mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 16:36:21 +02:00
8954fa3ad7
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.
280 lines
11 KiB
Markdown
280 lines
11 KiB
Markdown
---
|
||
layout: default
|
||
title: "Ajan Açıklanabilirliği: Kaynak Kaydı"
|
||
parent: "Turkish (Beta)"
|
||
---
|
||
|
||
# Ajan Açıklanabilirliği: Kaynak Kaydı
|
||
|
||
> **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ış
|
||
|
||
Ajan oturumlarının izlenebilmesi ve GraphRAG ile aynı açıklanabilirlik altyapısı kullanılarak hata ayıklanabilmesi için, React ajan döngüsüne kaynak kaydı ekleyin.
|
||
|
||
**Tasarım Kararları:**
|
||
- `urn:graph:retrieval`'a yazın (genel açıklanabilirlik grafiği)
|
||
- Şu anda doğrusal bağımlılık zinciri (analiz N → wasDerivedFrom → analiz N-1)
|
||
- Araçlar, kayıt alınmayan, opak kara kutulardır (sadece girdi/çıktı kaydedilir)
|
||
- DAG desteği, gelecekteki bir yinelemeye ertelenmiştir
|
||
|
||
## Varlık Türleri
|
||
|
||
Hem GraphRAG hem de Agent, TrustGraph'e özgü alt türlere sahip olan PROV-O'yu temel ontoloji olarak kullanır:
|
||
|
||
### GraphRAG Türleri
|
||
| Varlık | PROV-O Türü | TG Türleri | Açıklama |
|
||
|--------|-------------|----------|-------------|
|
||
| Soru | `prov:Activity` | `tg:Question`, `tg:GraphRagQuestion` | Kullanıcının sorgusu |
|
||
| Keşif | `prov:Entity` | `tg:Exploration` | Bilgi grafiğinden alınan kenarlar |
|
||
| Odak | `prov:Entity` | `tg:Focus` | Akıl yürütmeyle seçilen kenarlar |
|
||
| Sentez | `prov:Entity` | `tg:Synthesis` | Sonuç |
|
||
|
||
### Ajan Türleri
|
||
| Varlık | PROV-O Türü | TG Türleri | Açıklama |
|
||
|--------|-------------|----------|-------------|
|
||
| Soru | `prov:Activity` | `tg:Question`, `tg:AgentQuestion` | Kullanıcının sorgusu |
|
||
| Analiz | `prov:Entity` | `tg:Analysis` | Her düşünme/eylem/gözlem döngüsü |
|
||
| Sonuç | `prov:Entity` | `tg:Conclusion` | Sonuç |
|
||
|
||
### Belge RAG Türleri
|
||
| Varlık | PROV-O Türü | TG Türleri | Açıklama |
|
||
|--------|-------------|----------|-------------|
|
||
| Soru | `prov:Activity` | `tg:Question`, `tg:DocRagQuestion` | Kullanıcının sorgusu |
|
||
| Keşif | `prov:Entity` | `tg:Exploration` | Belge deposundan alınan parçalar |
|
||
| Sentez | `prov:Entity` | `tg:Synthesis` | Sonuç |
|
||
|
||
**Not:** Belge RAG, GraphRAG'ın türlerinin bir alt kümesini kullanır (kenar seçimi/akıl yürütme aşaması olmadığından Odak adımı yoktur).
|
||
|
||
### Soru Alt Türleri
|
||
|
||
Tüm Soru varlıkları `tg:Question`'ı temel tür olarak paylaşır, ancak geri alma mekanizmasını tanımlamak için özel bir alt türe sahiptir:
|
||
|
||
| Alt Tür | URI Kalıbı | Mekanizma |
|
||
|---------|-------------|-----------|
|
||
| `tg:GraphRagQuestion` | `urn:trustgraph:question:{uuid}` | Bilgi grafiği RAG |
|
||
| `tg:DocRagQuestion` | `urn:trustgraph:docrag:{uuid}` | Belge/parça RAG |
|
||
| `tg:AgentQuestion` | `urn:trustgraph:agent:{uuid}` | ReAct ajanı |
|
||
|
||
Bu, tüm soruların `tg:Question` aracılığıyla sorgulanabilmesini sağlarken, alt tür aracılığıyla belirli bir mekanizma ile filtrelenmesini sağlar.
|
||
|
||
## Kaynak Modeli
|
||
|
||
```
|
||
Question (urn:trustgraph:agent:{uuid})
|
||
│
|
||
│ tg:query = "User's question"
|
||
│ prov:startedAtTime = timestamp
|
||
│ rdf:type = prov:Activity, tg:Question
|
||
│
|
||
↓ prov:wasDerivedFrom
|
||
│
|
||
Analysis1 (urn:trustgraph:agent:{uuid}/i1)
|
||
│
|
||
│ tg:thought = "I need to query the knowledge base..."
|
||
│ tg:action = "knowledge-query"
|
||
│ tg:arguments = {"question": "..."}
|
||
│ tg:observation = "Result from tool..."
|
||
│ rdf:type = prov:Entity, tg:Analysis
|
||
│
|
||
↓ prov:wasDerivedFrom
|
||
│
|
||
Analysis2 (urn:trustgraph:agent:{uuid}/i2)
|
||
│ ...
|
||
↓ prov:wasDerivedFrom
|
||
│
|
||
Conclusion (urn:trustgraph:agent:{uuid}/final)
|
||
│
|
||
│ tg:answer = "The final response..."
|
||
│ rdf:type = prov:Entity, tg:Conclusion
|
||
```
|
||
|
||
### Belge RAG (Retrieval-Augmented Generation) Kaynak Modeli
|
||
|
||
```
|
||
Question (urn:trustgraph:docrag:{uuid})
|
||
│
|
||
│ tg:query = "User's question"
|
||
│ prov:startedAtTime = timestamp
|
||
│ rdf:type = prov:Activity, tg:Question
|
||
│
|
||
↓ prov:wasGeneratedBy
|
||
│
|
||
Exploration (urn:trustgraph:docrag:{uuid}/exploration)
|
||
│
|
||
│ tg:chunkCount = 5
|
||
│ tg:selectedChunk = "chunk-id-1"
|
||
│ tg:selectedChunk = "chunk-id-2"
|
||
│ ...
|
||
│ rdf:type = prov:Entity, tg:Exploration
|
||
│
|
||
↓ prov:wasDerivedFrom
|
||
│
|
||
Synthesis (urn:trustgraph:docrag:{uuid}/synthesis)
|
||
│
|
||
│ tg:content = "The synthesized answer..."
|
||
│ rdf:type = prov:Entity, tg:Synthesis
|
||
```
|
||
|
||
## Gerekli Değişiklikler
|
||
|
||
### 1. Şema Değişiklikleri
|
||
|
||
**Dosya:** `trustgraph-base/trustgraph/schema/services/agent.py`
|
||
|
||
`AgentRequest`'ye `session_id` ve `collection` alanlarını ekleyin:
|
||
```python
|
||
@dataclass
|
||
class AgentRequest:
|
||
question: str = ""
|
||
state: str = ""
|
||
group: list[str] | None = None
|
||
history: list[AgentStep] = field(default_factory=list)
|
||
user: str = ""
|
||
collection: str = "default" # NEW: Collection for provenance traces
|
||
streaming: bool = False
|
||
session_id: str = "" # NEW: For provenance tracking across iterations
|
||
```
|
||
|
||
**Dosya:** `trustgraph-base/trustgraph/messaging/translators/agent.py`
|
||
|
||
Çeviriciyi, `session_id` ve `collection`'i hem `to_pulsar()` hem de `from_pulsar()` içinde işleyebilecek şekilde güncelleyin.
|
||
|
||
### 2. Ajan Hizmetine Açıklanabilirlik Üreticisini Ekle
|
||
|
||
**Dosya:** `trustgraph-flow/trustgraph/agent/react/service.py`
|
||
|
||
Bir "açıklanabilirlik" üreticisi kaydedin (GraphRAG ile aynı yapı):
|
||
```python
|
||
from ... base import ProducerSpec
|
||
from ... schema import Triples
|
||
|
||
# In __init__:
|
||
self.register_specification(
|
||
ProducerSpec(
|
||
name = "explainability",
|
||
schema = Triples,
|
||
)
|
||
)
|
||
```
|
||
|
||
### 3. Kaynak Üçlü Oluşturma
|
||
|
||
**Dosya:** `trustgraph-base/trustgraph/provenance/agent.py`
|
||
|
||
Yardımcı fonksiyonlar oluşturun (GraphRAG'in `question_triples`, `exploration_triples`, vb. gibi):
|
||
```python
|
||
def agent_session_triples(session_uri, query, timestamp):
|
||
"""Generate triples for agent Question."""
|
||
return [
|
||
Triple(s=session_uri, p=RDF_TYPE, o=PROV_ACTIVITY),
|
||
Triple(s=session_uri, p=RDF_TYPE, o=TG_QUESTION),
|
||
Triple(s=session_uri, p=TG_QUERY, o=query),
|
||
Triple(s=session_uri, p=PROV_STARTED_AT_TIME, o=timestamp),
|
||
]
|
||
|
||
def agent_iteration_triples(iteration_uri, parent_uri, thought, action, arguments, observation):
|
||
"""Generate triples for one Analysis step."""
|
||
return [
|
||
Triple(s=iteration_uri, p=RDF_TYPE, o=PROV_ENTITY),
|
||
Triple(s=iteration_uri, p=RDF_TYPE, o=TG_ANALYSIS),
|
||
Triple(s=iteration_uri, p=TG_THOUGHT, o=thought),
|
||
Triple(s=iteration_uri, p=TG_ACTION, o=action),
|
||
Triple(s=iteration_uri, p=TG_ARGUMENTS, o=json.dumps(arguments)),
|
||
Triple(s=iteration_uri, p=TG_OBSERVATION, o=observation),
|
||
Triple(s=iteration_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
|
||
]
|
||
|
||
def agent_final_triples(final_uri, parent_uri, answer):
|
||
"""Generate triples for Conclusion."""
|
||
return [
|
||
Triple(s=final_uri, p=RDF_TYPE, o=PROV_ENTITY),
|
||
Triple(s=final_uri, p=RDF_TYPE, o=TG_CONCLUSION),
|
||
Triple(s=final_uri, p=TG_ANSWER, o=answer),
|
||
Triple(s=final_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
|
||
]
|
||
```
|
||
|
||
### 4. Tür Tanımları
|
||
|
||
**Dosya:** `trustgraph-base/trustgraph/provenance/namespaces.py`
|
||
|
||
Açıklanabilirlik varlık türlerini ve ajan özniteliklerini ekleyin:
|
||
```python
|
||
# Explainability entity types (used by both GraphRAG and Agent)
|
||
TG_QUESTION = TG + "Question"
|
||
TG_EXPLORATION = TG + "Exploration"
|
||
TG_FOCUS = TG + "Focus"
|
||
TG_SYNTHESIS = TG + "Synthesis"
|
||
TG_ANALYSIS = TG + "Analysis"
|
||
TG_CONCLUSION = TG + "Conclusion"
|
||
|
||
# Agent predicates
|
||
TG_THOUGHT = TG + "thought"
|
||
TG_ACTION = TG + "action"
|
||
TG_ARGUMENTS = TG + "arguments"
|
||
TG_OBSERVATION = TG + "observation"
|
||
TG_ANSWER = TG + "answer"
|
||
```
|
||
|
||
## Değiştirilen Dosyalar
|
||
|
||
| Dosya | Değişiklik |
|
||
|------|--------|
|
||
| `trustgraph-base/trustgraph/schema/services/agent.py` | AgentRequest'e session_id ve collection eklendi |
|
||
| `trustgraph-base/trustgraph/messaging/translators/agent.py` | Yeni alanlar için çevirici güncellendi |
|
||
| `trustgraph-base/trustgraph/provenance/namespaces.py` | Varlık türleri, ajan önişlemleri ve Document RAG önişlemleri eklendi |
|
||
| `trustgraph-base/trustgraph/provenance/triples.py` | GraphRAG üçlü oluşturucularına TG türleri eklendi, Document RAG üçlü oluşturucuları eklendi |
|
||
| `trustgraph-base/trustgraph/provenance/uris.py` | Document RAG URI oluşturucuları eklendi |
|
||
| `trustgraph-base/trustgraph/provenance/__init__.py` | Yeni türler, önişlemler ve Document RAG fonksiyonları dışa aktarıldı |
|
||
| `trustgraph-base/trustgraph/schema/services/retrieval.py` | DocumentRagResponse'a explain_id ve explain_graph eklendi |
|
||
| `trustgraph-base/trustgraph/messaging/translators/retrieval.py` | Açıklanabilirlik alanları için DocumentRagResponseTranslator güncellendi |
|
||
| `trustgraph-flow/trustgraph/agent/react/service.py` | Açıklanabilirlik üretici + kayıt mantığı eklendi |
|
||
| `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py` | Açıklanabilirlik geri çağırması eklendi ve kaynak üçlüleri yayıldı |
|
||
| `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` | Açıklanabilirlik üretici eklendi ve geri çağırma ile bağlandı |
|
||
| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | Ajan izleme türleri işlendi |
|
||
| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | Ajan oturumları, GraphRAG ile birlikte listelendi |
|
||
|
||
## Oluşturulan Dosyalar
|
||
|
||
| Dosya | Amaç |
|
||
|------|---------|
|
||
| `trustgraph-base/trustgraph/provenance/agent.py` | Ajan özel üçlü oluşturucuları |
|
||
|
||
## CLI Güncellemeleri
|
||
|
||
**Algılama:** Hem GraphRAG hem de Ajan Soruları `tg:Question` türündedir. Aşağıdakilerle ayırt edilir:
|
||
1. URI kalıbı: `urn:trustgraph:agent:` vs `urn:trustgraph:question:`
|
||
2. Türetilen varlıklar: `tg:Analysis` (ajan) vs `tg:Exploration` (GraphRAG)
|
||
|
||
**`list_explain_traces.py`:**
|
||
- Tür sütununu (Ajan vs GraphRAG) gösterir
|
||
|
||
**`show_explain_trace.py`:**
|
||
- İzleme türünü otomatik olarak algılar
|
||
- Ajan işleme, şu öğeleri gösterir: Soru → Analiz adımı(ları) → Sonuç
|
||
|
||
## Geriye Dönük Uyumluluk
|
||
|
||
- `session_id` varsayılan olarak `""`'dir - eski istekler çalışır, ancak kaynak bilgisi olmayacaktır
|
||
- `collection` varsayılan olarak `"default"`'dir - makul bir yedekleme
|
||
- CLI, her iki izleme türünü de sorunsuz bir şekilde işler
|
||
|
||
## Doğrulama
|
||
|
||
```bash
|
||
# Run an agent query
|
||
tg-invoke-agent -q "What is the capital of France?"
|
||
|
||
# List traces (should show agent sessions with Type column)
|
||
tg-list-explain-traces -U trustgraph -C default
|
||
|
||
# Show agent trace
|
||
tg-show-explain-trace "urn:trustgraph:agent:xxx"
|
||
```
|
||
|
||
## Gelecek Çalışmalar (Bu PR'de Değil)
|
||
|
||
- DAG bağımlılıkları (analiz N, birden fazla önceki analizden sonuçları kullandığında)
|
||
- Araçlara özel köken bağlantısı (KnowledgeQuery → GraphRAG izi)
|
||
- Akışlı köken yayını (sonunda toplu olarak değil, işlem sırasında yayınla)
|