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.
9.1 KiB
| layout | title | parent |
|---|---|---|
| default | מפרט טכני של כלי שורת הפקודה (CLI) להסברתיות | Hebrew (Beta) |
מפרט טכני של כלי שורת הפקודה (CLI) להסברתיות
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.
סטטוס
טיוטה
סקירה כללית
מפרט זה מתאר כלי שורת פקודה (CLI) לניפוי באגים ובדיקת נתוני הסברתיות ב-TrustGraph. כלים אלה מאפשרים למשתמשים לעקוב אחר אופן קבלת התשובות ולבצע ניפוי באגים בשרשרת המקור, החל מצמתים ועד למסמכים מקוריים.
שלושה כלים של שורת פקודה:
tg-show-document-hierarchy- הצגת היררכיה של מסמך → עמוד → מקטע → צומתtg-list-explain-traces- הצגת רשימה של כל הסשנים של GraphRAG עם שאלותtg-show-explain-trace- הצגת מעקב הסברתיות מלא עבור סשן
מטרות
ניפוי באגים: לאפשר למפתחים לבדוק את תוצאות עיבוד המסמכים ביקורת: לעקוב אחר כל עובדה שחולצה בחזרה למסמך המקור שלה שקיפות: להציג בדיוק כיצד GraphRAG הגיע לתשובה שימושיות: ממשק שורת פקודה פשוט עם הגדרות ברירת מחדל הגיוניות
רקע
ל-TrustGraph יש שתי מערכות מעקב מקור:
-
מעקב מקור בזמן חילוץ (ראה
extraction-time-provenance.md): מתעד את היחסים בין מסמך → עמוד → מקטע → צומת במהלך הטעינה. מאוחסן בגרף בשםurn:graph:sourceבאמצעותprov:wasDerivedFrom. -
הסברתיות בזמן שאילתה (ראה
query-time-explainability.md): מתעד את שרשרת השאלות → חקירה → מיקוד → סינתזה במהלך שאילתות GraphRAG. מאוחסן בגרף בשםurn:graph:retrieval.
מגבלות נוכחיות: אין דרך קלה להציג את היררכיית המסמכים לאחר העיבוד יש לבצע שאילתות ידניות על משולשים כדי לראות נתוני הסברתיות אין תצוגה מאוחדת של סשן GraphRAG
עיצוב טכני
כלי 1: tg-show-document-hierarchy
מטרה: בהינתן מזהה מסמך, לעבור ולציין את כל הישויות הנגזרות.
שימוש:
tg-show-document-hierarchy "urn:trustgraph:doc:abc123"
tg-show-document-hierarchy --show-content --max-content 500 "urn:trustgraph:doc:abc123"
ארגומנטים:
| Arg | תיאור |
|---|---|
document_id |
כתובת URI של המסמך (מיקום) |
-u/--api-url |
כתובת URL של ה-Gateway (ברירת מחדל: $TRUSTGRAPH_URL) |
-t/--token |
טוקן אימות (ברירת מחדל: $TRUSTGRAPH_TOKEN) |
-U/--user |
מזהה משתמש (ברירת מחדל: trustgraph) |
-C/--collection |
אוסף (ברירת מחדל: default) |
--show-content |
לכלול תוכן של קבצים/מסמכים |
--max-content |
מספר תווים מקסימלי לכל קובץ (ברירת מחדל: 200) |
--format |
פלט: tree (ברירת מחדל), json |
יישום:
- שאילת משולשות:
?child prov:wasDerivedFrom <document_id>ב-urn:graph:source - שאילת באופן רקורסיבי את הילדים של כל תוצאה
- בניית מבנה עץ: מסמך → עמודים → חלקים
- אם
--show-content, שליפה של תוכן מ-API של הספרן - הצגה כמבנה עץ עם הזחות או JSON
דוגמה לפלט:
Document: urn:trustgraph:doc:abc123
Title: "Sample PDF"
Type: application/pdf
└── Page 1: urn:trustgraph:doc:abc123/p1
├── Chunk 0: urn:trustgraph:doc:abc123/p1/c0
│ Content: "The quick brown fox..." [truncated]
└── Chunk 1: urn:trustgraph:doc:abc123/p1/c1
Content: "Machine learning is..." [truncated]
כלי 2: tg-list-explain-traces
מטרה: הצגת כל הסשנים (שאלות) של GraphRAG באוסף.
שימוש:
tg-list-explain-traces
tg-list-explain-traces --limit 20 --format json
ארגומנטים:
| Arg | תיאור |
|---|---|
-u/--api-url |
כתובת URL של ה-Gateway |
-t/--token |
טוקן אימות |
-U/--user |
מזהה משתמש |
-C/--collection |
אוסף |
--limit |
מספר תוצאות מקסימלי (ברירת מחדל: 50) |
--format |
פלט: table (ברירת מחדל), json |
יישום:
- שאילתה:
?session tg:query ?textב-urn:graph:retrieval - שאילתת חותמות זמן:
?session prov:startedAtTime ?time - הצגה כטבלה
דוגמה לפלט:
Session ID | Question | Time
----------------------------------------------|--------------------------------|---------------------
urn:trustgraph:question:abc123 | What was the War on Terror? | 2024-01-15 10:30:00
urn:trustgraph:question:def456 | Who founded OpenAI? | 2024-01-15 09:15:00
כלי 3: tg-show-explain-trace
מטרה: הצגת שרשרת ההסברים המלאה עבור סשן GraphRAG.
שימוש:
tg-show-explain-trace "urn:trustgraph:question:abc123"
tg-show-explain-trace --max-answer 1000 --show-provenance "urn:trustgraph:question:abc123"
ארגומנטים:
| Arg | תיאור |
|---|---|
question_id |
כתובת URI של שאלה (מיקום) |
-u/--api-url |
כתובת URL של שער |
-t/--token |
טוקן אימות |
-U/--user |
מזהה משתמש |
-C/--collection |
אוסף |
--max-answer |
מספר תווים מקסימלי לתשובה (ברירת מחדל: 500) |
--show-provenance |
לעקוב אחר קשרים למסמכים מקוריים |
--format |
פלט: text (ברירת מחדל), json |
יישום:
- קבל את טקסט השאלה מ-
tg:query(predicate) - מצא חקירה:
?exp prov:wasGeneratedBy <question_id> - מצא מיקוד:
?focus prov:wasDerivedFrom <exploration_id> - קבל קשרים שנבחרו:
<focus_id> tg:selectedEdge ?edge - עבור כל קשר, קבל
tg:edge(משולש מצוטט) ו-tg:reasoning - מצא סינתזה:
?synth prov:wasDerivedFrom <focus_id> - קבל את התשובה מ-
tg:documentדרך הספרן | - אם
--show-provenance, עקוב אחר קשרים למסמכים מקוריים
דוגמה לפלט:
=== GraphRAG Session: urn:trustgraph:question:abc123 ===
Question: What was the War on Terror?
Time: 2024-01-15 10:30:00
--- Exploration ---
Retrieved 50 edges from knowledge graph
--- Focus (Edge Selection) ---
Selected 12 edges:
1. (War on Terror, definition, "A military campaign...")
Reasoning: Directly defines the subject of the query
Source: chunk → page 2 → "Beyond the Vigilant State"
2. (Guantanamo Bay, part_of, War on Terror)
Reasoning: Shows key component of the campaign
--- Synthesis ---
Answer:
The War on Terror was a military campaign initiated...
[truncated at 500 chars]
קבצים ליצירה
| קובץ | מטרה |
|---|---|
trustgraph-cli/trustgraph/cli/show_document_hierarchy.py |
כלי 1 |
trustgraph-cli/trustgraph/cli/list_explain_traces.py |
כלי 2 |
trustgraph-cli/trustgraph/cli/show_explain_trace.py |
כלי 3 |
קבצים לשינוי
| קובץ | שינוי |
|---|---|
trustgraph-cli/setup.py |
הוספת רשומות ל-console_scripts |
הערות יישום
- בטיחות תוכן בינארי: נסה לפענח UTF-8; אם נכשל, הצג
[Binary: {size} bytes] - חיתוך: שמור על
--max-content/--max-answerעם מציין[truncated] - משולשות מצוטטות: נתח פורמט RDF-star מ-predicate
tg:edge - תבניות: עקוב אחר תבניות CLI קיימות מ-
query_graph.py
שיקולי אבטחה
כל השאילתות מכבדות את גבולות המשתמש/אוסף
אימות טוקן נתמך באמצעות --token או $TRUSTGRAPH_TOKEN
אסטרטגיית בדיקה
אימות ידני עם נתוני דוגמה:
# Load a test document
tg-load-pdf -f test.pdf -c test-collection
# Verify hierarchy
tg-show-document-hierarchy "urn:trustgraph:doc:test"
# Run a GraphRAG query with explainability
tg-invoke-graph-rag --explainable -q "Test question"
# List and inspect traces
tg-list-explain-traces
tg-show-explain-trace "urn:trustgraph:question:xxx"
הפניות
הסבר בזמן שאילתה: docs/tech-specs/query-time-explainability.md
מקור בזמן חילוץ: docs/tech-specs/extraction-time-provenance.md
דוגמה קיימת של שורת פקודה: trustgraph-cli/trustgraph/cli/invoke_graph_rag.py