mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 16:36:21 +02:00
Feat: TrustGraph i18n & Documentation Translation Updates (#781)
Native CLI i18n: The TrustGraph CLI has built-in translation support that dynamically loads language strings. You can test and use different languages by simply passing the --lang flag (e.g., --lang es for Spanish, --lang ru for Russian) or by configuring your environment's LANG variable. Automated Docs Translations: This PR introduces autonomously translated Markdown documentation into several target languages, including Spanish, Swahili, Portuguese, Turkish, Hindi, Hebrew, Arabic, Simplified Chinese, and Russian.
This commit is contained in:
Alex Jenkins
GitHub
parent
19f73e4cdc
commit
f95fd4f052
560 changed files with 236300 additions and 99 deletions
271
docs/tech-specs/query-time-explainability.tr.md
Normal file
271
docs/tech-specs/query-time-explainability.tr.md
Normal file
|
|
@ -0,0 +1,271 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Sorgu Zamanı Açıklanabilirlik"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Sorgu Zamanı Açıklanabilirlik
|
||||
|
||||
> **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.
|
||||
|
||||
## Durum
|
||||
|
||||
Uygulandı
|
||||
|
||||
## Genel Bakış
|
||||
|
||||
Bu özellik, GraphRAG'ın sorgu yürütülmesi sırasında açıklanabilirlik verilerini nasıl kaydettiğini ve ilettiğini açıklamaktadır. Amaç, nihai cevaptan başlayarak, seçilen kenarlara ve kaynak belgelere kadar tam bir izlenebilirlik sağlamaktır.
|
||||
|
||||
Sorgu zamanı açıklanabilirliği, GraphRAG boru hattının akıl yürütme sırasında neler yaptığını yakalar. Bu, bilginin nereden geldiğini kaydeden, çıkarma zamanı köken bilgilerine bağlanır.
|
||||
|
||||
## Terminoloji
|
||||
|
||||
| Terim | Tanım |
|
||||
|------|------------|
|
||||
| **Açıklanabilirlik** | Bir sonucun nasıl elde edildiğinin kaydı |
|
||||
| **Oturum** | Tek bir GraphRAG sorgu yürütmesi |
|
||||
| **Kenar Seçimi** | Akıl yürütmeyle ilgili kenarların LLM tarafından seçilmesi |
|
||||
| **Köken Zinciri** | Kenar → parça → sayfa → belge yolu |
|
||||
|
||||
## Mimari
|
||||
|
||||
### Açıklanabilirlik Akışı
|
||||
|
||||
```
|
||||
GraphRAG Query
|
||||
│
|
||||
├─► Session Activity
|
||||
│ └─► Query text, timestamp
|
||||
│
|
||||
├─► Retrieval Entity
|
||||
│ └─► All edges retrieved from subgraph
|
||||
│
|
||||
├─► Selection Entity
|
||||
│ └─► Selected edges with LLM reasoning
|
||||
│ └─► Each edge links to extraction provenance
|
||||
│
|
||||
└─► Answer Entity
|
||||
└─► Reference to synthesized response (in librarian)
|
||||
```
|
||||
|
||||
### İki Aşamalı GraphRAG İşlem Hattı
|
||||
|
||||
1. **Kenar Seçimi**: LLM, alt grafikten ilgili kenarları seçer ve her biri için bir gerekçe sunar.
|
||||
2. **Sentez**: LLM, yalnızca seçilen kenarlardan cevap oluşturur.
|
||||
|
||||
Bu ayrım, açıklanabilirliği sağlar - hangi kenarların katkıda bulunduğunu tam olarak biliyoruz.
|
||||
|
||||
### Depolama
|
||||
|
||||
Açıklanabilirlik üçlüleri, yapılandırılabilir bir koleksiyonda saklanır (varsayılan: `explainability`).
|
||||
Kaynak ilişkileri için PROV-O ontolojisi kullanılır.
|
||||
Kenar referansları için RDF-star yeniden tanımlaması.
|
||||
Cevap içeriği, kütüphaneci hizmetinde saklanır (satır içi değil - çok büyük).
|
||||
|
||||
### Gerçek Zamanlı Akış
|
||||
|
||||
Açıklanabilirlik olayları, sorgu yürütüldüğü sırada istemciye akış olarak gönderilir:
|
||||
|
||||
1. Oturum oluşturuldu → olay gönderildi.
|
||||
2. Kenarlar alındı → olay gönderildi.
|
||||
3. Gerekçeyle birlikte kenarlar seçildi → olay gönderildi.
|
||||
4. Cevap oluşturuldu → olay gönderildi.
|
||||
|
||||
İstemci, `explain_id` ve `explain_collection`'i tam ayrıntıları almak için kullanır.
|
||||
|
||||
## URI Yapısı
|
||||
|
||||
Tüm URI'ler, UUID'lerle birlikte `urn:trustgraph:` ad alanını kullanır:
|
||||
|
||||
| Varlık | URI Kalıbı |
|
||||
|--------|-------------|
|
||||
| Oturum | `urn:trustgraph:session:{uuid}` |
|
||||
| Alma | `urn:trustgraph:prov:retrieval:{uuid}` |
|
||||
| Seçim | `urn:trustgraph:prov:selection:{uuid}` |
|
||||
| Cevap | `urn:trustgraph:prov:answer:{uuid}` |
|
||||
| Kenar Seçimi | `urn:trustgraph:prov:edge:{uuid}:{index}` |
|
||||
|
||||
## RDF Modeli (PROV-O)
|
||||
|
||||
### Oturum Etkinliği
|
||||
|
||||
```turtle
|
||||
<session-uri> a prov:Activity ;
|
||||
rdfs:label "GraphRAG query session" ;
|
||||
prov:startedAtTime "2024-01-15T10:30:00Z" ;
|
||||
tg:query "What was the War on Terror?" .
|
||||
```
|
||||
|
||||
### Veri Alma Varlığı
|
||||
|
||||
```turtle
|
||||
<retrieval-uri> a prov:Entity ;
|
||||
rdfs:label "Retrieved edges" ;
|
||||
prov:wasGeneratedBy <session-uri> ;
|
||||
tg:edgeCount 50 .
|
||||
```
|
||||
|
||||
### Seçim Varlığı
|
||||
|
||||
```turtle
|
||||
<selection-uri> a prov:Entity ;
|
||||
rdfs:label "Selected edges" ;
|
||||
prov:wasDerivedFrom <retrieval-uri> ;
|
||||
tg:selectedEdge <edge-sel-0> ;
|
||||
tg:selectedEdge <edge-sel-1> .
|
||||
|
||||
<edge-sel-0> tg:edge << <s> <p> <o> >> ;
|
||||
tg:reasoning "This edge establishes the key relationship..." .
|
||||
```
|
||||
|
||||
### Cevap Varlığı
|
||||
|
||||
```turtle
|
||||
<answer-uri> a prov:Entity ;
|
||||
rdfs:label "GraphRAG answer" ;
|
||||
prov:wasDerivedFrom <selection-uri> ;
|
||||
tg:document <urn:trustgraph:answer:{uuid}> .
|
||||
```
|
||||
|
||||
`tg:document`, kütüphaneci hizmetinde saklanan cevabı referans alır.
|
||||
|
||||
## Ad Alanı Sabitleri
|
||||
|
||||
`trustgraph-base/trustgraph/provenance/namespaces.py` içinde tanımlanmıştır:
|
||||
|
||||
| Sabit | URI |
|
||||
|----------|-----|
|
||||
| `TG_QUERY` | `https://trustgraph.ai/ns/query` |
|
||||
| `TG_EDGE_COUNT` | `https://trustgraph.ai/ns/edgeCount` |
|
||||
| `TG_SELECTED_EDGE` | `https://trustgraph.ai/ns/selectedEdge` |
|
||||
| `TG_EDGE` | `https://trustgraph.ai/ns/edge` |
|
||||
| `TG_REASONING` | `https://trustgraph.ai/ns/reasoning` |
|
||||
| `TG_CONTENT` | `https://trustgraph.ai/ns/content` |
|
||||
| `TG_DOCUMENT` | `https://trustgraph.ai/ns/document` |
|
||||
|
||||
## GraphRagResponse Şeması
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class GraphRagResponse:
|
||||
error: Error | None = None
|
||||
response: str = ""
|
||||
end_of_stream: bool = False
|
||||
explain_id: str | None = None
|
||||
explain_collection: str | None = None
|
||||
message_type: str = "" # "chunk" or "explain"
|
||||
end_of_session: bool = False
|
||||
```
|
||||
|
||||
### Mesaj Türleri
|
||||
|
||||
| mesaj_türü | Amaç |
|
||||
|--------------|---------|
|
||||
| `chunk` | Yanıt metni (akış veya son) |
|
||||
| `explain` | IRI referansıyla açıklanabilirlik olayı |
|
||||
|
||||
### Oturum Yaşam Döngüsü
|
||||
|
||||
1. Birden fazla `explain` mesajı (oturum, alma, seçim, yanıt)
|
||||
2. Birden fazla `chunk` mesajı (akış yanıtı)
|
||||
3. `end_of_session=True` ile birlikte son `chunk`
|
||||
|
||||
## Kenar Seçim Formatı
|
||||
|
||||
LLM, seçilen kenarlarla birlikte JSONL döndürür:
|
||||
|
||||
```jsonl
|
||||
{"id": "edge-hash-1", "reasoning": "This edge shows the key relationship..."}
|
||||
{"id": "edge-hash-2", "reasoning": "Provides supporting evidence..."}
|
||||
```
|
||||
|
||||
`id`, `(labeled_s, labeled_p, labeled_o)`'nin `edge_id()` tarafından hesaplanan bir karma değeridir.
|
||||
|
||||
## URI'nin Korunması
|
||||
|
||||
### Sorun
|
||||
|
||||
GraphRAG, LLM'ye okunabilir etiketler gösterir, ancak açıklanabilirlik, köken takibi için orijinal URI'lere ihtiyaç duyar.
|
||||
|
||||
### Çözüm
|
||||
|
||||
`get_labelgraph()`, şunları döndürür:
|
||||
`labeled_edges`: LLM için `(label_s, label_p, label_o)` listesi
|
||||
`uri_map`: `edge_id(labels)` → `(uri_s, uri_p, uri_o)` eşlemesini içeren sözlük
|
||||
|
||||
Açıklanabilirlik verilerini saklarken, `uri_map`'dan gelen URI'ler kullanılır.
|
||||
|
||||
## Köken Takibi
|
||||
|
||||
### Kaynaktan Kenara
|
||||
|
||||
Seçilen kenarlar, kaynak belgelere kadar izlenebilir:
|
||||
|
||||
1. İçeren alt grafiği sorgulayın: `?subgraph tg:contains <<s p o>>`
|
||||
2. Kök belgeye kadar `prov:wasDerivedFrom` zincirini izleyin
|
||||
3. Zincirdeki her adım: parça → sayfa → belge
|
||||
|
||||
### Cassandra Tırnaklı Üçlü Desteği
|
||||
|
||||
Cassandra sorgu hizmeti, tırnaklı üçlüleri eşleştirmeyi destekler:
|
||||
|
||||
```python
|
||||
# In get_term_value():
|
||||
elif term.type == TRIPLE:
|
||||
return serialize_triple(term.triple)
|
||||
```
|
||||
|
||||
Bu, şu tür sorguları mümkün kılar:
|
||||
```
|
||||
?subgraph tg:contains <<http://example.org/s http://example.org/p "value">>
|
||||
```
|
||||
|
||||
## CLI Kullanımı
|
||||
|
||||
```bash
|
||||
tg-invoke-graph-rag --explainable -q "What was the War on Terror?"
|
||||
```
|
||||
|
||||
### Çıktı Formatı
|
||||
|
||||
```
|
||||
[session] urn:trustgraph:session:abc123
|
||||
|
||||
[retrieval] urn:trustgraph:prov:retrieval:abc123
|
||||
|
||||
[selection] urn:trustgraph:prov:selection:abc123
|
||||
Selected 12 edge(s)
|
||||
Edge: (Guantanamo, definition, A detention facility...)
|
||||
Reason: Directly connects Guantanamo to the War on Terror
|
||||
Source: Chunk 1 → Page 2 → Beyond the Vigilant State
|
||||
|
||||
[answer] urn:trustgraph:prov:answer:abc123
|
||||
|
||||
Based on the provided knowledge statements...
|
||||
```
|
||||
|
||||
### Özellikler
|
||||
|
||||
Sorgu sırasında gerçek zamanlı açıklanabilirlik olayları
|
||||
`rdfs:label` aracılığıyla kenar bileşenleri için etiket çözümü
|
||||
`prov:wasDerivedFrom` aracılığıyla kaynak zinciri takibi
|
||||
Tekrarlanan sorguları önlemek için etiket önbelleği
|
||||
|
||||
## Uygulanan Dosyalar
|
||||
|
||||
| Dosya | Amaç |
|
||||
|------|---------|
|
||||
| `trustgraph-base/trustgraph/provenance/uris.py` | URI oluşturucular |
|
||||
| `trustgraph-base/trustgraph/provenance/namespaces.py` | RDF ad alanı sabitleri |
|
||||
| `trustgraph-base/trustgraph/provenance/triples.py` | Üçlü oluşturucular |
|
||||
| `trustgraph-base/trustgraph/schema/services/retrieval.py` | GraphRagResponse şeması |
|
||||
| `trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py` | URI korumasıyla temel GraphRAG |
|
||||
| `trustgraph-flow/trustgraph/retrieval/graph_rag/rag.py` | Kütüphaneci entegrasyonlu hizmet |
|
||||
| `trustgraph-flow/trustgraph/query/triples/cassandra/service.py` | Tırnaklı üçlü sorgu desteği |
|
||||
| `trustgraph-cli/trustgraph/cli/invoke_graph_rag.py` | Açıklanabilirlik gösterimiyle CLI |
|
||||
|
||||
## Referanslar
|
||||
|
||||
PROV-O (W3C Provenance Ontology): https://www.w3.org/TR/prov-o/
|
||||
RDF-star: https://w3c.github.io/rdf-star/
|
||||
Çıkarma zamanı kökeni: `docs/tech-specs/extraction-time-provenance.md`
|
||||
Loading…
Add table
Add a link
Reference in a new issue