trustgraph/docs/tech-specs/jsonl-prompt-output.tr.md

layout	title	parent
default	JSONL İstek Çıktısı Teknik Özellikleri	Turkish (Beta)

JSONL İstek Çıktısı Teknik Özellikleri

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

Genel Bakış

Bu özellik, TrustGraph'ta istek yanıtları için JSONL (JSON Lines) çıktı biçiminin uygulanmasını tanımlar. JSONL, LLM yanıtlarından yapılandırılmış verilerin, LLM yanıtları çıktı belirteç sınırlarına ulaştığında JSON dizisi çıktıları bozulduğunda ortaya çıkan kritik sorunları ele alarak, kesme hatalarına karşı dayanıklı bir şekilde çıkarılmasını sağlar.

Bu uygulama, aşağıdaki kullanım senaryolarını destekler:

1. Kesintiye Dayanıklı Çıkarma: LLM çıktısı yanıtın ortasında kesildiğinde bile geçerli kısmi sonuçları çıkarın.

2. Büyük Ölçekli Çıkarma: Token limitleri nedeniyle tam bir başarısızlık riski olmadan birçok öğenin çıkarılmasını işleyin.

3. Karma Tip Çıkarma: Tek bir istemde birden fazla varlık türünün (tanımlar, ilişkiler, varlıklar, özellikler) çıkarılmasını destekleyin.

4. Akışla Uyumlu Çıktı: Çıkarma sonuçlarının gelecekteki akış/artımlı işlenmesini sağlayın.

Hedefler

<<<<<<< HEAD Geriye Dönük Uyumluluk: response-type: "text" kullanan mevcut istemler ve response-type: "json", herhangi bir değişiklik yapılmadan çalışmaya devam eder. Kesinti Dayanıklılığı: Kısmi LLM çıktıları, tam bir başarısızlık yerine kısmi, geçerli sonuçlar üretir.

Şema Doğrulama: Bireysel nesneler için JSON şema doğrulamasını destekler. Ayırıcı Birleşimler: type alanını kullanarak karma türlü çıktıları destekler.

Minimum API Değişiklikleri: Mevcut istem yapılandırmasını, yeni yanıt türü ve şema anahtarıyla genişletir.

Geriye Dönük Uyumluluk: response-type: "text" ve response-type: "json" kullanan mevcut istemler, herhangi bir değişiklik yapılmadan çalışmaya devam eder. Kesme Direnci: Kısmi LLM çıktıları, tam bir başarısızlık yerine, kısmi geçerli sonuçlar üretir.

Şema Doğrulama: Bireysel nesneler için JSON Şema doğrulamasını destekleyin. Ayırıcı Birleşimler: type alanı kullanılarak farklı türlerde çıktıları destekleyin. ayırıcı. Minimum API Değişiklikleri: Mevcut istem yapılandırmasını yeni yanıt türü ve şema anahtarıyla genişletin.

82edf2d (New md files from RunPod)

Arka Plan

Mevcut Mimari

İstek hizmeti, iki tür yanıtı destekler:

1. response-type: "text" - Ham metin yanıtı, olduğu gibi döndürülür.
2. response-type: "json" - Yanıttan ayrıştırılan JSON, isteğe bağlı response-type: "json"'a göre doğrulanır. isteğe bağlı schema

<<<<<<< HEAD trustgraph-flow/trustgraph/template/prompt_manager.py'daki mevcut uygulama:

Mevcut uygulama trustgraph-flow/trustgraph/template/prompt_manager.py içinde:

82edf2d (New md files from RunPod)

class Prompt:
    def __init__(self, template, response_type = "text", terms=None, schema=None):
        self.template = template
        self.response_type = response_type
        self.terms = terms
        self.schema = schema

Mevcut Sınırlamalar

Çıkarma komutları, çıktıyı JSON dizileri ([{...}, {...}, ...]) olarak istediğinde:

<<<<<<< HEAD Kesme nedeniyle oluşan bozulma: Eğer LLM, dizi ortasında çıktı belirteç sınırlarına ulaştığında, tüm yanıt geçersiz bir JSON haline gelir ve işlenemez. Tümünü veya hiçbirini işleme: İşlemeye başlamadan önce tam çıktıyı almanız gerekir. Kısmi sonuçlar yok: Kesilmiş bir yanıt, kullanılabilir veri olarak sıfır veri verir. Büyük çıkarmalar için güvenilir değil: Çıkarılan öğe sayısı arttıkça, başarısızlık riski daha yüksektir.

Kesme bozulması: Eğer LLM, dizi ortasında çıktı belirteç sınırlarına ulaştığında, tüm yanıt geçersiz bir JSON haline gelir ve işlenemez. Tüm veya hiçbir işleme: İşlemeye başlamadan önce tam çıktının alınması gerekir. Kısmi sonuçlar yok: Kesilmiş bir yanıt, kullanılabilir veri olarak sıfır veri verir. Büyük çıkarmalar için güvenilir değil: Çıkarılan öğe sayısı arttıkça, başarısızlık riski artar.

82edf2d (New md files from RunPod)

Bu özellik, her çıkarılan öğenin kendi satırında bulunan tam bir JSON nesnesi olduğu JSONL formatını kullanarak, bu sınırlamaları ele alır.

Teknik Tasarım

Yanıt Tipi Genişletmesi

Mevcut "text" ve "json" türlerinin yanı sıra yeni bir yanıt türü "jsonl" ekleyin.

<<<<<<< HEAD

Yapılandırma Değişiklikleri

=======

Yapılandırma Değişiklikleri

Yeni yanıt türü değeri:

82edf2d (New md files from RunPod)

"response-type": "jsonl"

Şema yorumlaması:

Mevcut "schema" anahtarı, hem "json" hem de "jsonl" yanıtları için kullanılmaktadır. Yorumlama, yanıt türüne bağlıdır:

"json": Şema, tüm yanıtı (genellikle bir dizi veya nesne) tanımlar. "jsonl": Şema, her bir satırı/nesneyi ayrı ayrı tanımlar.

{
  "response-type": "jsonl",
  "schema": {
    "type": "object",
    "properties": {
      "entity": { "type": "string" },
      "definition": { "type": "string" }
    },
    "required": ["entity", "definition"]
  }
}

Bu, istem yapılandırma araçlarına ve düzenleyicilere yapılan değişiklikleri önler.

JSONL Biçim Özellikleri

Basit Çıkarma

Tek bir nesne türünü (tanımlar, ilişkiler, konular, satırlar) çıkaran istemler için, çıktı her satırda bir JSON nesnesidir ve herhangi bir sarma bulunmaz:

İstem çıktı biçimi:

{"entity": "photosynthesis", "definition": "Process by which plants convert sunlight"}
{"entity": "chlorophyll", "definition": "Green pigment in plants"}
{"entity": "mitochondria", "definition": "Powerhouse of the cell"}

Önceki JSON dizi formatıyla karşılaştırma:

[
  {"entity": "photosynthesis", "definition": "Process by which plants convert sunlight"},
  {"entity": "chlorophyll", "definition": "Green pigment in plants"},
  {"entity": "mitochondria", "definition": "Powerhouse of the cell"}
]

<<<<<<< HEAD Eğer LLM, 2. satırdan sonra kesilirse, JSON dizisi formatı geçersiz bir JSON oluşturur, ancak JSONL iki geçerli nesne üretir.

Karışık Tip Çıkarımı (Ayırıcı Birleşimler)

Birden fazla nesne türünü çıkaran (örneğin, hem tanımları hem de ilişkileri, veya varlıklar, ilişkiler ve özellikler) istemler için, bir "type"

Eğer LLM, 2. satırdan sonra kesilirse, JSON dizisi formatı geçersiz bir JSON oluştururken, JSONL ise iki geçerli nesne üretir.

Karışık Tip Çıkarımı (Ayırıcı Birleşimler)

Birden fazla nesne türünü çıkaran (örneğin, hem tanımları ve ilişkiler veya varlıklar, ilişkiler ve özellikler) istemler için, bir "type"

82edf2d (New md files from RunPod) alanını ayırıcı olarak kullanın:

İstem çıktısı formatı:

{"type": "definition", "entity": "DNA", "definition": "Molecule carrying genetic instructions"}
{"type": "relationship", "subject": "DNA", "predicate": "located_in", "object": "cell nucleus", "object-entity": true}
{"type": "definition", "entity": "RNA", "definition": "Molecule that carries genetic information"}
{"type": "relationship", "subject": "RNA", "predicate": "transcribed_from", "object": "DNA", "object-entity": true}

Ayırıcı birleşimler için şema, oneOf kullanır:

{
  "response-type": "jsonl",
  "schema": {
    "oneOf": [
      {
        "type": "object",
        "properties": {
          "type": { "const": "definition" },
          "entity": { "type": "string" },
          "definition": { "type": "string" }
        },
        "required": ["type", "entity", "definition"]
      },
      {
        "type": "object",
        "properties": {
          "type": { "const": "relationship" },
          "subject": { "type": "string" },
          "predicate": { "type": "string" },
          "object": { "type": "string" },
          "object-entity": { "type": "boolean" }
        },
        "required": ["type", "subject", "predicate", "object", "object-entity"]
      }
    ]
  }
}

Ontoloji Çıkarımı

Varlıklar, ilişkiler ve özelliklerle ontoloji tabanlı çıkarım için:

İstenen çıktı formatı:

{"type": "entity", "entity": "Cornish pasty", "entity_type": "fo/Recipe"}
{"type": "entity", "entity": "beef", "entity_type": "fo/Food"}
{"type": "relationship", "subject": "Cornish pasty", "subject_type": "fo/Recipe", "relation": "fo/has_ingredient", "object": "beef", "object_type": "fo/Food"}
{"type": "attribute", "entity": "Cornish pasty", "entity_type": "fo/Recipe", "attribute": "fo/serves", "value": "4 people"}

Uygulama Detayları

İstek Sınıfı

Mevcut Prompt sınıfı herhangi bir değişiklik gerektirmiyor. schema alanı yeniden kullanılıyor. JSONL formatı için, yorumlanması response_type ile belirlenir:

class Prompt:
    def __init__(self, template, response_type="text", terms=None, schema=None):
        self.template = template
        self.response_type = response_type
        self.terms = terms
        self.schema = schema  # Interpretation depends on response_type

PromptManager.load_config

Herhangi bir değişiklik gerekli değil - mevcut yapılandırma yüklemesi zaten schema anahtarını işlemektedir.

JSONL Ayrıştırma

JSONL yanıtları için yeni bir ayrıştırma yöntemi ekleyin:

def parse_jsonl(self, text):
    """
    Parse JSONL response, returning list of valid objects.

    Invalid lines (malformed JSON, empty lines) are skipped with warnings.
    This provides truncation resilience - partial output yields partial results.
    """
    results = []

    for line_num, line in enumerate(text.strip().split('\n'), 1):
        line = line.strip()

        # Skip empty lines
        if not line:
            continue

        # Skip markdown code fence markers if present
        if line.startswith('```'):
            continue

        try:
            obj = json.loads(line)
            results.append(obj)
        except json.JSONDecodeError as e:
            # Log warning but continue - this provides truncation resilience
            logger.warning(f"JSONL parse error on line {line_num}: {e}")

    return results

PromptManager.invoke Değişiklikleri

Yeni yanıt türünü işleyebilmek için invoke yöntemini genişletin:

async def invoke(self, id, input, llm):
    logger.debug("Invoking prompt template...")

    terms = self.terms | self.prompts[id].terms | input
    resp_type = self.prompts[id].response_type

    prompt = {
        "system": self.system_template.render(terms),
        "prompt": self.render(id, input)
    }

    resp = await llm(**prompt)

    if resp_type == "text":
        return resp

    if resp_type == "json":
        try:
            obj = self.parse_json(resp)
        except:
            logger.error(f"JSON parse failed: {resp}")
            raise RuntimeError("JSON parse fail")

        if self.prompts[id].schema:
            try:
                validate(instance=obj, schema=self.prompts[id].schema)
                logger.debug("Schema validation successful")
            except Exception as e:
                raise RuntimeError(f"Schema validation fail: {e}")

        return obj

    if resp_type == "jsonl":
        objects = self.parse_jsonl(resp)

        if not objects:
            logger.warning("JSONL parse returned no valid objects")
            return []

        # Validate each object against schema if provided
        if self.prompts[id].schema:
            validated = []
            for i, obj in enumerate(objects):
                try:
                    validate(instance=obj, schema=self.prompts[id].schema)
                    validated.append(obj)
                except Exception as e:
                    logger.warning(f"Object {i} failed schema validation: {e}")
            return validated

        return objects

    raise RuntimeError(f"Response type {resp_type} not known")

Etkilenen İstekler

Aşağıdaki istekler JSONL formatına aktarılmalıdır:

İstek Kimliği	Açıklama	Tür Alanı
extract-definitions	Varlık/tanım çıkarma	Hayır (tek tür)
extract-relationships	İlişki çıkarma	Hayır (tek tür)
extract-topics	Konu/tanım çıkarma	Hayır (tek tür)
extract-rows	Yapılandırılmış satır çıkarma	Hayır (tek tür)
agent-kg-extract	Birleştirilmiş tanım + ilişki çıkarma	Evet: "definition", "relationship"
extract-with-ontologies / ontology-extract	Ontoloji tabanlı çıkarma	Evet: "entity", "relationship", "attribute"

API Değişiklikleri

Müşteri Perspektifi

<<<<<<< HEAD JSONL ayrıştırması, istem hizmeti API'sini kullananlar için şeffaftır. Ayrıştırma, istem hizmetinde sunucu tarafında gerçekleşir ve yanıt standart bir şekilde döndürülür. PromptResponse.object alanını seri hale edilmiş bir JSON dizisi olarak.

Müşteriler, istem hizmetini (PromptClient.prompt() veya benzeri bir yöntemle) kullandığında:

response-type: "json" (dizi şeması ile) → müşteri, Python list alır. response-type: "jsonl" → müşteri, Python list alır.

Müşterinin bakış açısıyla, her iki yöntem de aynı veri yapılarını döndürür. Fark, tamamen LLM çıktısının sunucu tarafında nasıl işlendiğindedir:

JSON dizisi formatı: Tek json.loads() çağrısı; kısaltılırsa tamamen başarısız olur. JSONL formatı: Satır satır ayrıştırma; kısaltılırsa kısmi sonuçlar verir.

Bu, çıkarma istemlerinden bir liste bekleyen mevcut istemci kodunun, istemleri JSON'dan JSONL formatına geçirirken herhangi bir değişikliğe ihtiyaç duymamasını sağlar.

Sunucu Dönüş Değeri

response-type: "jsonl" için, PromptManager.invoke() metodu, başarıyla ayrıştırılmış ve doğrulanmış tüm nesneleri içeren bir list[dict] döndürür. Bu liste, daha sonra PromptResponse.object alanı için JSON'a dönüştürülür.

Hata Yönetimi

Boş sonuçlar: Uyarı günlüğü ile boş bir liste [] döndürür. Kısmi ayrıştırma hatası: Başarıyla ayrıştırılmış nesnelerin bir listesini ve hatalar için uyarı günlüklerini döndürür. Tam ayrıştırma hatası: Uyarı günlükleriyle boş bir liste [] döndürür.

Bu, response-type: "json"'den farklıdır, çünkü RuntimeError ayrıştırma hatası durumunda RuntimeError hatası oluşturur. JSONL için daha hoşgörülü davranış, kesintilere karşı dayanıklılık sağlamak amacıyla kasıtlıdır.

JSONL ayrıştırması, istek hizmeti API kullanıcıları için şeffaftır. Ayrıştırma, isteğin sunucu tarafında gerçekleşir ve yanıt, standart PromptResponse.object alanı aracılığıyla seri hale getirilmiş bir JSON dizisi olarak döndürülür.

Müşteriler, istek hizmetini (PromptClient.prompt() veya benzeri aracılığıyla) çağırdığında:

response-type: "json" dizi şeması ile → müşteri, Python list alır response-type: "jsonl" → müşteri, Python list alır

Müşteri açısından, her iki yöntem de aynı veri yapılarını döndürür. Fark, yalnızca LLM çıktısının sunucu tarafında nasıl ayrıştırıldığıdır:

JSON dizisi formatı: Tek json.loads() çağrısı; kesintiye uğratılırsa tamamen başarısız olur JSONL formatı: Satır satır ayrıştırma; kesintiye uğratılırsa kısmi sonuçlar verir

Bu, çıkarma isteklerinden gelen listeleri bekleyen mevcut müşteri kodunun, istekleri JSON'dan JSONL formatına geçirirken herhangi bir değişikliğe ihtiyaç duymamasını sağlar.

Sunucu Dönüş Değeri

response-type: "jsonl" için, PromptManager.invoke() yöntemi bir list[dict] döndürür ve bu, başarıyla ayrıştırılmış ve doğrulanmış tüm nesneleri içerir. Bu liste daha sonra PromptResponse.object alanı için JSON'a seri hale getirilir.

Hata Yönetimi

Boş sonuçlar: Uyarı günlüğü ile boş bir liste [] döndürülür Kısmi ayrıştırma hatası: Başarıyla ayrıştırılmış nesnelerin listesi, hatalar için uyarı günlükleriyle birlikte döndürülür Tam ayrıştırma hatası: Uyarı günlükleriyle boş bir liste [] döndürülür

Bu, ayrıştırma hatası durumunda RuntimeError'i yükselten response-type: "json"'dan farklıdır. JSONL için esnek davranış, kesintiye karşı dayanıklılık sağlamak için kasıtlıdır.

82edf2d (New md files from RunPod)

Yapılandırma Örneği

<<<<<<< HEAD Tam istem yapılandırma örneği:

Tam istek yapılandırma örneği:

82edf2d (New md files from RunPod)

{
  "prompt": "Extract all entities and their definitions from the following text. Output one JSON object per line.\n\nText:\n{{text}}\n\nOutput format per line:\n{\"entity\": \"<name>\", \"definition\": \"<definition>\"}",
  "response-type": "jsonl",
  "schema": {
    "type": "object",
    "properties": {
      "entity": {
        "type": "string",
        "description": "The entity name"
      },
      "definition": {
        "type": "string",
        "description": "A clear definition of the entity"
      }
    },
    "required": ["entity", "definition"]
  }
}

Güvenlik Hususları

Girdi Doğrulama: JSON ayrıştırması, standart json.loads()'ı kullanır ve bu, enjeksiyon saldırılarına karşı güvenlidir. Şema Doğrulama: Şema zorlaması için ⟦CODE_0⟧ kullanılır. Şema Doğrulama: Şema uyumluluğunu sağlamak için jsonschema.validate() kullanılır. Yeni Bir Saldırı Yüzeyi Yok: JSONL ayrıştırması, satır satır işlenmesi nedeniyle JSON dizisi ayrıştırmasından çok daha güvenlidir.

Performans Hususları

Bellek: Satır satır ayrıştırma, tam JSON dizilerini yüklemekten daha az bellek kullanır. <<<<<<< HEAD Gecikme: Ayrıştırma performansı, JSON dizisi ayrıştırmasıyla karşılaştırılabilir. Doğrulama: Şema doğrulaması, her bir nesne için yapılır, bu da ek yük getirir ancak doğrulama başarısız olduğunda kısmi sonuçlar elde etmeyi sağlar.

Test Stratejisi

=======

Gecikme: Ayrıştırma performansı, JSON dizisi ayrıştırmasıyla karşılaştırılabilir. Doğrulama: Şema doğrulaması, her bir nesne için yapılır, bu da ek yük getirir ancak doğrulama başarısız olduğunda kısmi sonuçlar elde etmeyi sağlar.

Test Stratejisi

82edf2d (New md files from RunPod)

Birim Testleri

Geçerli giriş ile JSONL ayrıştırma Boş satırlarla JSONL ayrıştırma Markdown kod bloklarıyla JSONL ayrıştırma Kesilmiş son satırla JSONL ayrıştırma Geçersiz JSON satırlarının arasına serpiştirilmiş JSONL ayrıştırma oneOf ayrımcı birleşimlerle şema doğrulaması Geriye dönük uyumluluk: Mevcut "text" ve "json" istemleri değişmeden kalır

Entegrasyon Testleri

JSONL istemleriyle uçtan uca çıkarma Simüle edilmiş kesme ile çıkarma (yapay olarak sınırlı yanıt) Tür ayrımcısı ile karma tür çıkarma Üç türün tamamıyla ontoloji çıkarma

Çıkarma Kalitesi Testleri

Çıkarma sonuçlarını karşılaştırın: JSONL ile JSON dizisi formatı Kesme dayanıklılığını doğrulayın: JSONL, JSON'un başarısız olduğu durumlarda kısmi sonuçlar verir

Geçiş Planı

1. Aşama: Uygulama

1. parse_jsonl() yöntemini PromptManager içinde uygulayın
2. invoke()'ı response-type: "jsonl"'i işleyebilecek şekilde genişletin
3. Birim testleri ekleyin

2. Aşama: İstek Geçişi

1. extract-definitions isteğini ve yapılandırmasını güncelleyin
2. extract-relationships isteğini ve yapılandırmasını güncelleyin
3. extract-topics isteğini ve yapılandırmasını güncelleyin
4. extract-rows isteğini ve yapılandırmasını güncelleyin
5. agent-kg-extract isteğini ve yapılandırmasını güncelleyin
6. extract-with-ontologies isteğini ve yapılandırmasını güncelleyin

3. Aşama: Aşağı Akış Güncellemeleri

1. Çıkarma sonuçlarını kullanan tüm kodu, liste dönüş türünü işleyebilecek şekilde güncelleyin <<<<<<< HEAD
2. type alanına göre karma türdeki çıkarma sonuçlarını kategorize eden kodu güncelleyin =======
3. type alanıyla karma türdeki çıkarma türlerini sınıflandıran kodu güncelleyin

82edf2d (New md files from RunPod)

3. Çıkarma çıktısı formatı hakkında doğrulama yapan testleri güncelleyin

Açık Sorular

Şu anda yok.

Referanslar

Mevcut uygulama: trustgraph-flow/trustgraph/template/prompt_manager.py JSON Lines belirtimi: https://jsonlines.org/ JSON Şeması oneOf: https://json-schema.org/understanding-json-schema/reference/combining.html#oneof İlgili belirtim: Streaming LLM Responses (docs/tech-specs/streaming-llm-responses.md)