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
Cyber MacGeddon
parent
f976f1b6fe
commit
8954fa3ad7
560 changed files with 236300 additions and 99 deletions
228
docs/tech-specs/explainability-cli.tr.md
Normal file
228
docs/tech-specs/explainability-cli.tr.md
Normal file
|
|
@ -0,0 +1,228 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Açıklanabilirlik CLI Teknik Özellikleri"
|
||||
parent: "Turkish (Beta)"
|
||||
---
|
||||
|
||||
# Açıklanabilirlik CLI Teknik Özellikleri
|
||||
|
||||
> **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
|
||||
|
||||
Taslak
|
||||
|
||||
## Genel Bakış
|
||||
|
||||
Bu özellik, TrustGraph'ta açıklanabilirlik verilerini hata ayıklamak ve incelemek için kullanılan CLI araçlarını tanımlar. Bu araçlar, kullanıcıların cevapların nasıl elde edildiğini izlemesini ve kenarlardan kaynak belgelere kadar olan köken zincirini hata ayıklamasını sağlar.
|
||||
|
||||
Üç CLI aracı:
|
||||
|
||||
1. **`tg-show-document-hierarchy`** - Belge → sayfa → parça → kenar hiyerarşisini gösterir
|
||||
2. **`tg-list-explain-traces`** - Tüm GraphRAG oturumlarını sorularla birlikte listeler
|
||||
3. **`tg-show-explain-trace`** - Bir oturum için tam açıklanabilirlik izini gösterir
|
||||
|
||||
## Hedefler
|
||||
|
||||
**Hata Ayıklama**: Geliştiricilerin belge işleme sonuçlarını incelemesini sağlar
|
||||
**Denetlenebilirlik**: Herhangi bir çıkarılan gerçeği kaynak belgesine kadar izleme
|
||||
**Şeffaflık**: GraphRAG'ın bir cevabı tam olarak nasıl elde ettiğini gösterme
|
||||
**Kullanılabilirlik**: Akıllı varsayılanlarla basit bir CLI arayüzü
|
||||
|
||||
## Arka Plan
|
||||
|
||||
TrustGraph'un iki köken sistemi vardır:
|
||||
|
||||
1. **Çıkarma zamanı kökeni** (bkz. `extraction-time-provenance.md`): Yükleme sırasında belge → sayfa → parça → kenar ilişkilerini kaydeder. `urn:graph:source` adlı grafte saklanır ve `prov:wasDerivedFrom` kullanılarak oluşturulur.
|
||||
|
||||
2. **Sorgu zamanı açıklanabilirliği** (bkz. `query-time-explainability.md`): GraphRAG sorguları sırasında soru → keşif → odak → sentez zincirini kaydeder. `urn:graph:retrieval` adlı grafte saklanır.
|
||||
|
||||
Mevcut sınırlamalar:
|
||||
İşleme sonrası belge hiyerarşisini görselleştirmenin kolay bir yolu yok
|
||||
Açıklanabilirlik verilerini görmek için üçlüleri manuel olarak sorgulamak gerekiyor
|
||||
Bir GraphRAG oturumunun konsolide bir görünümü yok
|
||||
|
||||
## Teknik Tasarım
|
||||
|
||||
### Araç 1: tg-show-document-hierarchy
|
||||
|
||||
**Amaç**: Bir belge kimliği verildiğinde, türetilen tüm varlıkları gezinerek ve görüntüleyerek.
|
||||
|
||||
**Kullanım**:
|
||||
```bash
|
||||
tg-show-document-hierarchy "urn:trustgraph:doc:abc123"
|
||||
tg-show-document-hierarchy --show-content --max-content 500 "urn:trustgraph:doc:abc123"
|
||||
```
|
||||
|
||||
**Argümanlar**:
|
||||
| Arg | Açıklama |
|
||||
|-----|-------------|
|
||||
| `document_id` | Belge URI'si (konumsal) |
|
||||
| `-u/--api-url` | Ağ geçidi URL'si (varsayılan: `$TRUSTGRAPH_URL`) |
|
||||
| `-t/--token` | Kimlik doğrulama belirteci (varsayılan: `$TRUSTGRAPH_TOKEN`) |
|
||||
| `-U/--user` | Kullanıcı Kimliği (varsayılan: `trustgraph`) |
|
||||
| `-C/--collection` | Koleksiyon (varsayılan: `default`) |
|
||||
| `--show-content` | Blob/belge içeriğini dahil et |
|
||||
| `--max-content` | Blob başına maksimum karakter sayısı (varsayılan: 200) |
|
||||
| `--format` | Çıktı: `tree` (varsayılan), `json` |
|
||||
|
||||
**Uygulama**:
|
||||
1. Üçlüleri sorgula: `?child prov:wasDerivedFrom <document_id>` içinde `urn:graph:source`
|
||||
2. Her sonucun çocuklarını yinelemeli olarak sorgula
|
||||
3. Ağaç yapısını oluştur: Belge → Sayfalar → Parçalar
|
||||
4. Eğer `--show-content` ise, içeriği kütüphaneci API'sinden al
|
||||
5. Girintili bir ağaç veya JSON olarak göster
|
||||
|
||||
**Çıktı Örneği**:
|
||||
```
|
||||
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]
|
||||
```
|
||||
|
||||
### Araç 2: tg-list-explain-traces
|
||||
|
||||
**Amaç**: Bir koleksiyondaki tüm GraphRAG oturumlarını (soruları) listelemek.
|
||||
|
||||
**Kullanım**:
|
||||
```bash
|
||||
tg-list-explain-traces
|
||||
tg-list-explain-traces --limit 20 --format json
|
||||
```
|
||||
|
||||
**Argümanlar**:
|
||||
| Arg | Açıklama |
|
||||
|-----|-------------|
|
||||
| `-u/--api-url` | Ağ geçidi URL'si |
|
||||
| `-t/--token` | Yetkilendirme belirteci |
|
||||
| `-U/--user` | Kullanıcı Kimliği |
|
||||
| `-C/--collection` | Koleksiyon |
|
||||
| `--limit` | Maksimum sonuç sayısı (varsayılan: 50) |
|
||||
| `--format` | Çıktı: `table` (varsayılan), `json` |
|
||||
|
||||
**Uygulama**:
|
||||
1. Sorgu: `?session tg:query ?text` içinde `urn:graph:retrieval`
|
||||
2. Sorgu zaman damgaları: `?session prov:startedAtTime ?time`
|
||||
3. Tablo olarak göster
|
||||
|
||||
**Çıktı Örneği**:
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
### Araç 3: tg-show-explain-trace
|
||||
|
||||
**Amaç**: Bir GraphRAG oturumu için tam açıklanabilirlik zincirini gösterir.
|
||||
|
||||
**Kullanım**:
|
||||
```bash
|
||||
tg-show-explain-trace "urn:trustgraph:question:abc123"
|
||||
tg-show-explain-trace --max-answer 1000 --show-provenance "urn:trustgraph:question:abc123"
|
||||
```
|
||||
|
||||
**Argümanlar**:
|
||||
| Arg | Açıklama |
|
||||
|-----|-------------|
|
||||
| `question_id` | Soru URI'si (konumsal) |
|
||||
| `-u/--api-url` | Ağ geçidi URL'si |
|
||||
| `-t/--token` | Kimlik doğrulama belirteci |
|
||||
| `-U/--user` | Kullanıcı Kimliği |
|
||||
| `-C/--collection` | Koleksiyon |
|
||||
| `--max-answer` | Cevap için maksimum karakter sayısı (varsayılan: 500) |
|
||||
| `--show-provenance` | Kaynak belgelere kadar kenarları izle |
|
||||
| `--format` | Çıktı: `text` (varsayılan), `json` |
|
||||
|
||||
**Uygulama**:
|
||||
1. `tg:query` özniteliğinden soru metnini al.
|
||||
2. Keşfi bul: `?exp prov:wasGeneratedBy <question_id>`
|
||||
3. Odak noktasını bul: `?focus prov:wasDerivedFrom <exploration_id>`
|
||||
4. Seçilen kenarları al: `<focus_id> tg:selectedEdge ?edge`
|
||||
5. Her kenar için, `tg:edge` (alıntılanmış üçlü) ve `tg:reasoning`'i al.
|
||||
6. Sentezi bul: `?synth prov:wasDerivedFrom <focus_id>`
|
||||
7. Cevabı `tg:document` aracılığıyla kütüphaneciden al.
|
||||
8. Eğer `--show-provenance` ise, kaynak belgelere kadar kenarları izle.
|
||||
|
||||
**Çıktı Örneği**:
|
||||
```
|
||||
=== 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]
|
||||
```
|
||||
|
||||
## Oluşturulacak Dosyalar
|
||||
|
||||
| Dosya | Amaç |
|
||||
|------|---------|
|
||||
| `trustgraph-cli/trustgraph/cli/show_document_hierarchy.py` | Araç 1 |
|
||||
| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | Araç 2 |
|
||||
| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | Araç 3 |
|
||||
|
||||
## Değiştirilecek Dosyalar
|
||||
|
||||
| Dosya | Değişiklik |
|
||||
|------|--------|
|
||||
| `trustgraph-cli/setup.py` | console_scripts girişlerini ekle |
|
||||
|
||||
## Uygulama Notları
|
||||
|
||||
1. **İkili içerik güvenliği**: UTF-8 ile çözmeyi deneyin; başarısız olursa `[Binary: {size} bytes]` gösterin.
|
||||
2. **Kısaltma**: `--max-content`/`--max-answer` ile `[truncated]` göstergesine saygı gösterin.
|
||||
3. **Tırnak işaretli üçlüler**: `tg:edge` önekinden RDF-star formatını ayrıştırın.
|
||||
4. **Desenler**: `query_graph.py`'dan mevcut CLI desenlerini izleyin.
|
||||
|
||||
## Güvenlik Hususları
|
||||
|
||||
Tüm sorgular, kullanıcı/koleksiyon sınırlarına saygı gösterir.
|
||||
`--token` veya `$TRUSTGRAPH_TOKEN` aracılığıyla token kimlik doğrulaması desteklenir.
|
||||
|
||||
## Test Stratejisi
|
||||
|
||||
Örnek verilerle manuel doğrulama:
|
||||
```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"
|
||||
```
|
||||
|
||||
## Referanslar
|
||||
|
||||
Sorgu zamanı açıklanabilirlik: `docs/tech-specs/query-time-explainability.md`
|
||||
Çıkarım zamanı köken bilgisi: `docs/tech-specs/extraction-time-provenance.md`
|
||||
Mevcut komut satırı örneği: `trustgraph-cli/trustgraph/cli/invoke_graph_rag.py`
|
||||
Loading…
Add table
Add a link
Reference in a new issue