mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 16:36:21 +02:00
Structure the tech specs directory (#836)
Tech spec some subdirectories for different languages
This commit is contained in:
cybermaggedon
GitHub
parent
48da6c5f8b
commit
e7efb673ef
423 changed files with 0 additions and 0 deletions
228
docs/tech-specs/sw/explainability-cli.sw.md
Normal file
228
docs/tech-specs/sw/explainability-cli.sw.md
Normal file
|
|
@ -0,0 +1,228 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Maelezo ya Kiufundi ya Zana za Amri (CLI) za Ufafanuzi"
|
||||
parent: "Swahili (Beta)"
|
||||
---
|
||||
|
||||
# Maelezo ya Kiufundi ya Zana za Amri (CLI) za Ufafanuzi
|
||||
|
||||
> **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.
|
||||
|
||||
## Hali
|
||||
|
||||
Rasimu
|
||||
|
||||
## Muhtasari
|
||||
|
||||
Maelezo haya yanaeleza zana za amri (CLI) za kuchanganua na kuchunguza data ya ufafanuzi katika TrustGraph. Zana hizi zinawawezesha watumiaji kufuatilia jinsi majibu yalivyopatikana na kuchanganua mnyororo wa asili kutoka kwa uhusiano (edges) hadi kwenye nyaraka za asili.
|
||||
|
||||
Zana tatu za CLI:
|
||||
|
||||
1. **`tg-show-document-hierarchy`** - Onyesha hierarkia ya nyaraka → kurasa → vipande → uhusiano
|
||||
2. **`tg-list-explain-traces`** - Orodha ya vipindi vyote vya GraphRAG na maswali
|
||||
3. **`tg-show-explain-trace`** - Onyesha mnyororo kamili wa ufafanuzi kwa kipindi
|
||||
|
||||
## Lengo
|
||||
|
||||
**Uchanganuzi**: Kuwawezesha watengenezaji kuchunguza matokeo ya usindikaji wa nyaraka
|
||||
**Ufuatiliaji**: Kufuatilia ukweli wowote uliopatikana hadi kwenye nyaraka yake ya asili
|
||||
**Unyonyaji**: Kuonyesha jinsi GraphRAG ilivyopata jibu
|
||||
**Urahisi wa Matumizi**: Kiolesura rahisi cha CLI na mipangilio ya kawaida
|
||||
|
||||
## Asili
|
||||
|
||||
TrustGraph ina mifumo miwili ya asili:
|
||||
|
||||
1. **Asili ya wakati wa uundaji** (angalia `extraction-time-provenance.md`): Inarecord uhusiano wa nyaraka → kurasa → vipande → uhusiano wakati wa kuingizwa. Hifadhiwa katika grafu iliyoitwa `urn:graph:source` kwa kutumia `prov:wasDerivedFrom`.
|
||||
|
||||
2. **Ufafanuzi wa wakati wa kuulizia** (angalia `query-time-explainability.md`): Inarecord mnyororo wa swali → uchunguzi → umakini → muhtasari wakati wa maswali ya GraphRAG. Hifadhiwa katika grafu iliyoitwa `urn:graph:retrieval`.
|
||||
|
||||
Mapungufu ya sasa:
|
||||
Hakuna njia rahisi ya kuonyesha hierarkia ya nyaraka baada ya usindikaji
|
||||
Lazima kuulize data ya ufafanuzi kwa kutumia triples
|
||||
Hakuna mtazamo uliochanganywa wa kipindi cha GraphRAG
|
||||
|
||||
## Muundo wa Kiufundi
|
||||
|
||||
### Zana 1: tg-show-document-hierarchy
|
||||
|
||||
**Lengo**: Ikiwa unapokea kitambulisho cha nyaraka, tembea na uonyeshe vitu vyote vilivyotokana.
|
||||
|
||||
**Matumizi**:
|
||||
```bash
|
||||
tg-show-document-hierarchy "urn:trustgraph:doc:abc123"
|
||||
tg-show-document-hierarchy --show-content --max-content 500 "urn:trustgraph:doc:abc123"
|
||||
```
|
||||
|
||||
**Vigezo**:
|
||||
| Arg | Maelezo |
|
||||
|-----|-------------|
|
||||
| `document_id` | URI ya hati (ya nafasi) |
|
||||
| `-u/--api-url` | URL ya lango (ya kawaida: `$TRUSTGRAPH_URL`) |
|
||||
| `-t/--token` | Ishara ya uthibitishaji (ya kawaida: `$TRUSTGRAPH_TOKEN`) |
|
||||
| `-U/--user` | Kitambulisho cha mtumiaji (ya kawaida: `trustgraph`) |
|
||||
| `-C/--collection` | Mkusanyiko (ya kawaida: `default`) |
|
||||
| `--show-content` | Jumuisha yaliyomo katika faili/hati |
|
||||
| `--max-content` | Herufi nyingi kwa kila faili (ya kawaida: 200) |
|
||||
| `--format` | Matokeo: `tree` (ya kawaida), `json` |
|
||||
|
||||
**Utendaji**:
|
||||
1. Tafuta data: `?child prov:wasDerivedFrom <document_id>` katika `urn:graph:source`
|
||||
2. Tafuta kwa urudi-urudi watoto wa kila matokeo
|
||||
3. Jenga muundo wa mti: Hati → Kurasa → Sehemu
|
||||
4. Ikiwa `--show-content`, pata yaliyomo kutoka kwa API ya msimamizi
|
||||
5. Onyesha kama mti ulioainishwa au JSON
|
||||
|
||||
**Mfano wa Matokeo**:
|
||||
```
|
||||
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]
|
||||
```
|
||||
|
||||
### Zana 2: tg-list-explain-traces
|
||||
|
||||
**Madhumuni**: Kuorodhesha vipindi vyote vya GraphRAG (maswali) katika mkusanyiko.
|
||||
|
||||
**Matumizi**:
|
||||
```bash
|
||||
tg-list-explain-traces
|
||||
tg-list-explain-traces --limit 20 --format json
|
||||
```
|
||||
|
||||
**Vigezo**:
|
||||
| Arg | Maelezo |
|
||||
|-----|-------------|
|
||||
| `-u/--api-url` | URL ya lango |
|
||||
| `-t/--token` | Token ya uthibitishaji |
|
||||
| `-U/--user` | Kitambulisho cha mtumiaji |
|
||||
| `-C/--collection` | Mkusanyiko |
|
||||
| `--limit` | Matokeo ya juu (ya kawaida: 50) |
|
||||
| `--format` | Matokeo: `table` (ya kawaida), `json` |
|
||||
|
||||
**Utekelezaji**:
|
||||
1. Uliza: `?session tg:query ?text` katika `urn:graph:retrieval`
|
||||
2. Uliza alama za wakati: `?session prov:startedAtTime ?time`
|
||||
3. Onyesha kama jedwali
|
||||
|
||||
**Mfano wa Matokeo**:
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
### Zana 3: tg-show-explain-trace
|
||||
|
||||
**Madhumuni**: Kuonyesha mnyororo kamili wa uelewaji kwa kipindi cha GraphRAG.
|
||||
|
||||
**Matumizi**:
|
||||
```bash
|
||||
tg-show-explain-trace "urn:trustgraph:question:abc123"
|
||||
tg-show-explain-trace --max-answer 1000 --show-provenance "urn:trustgraph:question:abc123"
|
||||
```
|
||||
|
||||
**Vigezo**:
|
||||
| Arg | Maelezo |
|
||||
|-----|-------------|
|
||||
| `question_id` | URI ya swali (nafasi) |
|
||||
| `-u/--api-url` | URL ya lango |
|
||||
| `-t/--token` | Ishara ya uthibitishaji |
|
||||
| `-U/--user` | Kitambulisho cha mtumiaji |
|
||||
| `-C/--collection` | Mkusanyiko |
|
||||
| `--max-answer` | Idadi ya juu ya herufi kwa jibu (ya kawaida: 500) |
|
||||
| `--show-provenance` | Fuatilia miunganisho hadi kwenye hati za asili |
|
||||
| `--format` | Pato: `text` (ya kawaida), `json` |
|
||||
|
||||
**Utendaji**:
|
||||
1. Pata maandishi ya swali kutoka kwa `tg:query`.
|
||||
2. Tafuta utafutaji: `?exp prov:wasGeneratedBy <question_id>`
|
||||
3. Tafuta umakini: `?focus prov:wasDerivedFrom <exploration_id>`
|
||||
4. Pata miunganisho iliyochaguliwa: `<focus_id> tg:selectedEdge ?edge`
|
||||
5. Kwa kila muunganisho, pata `tg:edge` (triple iliyotiwa mabano) na `tg:reasoning`.
|
||||
6. Tafuta muhtasari: `?synth prov:wasDerivedFrom <focus_id>`
|
||||
7. Pata jibu kutoka kwa `tg:document` kupitia msimamizi wa maktaba.
|
||||
8. Ikiwa `--show-provenance`, fuatilia miunganisho hadi kwenye hati za asili.
|
||||
|
||||
**Mfano wa Pato**:
|
||||
```
|
||||
=== 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]
|
||||
```
|
||||
|
||||
## Faili Zinazotakazwa Kuundwa
|
||||
|
||||
| Faili | Madhumuni |
|
||||
|------|---------|
|
||||
| `trustgraph-cli/trustgraph/cli/show_document_hierarchy.py` | Chombo 1 |
|
||||
| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | Chombo 2 |
|
||||
| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | Chombo 3 |
|
||||
|
||||
## Faili Zinazotakazwa Kurekebishwa
|
||||
|
||||
| Faili | Marekebisho |
|
||||
|------|--------|
|
||||
| `trustgraph-cli/setup.py` | Ongeza vipengele vya `console_scripts` |
|
||||
|
||||
## Maelezo ya Utendaji
|
||||
|
||||
1. **Usalama wa yaliyomo ya binary**: Jaribu kusimbua kwa UTF-8; ikiwa hufanikiwa, onyesha `[Binary: {size} bytes]`
|
||||
2. **Ufupishaji**: Zifuata sheria za `--max-content`/`--max-answer` pamoja na ishara ya `[truncated]`
|
||||
3. **Manuku matatu yaliyotiwa:** Changanua muundo wa RDF-star kutoka kwa `predicate` ya `tg:edge`
|
||||
4. **Mifumo:** Fuata mifumo iliyopo ya CLI kutoka `query_graph.py`
|
||||
|
||||
## Masuala ya Usalama
|
||||
|
||||
Maswali yote yanazingatia mipaka ya mtumiaji/mkusanyiko
|
||||
Uthibitishaji wa token unaoendeshwa kupitia `--token` au `$TRUSTGRAPH_TOKEN`
|
||||
|
||||
## Mkakati wa Upimaji
|
||||
|
||||
Uthibitisho wa mwongozo kwa data ya mfano:
|
||||
```bash
|
||||
# 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"
|
||||
```
|
||||
|
||||
## Marejeleo
|
||||
|
||||
Uwezekano wa kueleza matokeo wakati wa swali: `docs/tech-specs/query-time-explainability.md`
|
||||
Chanzo cha data wakati wa uundaji: `docs/tech-specs/extraction-time-provenance.md`
|
||||
Kifaa cha amri (CLI) cha mfano uliopo: `trustgraph-cli/trustgraph/cli/invoke_graph_rag.py`
|
||||
Loading…
Add table
Add a link
Reference in a new issue