2026-04-10 12:22:20 -04:00
# JSONL İstek Çı ı ı
## Genel Bakı
Bu özellik, TrustGraph'ta istek yanı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı ı
Bu uygulama, aşağı ı ı ı
1. **Kesintiye Dayanı ı ı : LLM çı ı ı ı ı ı ı ı ı ı
2. **Büyük Ölçekli Çı : Token limitleri nedeniyle tam bir başarı ı ı ı ı ı ı
3. **Karma Tip Çı : Tek bir istemde birden fazla varlı ı ı ı ı ı ı
4. **Akı ı ı : Çı ı ı ı ı ı
işlenmesini sağlayı
## Hedefler
2026-04-11 01:08:44 +00:00
< < < < < < < HEAD
2026-04-10 12:22:20 -04:00
**Geriye Dönük Uyumluluk**: `response-type: "text"` kullanan mevcut istemler ve
`response-type: "json"` , herhangi bir değişiklik yapı ı
**Kesinti Dayanı ı ı ı ı ı ı ı ı ı ı ı
**Şema Doğrulama**: Bireysel nesneler için JSON şema doğrulaması ı
**Ayı ı ı `type` alanı ı ı ı ı
**Minimum API Değişiklikleri**: Mevcut istem yapı ı ı ı
yanı ı
2026-04-11 01:08:44 +00:00
=======
**Geriye Dönük Uyumluluk**: `response-type: "text"` ve
`response-type: "json"` kullanan mevcut istemler, herhangi bir değişiklik yapı ı
**Kesme Direnci**: Kı ı ı ı ı ı ı ı
**Şema Doğrulama**: Bireysel nesneler için JSON Şema doğrulaması ı
**Ayı ı ı `type` alanı ı ı ı ı ı
ayı ı ı
**Minimum API Değişiklikleri**: Mevcut istem yapı ı ı ı
yanı ı
>>>>>>> 82edf2d (New md files from RunPod)
2026-04-10 12:22:20 -04:00
## Arka Plan
### Mevcut Mimari
İstek hizmeti, iki tür yanı ı
1. `response-type: "text"` - Ham metin yanı ı
2. `response-type: "json"` - Yanı ı ı ı ı `response-type: "json"` 'a göre doğrulanı
isteğe bağlı `schema`
2026-04-11 01:08:44 +00:00
< < < < < < < HEAD
2026-04-10 12:22:20 -04:00
`trustgraph-flow/trustgraph/template/prompt_manager.py` 'daki mevcut uygulama:
2026-04-11 01:08:44 +00:00
=======
Mevcut uygulama `trustgraph-flow/trustgraph/template/prompt_manager.py` içinde:
>>>>>>> 82edf2d (New md files from RunPod)
2026-04-10 12:22:20 -04:00
```python
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ı ı
Çı ı ı ı ı `[{...}, {...}, ...]` ) olarak istediğinde:
2026-04-11 01:08:44 +00:00
< < < < < < < HEAD
2026-04-10 12:22:20 -04:00
**Kesme nedeniyle oluşan bozulma**: Eğer LLM, dizi ortası ı ı ı ı ı ı ı
tüm yanı
**Tümünü veya hiçbirini işleme**: İşlemeye başlamadan önce tam çı ı ı ı
**Kı ı ı ı ı
**Büyük çı ı ı ı ı ı ı ı ı
2026-04-11 01:08:44 +00:00
=======
**Kesme bozulması ı ı ı ı ı ı ı ı
tüm yanı
**Tüm veya hiçbir işleme**: İşlemeye başlamadan önce tam çı ı ı ı ı
**Kı ı ı ı ı
**Büyük çı ı ı ı ı ı ı ı ı
>>>>>>> 82edf2d (New md files from RunPod)
2026-04-10 12:22:20 -04:00
Bu özellik, her çı ı ı ı ı ı ı ı ı ı
## Teknik Tasarı
### Yanı
Mevcut `"text"` ve `"json"` türlerinin yanı ı ı `"jsonl"` ekleyin.
2026-04-11 01:08:44 +00:00
< < < < < < < HEAD
2026-04-10 12:22:20 -04:00
#### Yapı ı
2026-04-11 01:08:44 +00:00
=======
#### Yapı ı
**Yeni yanı
>>>>>>> 82edf2d (New md files from RunPod)
2026-04-10 12:22:20 -04:00
```
"response-type": "jsonl"
```
**Şema yorumlaması
Mevcut `"schema"` anahtarı `"json"` hem de `"jsonl"` yanı ı ı ı
Yorumlama, yanı ı ı
`"json"` : Şema, tüm yanı ı ı
`"jsonl"` : Şema, her bir satı ı ı ı ı
```json
{
"response-type": "jsonl",
"schema": {
"type": "object",
"properties": {
"entity": { "type": "string" },
"definition": { "type": "string" }
},
"required": ["entity", "definition"]
}
}
```
Bu, istem yapı ı ı ı
### JSONL Biçim Özellikleri
#### Basit Çı
Tek bir nesne türünü (tanı
konular, satı ı ı ı ı
**İstem çı ı
```
{"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ı ı ı
```json
[
{"entity": "photosynthesis", "definition": "Process by which plants convert sunlight"},
{"entity": "chlorophyll", "definition": "Green pigment in plants"},
{"entity": "mitochondria", "definition": "Powerhouse of the cell"}
]
```
2026-04-11 01:08:44 +00:00
< < < < < < < HEAD
2026-04-10 12:22:20 -04:00
Eğer LLM, 2. satı ı
ancak JSONL iki geçerli nesne üretir.
#### Karı ı ı ı ı ı ı ı
Birden fazla nesne türünü çı ı ı
ilişkileri, veya varlı `"type"`
2026-04-11 01:08:44 +00:00
=======
Eğer LLM, 2. satı ı
JSONL ise iki geçerli nesne üretir.
#### Karı ı ı ı ı ı ı ı
Birden fazla nesne türünü çı ı ı
ilişkiler veya varlı `"type"`
>>>>>>> 82edf2d (New md files from RunPod)
2026-04-10 12:22:20 -04:00
alanı ı ı ı ı ı
**İstem çı ı ı ı
```
{"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ı ı ı `oneOf` kullanı
```json
{
"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 Çı ı ı
Varlı ı ı ı
**İstenen çı ı ı
```
{"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ı ı ı
Mevcut `Prompt` sı ı ı `schema` alanı ı ı
JSONL formatı ı `response_type` ile belirlenir:
```python
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ı ı
`schema` anahtarı ı
#### JSONL Ayrı ı
JSONL yanı ı ı ı
```python
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ı
```python
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ğı ı ı ı ı
| İstek Kimliği | Açı ı
|-----------|-------------|------------|
| `extract-definitions` | Varlı ı ı ı
| `extract-relationships` | İlişki çı ı
| `extract-topics` | Konu/tanı ı ı
| `extract-rows` | Yapı ı ı ı ı ı ı
| `agent-kg-extract` | Birleştirilmiş tanı ı `"definition"` , `"relationship"` |
| `extract-with-ontologies` / `ontology-extract` | Ontoloji tabanlı ı `"entity"` , `"relationship"` , `"attribute"` |
### API Değişiklikleri
#### Müşteri Perspektifi
2026-04-11 01:08:44 +00:00
< < < < < < < HEAD
2026-04-10 12:22:20 -04:00
JSONL ayrı ı ı ı ı ı ı ı
bir şekilde döndürülür.
`PromptResponse.object` alanı ı
Müşteriler, istem hizmetini (`PromptClient.prompt()` veya benzeri bir yöntemle) kullandı ı
**`response-type: "json"` ** (dizi şeması `list` alı
**`response-type: "jsonl"` ** → müşteri, Python `list` alı
Müşterinin bakı ı ı ı ı ı ı
Fark, tamamen LLM çı ı ı ı ı ı
JSON dizisi formatı `json.loads()` çağrı ı ı ı ı ı ı
JSONL formatı ı ı ı ı ı ı ı ı
Bu, çı ı ı ı
#### Sunucu Dönüş Değeri
`response-type: "jsonl"` için, `PromptManager.invoke()` metodu,
başarı ı ı ı ı ı `list[dict]` döndürür. Bu
liste, daha sonra `PromptResponse.object` alanı
#### Hata Yönetimi
Boş sonuçlar: Uyarı `[]` döndürür.
Kı ı ı ı ı ı ı ı ı
hatalar için uyarı
Tam ayrı ı ı ı `[]` döndürür.
Bu, `response-type: "json"` 'den farklı ı `RuntimeError` ayrı ı ı `RuntimeError` hatası
JSONL için daha hoşgörülü davranı ı ı ı ı ı ı ı ı
2026-04-11 01:08:44 +00:00
=======
JSONL ayrı ı ı ı ı ı ı ı ı
sunucu tarafı ı
`PromptResponse.object` alanı ı ı ı
Müşteriler, istek hizmetini (`PromptClient.prompt()` veya benzeri aracı ı ı ı ı ı
**`response-type: "json"` ** dizi şeması `list` alı
**`response-type: "jsonl"` ** → müşteri, Python `list` alı
Müşteri açı ı ı ı ı ı ı ı ı ı ı
sunucu tarafı ı ı ı ı ı ı ı
JSON dizisi formatı `json.loads()` çağrı ı ı ı ı ı
JSONL formatı ı ı ı ı ı ı ı
Bu, çı
istekleri JSON'dan JSONL formatı ı ı
#### 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ı ı ı ı ı ı
Bu liste daha sonra `PromptResponse.object` alanı
#### Hata Yönetimi
Boş sonuçlar: Uyarı `[]` döndürülür
Kı ı ı ı ı ı ı ı ı
uyarı
Tam ayrı ı ı ı `[]` döndürülür
Bu, ayrı ı ı `RuntimeError` 'i yükselten `response-type: "json"` 'dan farklı ı
JSONL için esnek davranı ı ı ı ı ı ı ı
>>>>>>> 82edf2d (New md files from RunPod)
2026-04-10 12:22:20 -04:00
### Yapı ı
2026-04-11 01:08:44 +00:00
< < < < < < < HEAD
2026-04-10 12:22:20 -04:00
Tam istem yapı ı
2026-04-11 01:08:44 +00:00
=======
Tam istek yapı ı
>>>>>>> 82edf2d (New md files from RunPod)
2026-04-10 12:22:20 -04:00
```json
{
"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ı ı ı `json.loads()` 'ı ı ı ı ı ı
**Şema Doğrulama** : Şema zorlaması ı ı
**Şema Doğrulama**: Şema uyumluluğunu sağlamak için `jsonschema.validate()` kullanı ı
**Yeni Bir Saldı ı ı ı ı ı ı ı ı ı
## Performans Hususları
**Bellek**: Satı ı ı ı ı
2026-04-11 01:08:44 +00:00
< < < < < < < HEAD
2026-04-10 12:22:20 -04:00
**Gecikme** : Ayrı ı ı ı ı ı ı ı ı
**Doğrulama**: Şema doğrulaması ı ı
doğrulama başarı ı ı
## Test Stratejisi
2026-04-11 01:08:44 +00:00
=======
**Gecikme**: Ayrı ı ı ı ı ı ı ı ı
**Doğrulama**: Şema doğrulaması ı ı
doğrulama başarı ı ı
## Test Stratejisi
>>>>>>> 82edf2d (New md files from RunPod)
2026-04-10 12:22:20 -04:00
### Birim Testleri
Geçerli giriş ile JSONL ayrı ı
Boş satı ı ı
Markdown kod blokları ı ı
Kesilmiş son satı ı ı
Geçersiz JSON satı ı ı ı ı ı
`oneOf` ayrı ı ı
Geriye dönük uyumluluk: Mevcut `"text"` ve `"json"` istemleri değişmeden kalı
### Entegrasyon Testleri
JSONL istemleriyle uçtan uca çı
Simüle edilmiş kesme ile çı ı ı ı ı
Tür ayrı ı ı ı
Üç türün tamamı ı
### Çı
Çı ı ı ı ı ı ı
Kesme dayanı ı ı ı ı ı ı ı ı
## Geçiş Planı
### 1. Aşama: Uygulama
1. `parse_jsonl()` yöntemini `PromptManager` içinde uygulayı
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ı ı ı ı
2. `extract-relationships` isteğini ve yapı ı ı ı
3. `extract-topics` isteğini ve yapı ı ı ı
4. `extract-rows` isteğini ve yapı ı ı ı
5. `agent-kg-extract` isteğini ve yapı ı ı ı
6. `extract-with-ontologies` isteğini ve yapı ı ı ı
### 3. Aşama: Aşağı ı
1. Çı ı ı
2026-04-11 01:08:44 +00:00
< < < < < < < HEAD
2026-04-10 12:22:20 -04:00
2. `type` alanı ı ı ı
2026-04-11 01:08:44 +00:00
=======
2. `type` alanı ı ı ı ı
>>>>>>> 82edf2d (New md files from RunPod)
2026-04-10 12:22:20 -04:00
3. Çı ı ı ı ı ı
## Açı
Ş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` )
