mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 08:26:21 +02:00
281 lines
12 KiB
Markdown
281 lines
12 KiB
Markdown
|
---
|
|||
|
|
layout: default
|
|||
|
|
title: "הסברתיות של סוכן: רישום מקורות"
|
|||
|
|
parent: "Hebrew (Beta)"
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# הסברתיות של סוכן: רישום מקורות
|
|||
|
|
|
|||
|
|
> **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.
|
|||
|
|
|
|||
|
|
## סקירה כללית
|
|||
|
|
|
|||
|
|
הוספת רישום מקורות ללולאת הסוכן של React כך שניתן יהיה לעקוב אחר סשנים של סוכנים ולבצע ניפוי באגים באמצעות אותה תשתית הסברתיות כמו GraphRAG.
|
|||
|
|
|
|||
|
|
**החלטות עיצוב:**
|
|||
|
|
כתיבה ל-`urn:graph:retrieval` (גרף הסברתיות גנרי)
|
|||
|
|
שרשרת תלות ליניארית כרגע (ניתוח N → נגזר מ → ניתוח N-1)
|
|||
|
|
כלים הם תיבות שחורות (רישום קלט/פלט בלבד)
|
|||
|
|
תמיכה ב-DAG (גרף מכוון) נדחית למהלך עתידי
|
|||
|
|
|
|||
|
|
## סוגי ישויות
|
|||
|
|
|
|||
|
|
גם GraphRAG וגם Agent משתמשים ב-PROV-O כאונטולוגיה בסיסית עם תת-סוגים ספציפיים ל-TrustGraph:
|
|||
|
|
|
|||
|
|
### סוגי GraphRAG
|
|||
|
|
| ישות | סוג PROV-O | סוגי TG | תיאור |
|
|||
|
|
|--------|-------------|----------|-------------|
|
|||
|
|
| שאלה | `prov:Activity` | `tg:Question`, `tg:GraphRagQuestion` | השאלה של המשתמש |
|
|||
|
|
| חקירה | `prov:Entity` | `tg:Exploration` | צמתים שאוחזרו מגרף ידע |
|
|||
|
|
| מיקוד | `prov:Entity` | `tg:Focus` | צמתים שנבחרו עם נימוק |
|
|||
|
|
| סינתזה | `prov:Entity` | `tg:Synthesis` | תשובה סופית |
|
|||
|
|
|
|||
|
|
### סוגי סוכן
|
|||
|
|
| ישות | סוג PROV-O | סוגי TG | תיאור |
|
|||
|
|
|--------|-------------|----------|-------------|
|
|||
|
|
| שאלה | `prov:Activity` | `tg:Question`, `tg:AgentQuestion` | השאלה של המשתמש |
|
|||
|
|
| ניתוח | `prov:Entity` | `tg:Analysis` | כל מחזור חשיבה/פעולה/תצפית |
|
|||
|
|
| מסקנה | `prov:Entity` | `tg:Conclusion` | תשובה סופית |
|
|||
|
|
|
|||
|
|
### סוגי RAG של מסמכים
|
|||
|
|
| ישות | סוג PROV-O | סוגי TG | תיאור |
|
|||
|
|
|--------|-------------|----------|-------------|
|
|||
|
|
| שאלה | `prov:Activity` | `tg:Question`, `tg:DocRagQuestion` | השאלה של המשתמש |
|
|||
|
|
| חקירה | `prov:Entity` | `tg:Exploration` | חלקים שאוחזרו מחנות מסמכים |
|
|||
|
|
| סינתזה | `prov:Entity` | `tg:Synthesis` | תשובה סופית |
|
|||
|
|
|
|||
|
|
**הערה:** RAG של מסמכים משתמש בתת-קבוצה של סוגים של GraphRAG (אין שלב מיקוד מכיוון שאין שלב בחירת/נימוק צמתים).
|
|||
|
|
|
|||
|
|
### תת-סוגים של שאלה
|
|||
|
|
|
|||
|
|
כל ישויות השאלה חולקות את `tg:Question` כסוג בסיסי אך יש להן תת-סוג ספציפי כדי לזהות את מנגנון השליפה:
|
|||
|
|
|
|||
|
|
| תת-סוג | תבנית URI | מנגנון |
|
|||
|
|
|---------|-------------|-----------|
|
|||
|
|
| `tg:GraphRagQuestion` | `urn:trustgraph:question:{uuid}` | RAG של גרף ידע |
|
|||
|
|
| `tg:DocRagQuestion` | `urn:trustgraph:docrag:{uuid}` | RAG של מסמכים/חלקים |
|
|||
|
|
| `tg:AgentQuestion` | `urn:trustgraph:agent:{uuid}` | סוכן ReAct |
|
|||
|
|
|
|||
|
|
זה מאפשר שאילתא של כל השאלות באמצעות `tg:Question` תוך סינון לפי מנגנון ספציפי באמצעות תת-הסוג.
|
|||
|
|
|
|||
|
|
## מודל מקורות
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
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
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### מודל מקור (Provenance) של מסמכים בשיטת RAG
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
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
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## שינויים נדרשים
|
|||
|
|
|
|||
|
|
### 1. שינויים בסכימה
|
|||
|
|
|
|||
|
|
**קובץ:** `trustgraph-base/trustgraph/schema/services/agent.py`
|
|||
|
|
|
|||
|
|
הוסף את השדות `session_id` ו-`collection` ל-`AgentRequest`:
|
|||
|
|
```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
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**קובץ:** `trustgraph-base/trustgraph/messaging/translators/agent.py`
|
|||
|
|
|
|||
|
|
עדכון המתרגם כדי לטפל ב-`session_id` וב-`collection` הן ב-`to_pulsar()` והן ב-`from_pulsar()`.
|
|||
|
|
|
|||
|
|
### 2. הוספת יצרן הסברות לשירות הסוכנים
|
|||
|
|
|
|||
|
|
**קובץ:** `trustgraph-flow/trustgraph/agent/react/service.py`
|
|||
|
|
|
|||
|
|
רישום יצרן "הסברות" (באותו דפוס כמו GraphRAG):
|
|||
|
|
```python
|
|||
|
|
from ... base import ProducerSpec
|
|||
|
|
from ... schema import Triples
|
|||
|
|
|
|||
|
|
# In __init__:
|
|||
|
|
self.register_specification(
|
|||
|
|
ProducerSpec(
|
|||
|
|
name = "explainability",
|
|||
|
|
schema = Triples,
|
|||
|
|
)
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. יצירת משולש מוצא
|
|||
|
|
|
|||
|
|
**קובץ:** `trustgraph-base/trustgraph/provenance/agent.py`
|
|||
|
|
|
|||
|
|
צור פונקציות עזר (בדומה ל-`question_triples`, `exploration_triples` וכו' של GraphRAG):
|
|||
|
|
```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. הגדרות סוג
|
|||
|
|
|
|||
|
|
**קובץ:** `trustgraph-base/trustgraph/provenance/namespaces.py`
|
|||
|
|
|
|||
|
|
הוסף סוגי ישויות הסבר ופרדיקטים של סוכנים:
|
|||
|
|
```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"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## קבצים ששונו
|
|||
|
|
|
|||
|
|
| קובץ | שינוי |
|
|||
|
|
|------|--------|
|
|||
|
|
| `trustgraph-base/trustgraph/schema/services/agent.py` | הוספת session_id ו-collection ל-AgentRequest |
|
|||
|
|
| `trustgraph-base/trustgraph/messaging/translators/agent.py` | עדכון מתרגם עבור שדות חדשים |
|
|||
|
|
| `trustgraph-base/trustgraph/provenance/namespaces.py` | הוספת סוגי ישויות, טענות של סוכן וטענות של Document RAG |
|
|||
|
|
| `trustgraph-base/trustgraph/provenance/triples.py` | הוספת סוגי TG לבונים של משולשים של GraphRAG, הוספת בונים של משולשים של Document RAG |
|
|||
|
|
| `trustgraph-base/trustgraph/provenance/uris.py` | הוספת יוצרי URI של Document RAG |
|
|||
|
|
| `trustgraph-base/trustgraph/provenance/__init__.py` | ייצוא סוגים, טענות ופונקציות חדשות של Document RAG |
|
|||
|
|
| `trustgraph-base/trustgraph/schema/services/retrieval.py` | הוספת explain_id ו-explain_graph ל-DocumentRagResponse |
|
|||
|
|
| `trustgraph-base/trustgraph/messaging/translators/retrieval.py` | עדכון DocumentRagResponseTranslator עבור שדות הסברתיות |
|
|||
|
|
| `trustgraph-flow/trustgraph/agent/react/service.py` | הוספת מפיק הסברתיות + לוגיקת הקלטה |
|
|||
|
|
| `trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py` | הוספת קריאה חוזרת של הסברתיות ופליטת משולשים של מקור |
|
|||
|
|
| `trustgraph-flow/trustgraph/retrieval/document_rag/rag.py` | הוספת מפיק הסברתיות וחיבור הקריאה החוזרת |
|
|||
|
|
| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | טיפול בסוגי מעקב של סוכן |
|
|||
|
|
| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | הצגת סשנים של סוכן לצד GraphRAG |
|
|||
|
|
|
|||
|
|
## קבצים שנוצרו
|
|||
|
|
|
|||
|
|
| קובץ | מטרה |
|
|||
|
|
|------|---------|
|
|||
|
|
| `trustgraph-base/trustgraph/provenance/agent.py` | יוצרי משולשים ספציפיים לסוכן |
|
|||
|
|
|
|||
|
|
## עדכוני CLI
|
|||
|
|
|
|||
|
|
**זיהוי:** גם לשאלות GraphRAG וגם לשאלות סוכן יש סוג `tg:Question`. מובחנים על ידי:
|
|||
|
|
1. תבנית URI: `urn:trustgraph:agent:` לעומת `urn:trustgraph:question:`
|
|||
|
|
2. ישויות נגזרות: `tg:Analysis` (סוכן) לעומת `tg:Exploration` (GraphRAG)
|
|||
|
|
|
|||
|
|
**`list_explain_traces.py`:**
|
|||
|
|
מציג את עמודת הסוג (סוכן לעומת GraphRAG)
|
|||
|
|
|
|||
|
|
**`show_explain_trace.py`:**
|
|||
|
|
מזהה אוטומטית את סוג המעקב
|
|||
|
|
הצגת סוכן מציגה: שאלה → שלב(ים) של ניתוח → מסקנה
|
|||
|
|
|
|||
|
|
## תאימות לאחור
|
|||
|
|
|
|||
|
|
`session_id` כברירת מחדל הוא `""` - בקשות ישנות עובדות, פשוט לא יהיו להן נתונים של מקור
|
|||
|
|
`collection` כברירת מחדל הוא `"default"` - חזרה סבירה
|
|||
|
|
ה-CLI מטפל בצורה חלקה בשני סוגי המעקב
|
|||
|
|
|
|||
|
|
## אימות
|
|||
|
|
|
|||
|
|
```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"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## עבודה עתידית (לא בבקשה הזו)
|
|||
|
|
|
|||
|
|
תלותיות DAG (כאשר ניתוח N משתמש בתוצאות ממספר ניתוחים קודמים)
|
|||
|
|
קישור מקורות מידע ספציפי לכלי (KnowledgeQuery → המעקב GraphRAG שלו)
|
|||
|
|
פליטת מקורות מידע בסטרימינג (לשלוח תוך כדי פעולה, ולא במקשה בסוף)
|