mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 08:26: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.
228 lines
11 KiB
Markdown
228 lines
11 KiB
Markdown
---
|
||
layout: default
|
||
title: "Техническая спецификация CLI для Explainability"
|
||
parent: "Russian (Beta)"
|
||
---
|
||
|
||
# Техническая спецификация CLI для Explainability
|
||
|
||
> **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.
|
||
|
||
## Статус
|
||
|
||
Черновик
|
||
|
||
## Обзор
|
||
|
||
Эта спецификация описывает инструменты командной строки для отладки и изучения данных explainability в TrustGraph. Эти инструменты позволяют пользователям отслеживать, как были получены ответы, и отлаживать цепочку происхождения от ребер до исходных документов.
|
||
|
||
Три инструмента командной строки:
|
||
|
||
1. **`tg-show-document-hierarchy`** - Отображение иерархии документ → страница → фрагмент → ребро
|
||
2. **`tg-list-explain-traces`** - Список всех сессий GraphRAG с вопросами
|
||
3. **`tg-show-explain-trace`** - Отображение полной цепочки explainability для сессии
|
||
|
||
## Цели
|
||
|
||
**Отладка**: Предоставить разработчикам возможность просматривать результаты обработки документов.
|
||
**Прослеживаемость**: Отслеживать любой извлеченный факт до его исходного документа.
|
||
**Прозрачность**: Показать, как GraphRAG получил ответ.
|
||
**Удобство использования**: Простой интерфейс командной строки с разумными значениями по умолчанию.
|
||
|
||
## Предыстория
|
||
|
||
TrustGraph имеет две системы отслеживания происхождения:
|
||
|
||
1. **Отслеживание происхождения во время извлечения** (см. `extraction-time-provenance.md`): Записывает отношения документ → страница → фрагмент → ребро во время импорта. Хранится в графе с именем `urn:graph:source`, используя `prov:wasDerivedFrom`.
|
||
|
||
2. **Explainability во время запроса** (см. `query-time-explainability.md`): Записывает цепочку вопрос → исследование → фокус → синтез во время запросов GraphRAG. Хранится в графе с именем `urn:graph:retrieval`.
|
||
|
||
Текущие ограничения:
|
||
Нет простого способа визуализации иерархии документов после обработки.
|
||
Необходимо вручную запрашивать тройки для просмотра данных explainability.
|
||
Нет единого представления сессии GraphRAG.
|
||
|
||
## Технический дизайн
|
||
|
||
### Инструмент 1: tg-show-document-hierarchy
|
||
|
||
**Назначение**: При заданном идентификаторе документа, обходит и отображает все производные сущности.
|
||
|
||
**Использование**:
|
||
```bash
|
||
tg-show-document-hierarchy "urn:trustgraph:doc:abc123"
|
||
tg-show-document-hierarchy --show-content --max-content 500 "urn:trustgraph:doc:abc123"
|
||
```
|
||
|
||
**Аргументы**:
|
||
| Аргумент | Описание |
|
||
|-----|-------------|
|
||
| `document_id` | URI документа (позиционный) |
|
||
| `-u/--api-url` | URL шлюза (по умолчанию: `$TRUSTGRAPH_URL`) |
|
||
| `-t/--token` | Токен авторизации (по умолчанию: `$TRUSTGRAPH_TOKEN`) |
|
||
| `-U/--user` | Идентификатор пользователя (по умолчанию: `trustgraph`) |
|
||
| `-C/--collection` | Коллекция (по умолчанию: `default`) |
|
||
| `--show-content` | Включить содержимое блоба/документа |
|
||
| `--max-content` | Максимальное количество символов на блоб (по умолчанию: 200) |
|
||
| `--format` | Вывод: `tree` (по умолчанию), `json` |
|
||
|
||
**Реализация**:
|
||
1. Запрос троек: `?child prov:wasDerivedFrom <document_id>` в `urn:graph:source`
|
||
2. Рекурсивный запрос дочерних элементов каждого результата
|
||
3. Построение древовидной структуры: Документ → Страницы → Части
|
||
4. Если `--show-content`, получение содержимого из API librarian
|
||
5. Отображение в виде отформатированного дерева или 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 (вопросов) в коллекции.
|
||
|
||
**Использование**:
|
||
```bash
|
||
tg-list-explain-traces
|
||
tg-list-explain-traces --limit 20 --format json
|
||
```
|
||
|
||
**Аргументы**:
|
||
| Аргумент | Описание |
|
||
|-----|-------------|
|
||
| `-u/--api-url` | URL шлюза |
|
||
| `-t/--token` | Токен авторизации |
|
||
| `-U/--user` | Идентификатор пользователя |
|
||
| `-C/--collection` | Коллекция |
|
||
| `--limit` | Максимальное количество результатов (по умолчанию: 50) |
|
||
| `--format` | Вывод: `table` (по умолчанию), `json` |
|
||
|
||
**Реализация**:
|
||
1. Запрос: `?session tg:query ?text` в `urn:graph:retrieval`
|
||
2. Запрос временных меток: `?session prov:startedAtTime ?time`
|
||
3. Отображение в виде таблицы
|
||
|
||
**Пример вывода**:
|
||
```
|
||
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.
|
||
|
||
**Использование**:
|
||
```bash
|
||
tg-show-explain-trace "urn:trustgraph:question:abc123"
|
||
tg-show-explain-trace --max-answer 1000 --show-provenance "urn:trustgraph:question:abc123"
|
||
```
|
||
|
||
**Аргументы**:
|
||
| Аргумент | Описание |
|
||
|-----|-------------|
|
||
| `question_id` | URI вопроса (позиционный) |
|
||
| `-u/--api-url` | URL шлюза |
|
||
| `-t/--token` | Токен авторизации |
|
||
| `-U/--user` | Идентификатор пользователя |
|
||
| `-C/--collection` | Коллекция |
|
||
| `--max-answer` | Максимальное количество символов для ответа (по умолчанию: 500) |
|
||
| `--show-provenance` | Проследить связи к исходным документам |
|
||
| `--format` | Вывод: `text` (по умолчанию), `json` |
|
||
|
||
**Реализация**:
|
||
1. Получить текст вопроса из предиката `tg:query`
|
||
2. Найти исследование: `?exp prov:wasGeneratedBy <question_id>`
|
||
3. Найти фокус: `?focus prov:wasDerivedFrom <exploration_id>`
|
||
4. Получить выбранные связи: `<focus_id> tg:selectedEdge ?edge`
|
||
5. Для каждой связи, получить `tg:edge` (цитируемая тройка) и `tg:reasoning`
|
||
6. Найти синтез: `?synth prov:wasDerivedFrom <focus_id>`
|
||
7. Получить ответ из `tg:document` через библиотекаря
|
||
8. Если `--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 |
|
||
|
||
## Замечания по реализации
|
||
|
||
1. **Безопасность двоичного содержимого**: Попробуйте декодировать в UTF-8; если не удается, отобразите `[Binary: {size} bytes]`.
|
||
2. **Усечение**: Соблюдайте `--max-content`/`--max-answer` с индикатором `[truncated]`.
|
||
3. **Тройки в кавычках**: Разберите формат RDF-star из предиката `tg:edge`.
|
||
4. **Шаблоны**: Следуйте существующим шаблонам CLI из `query_graph.py`.
|
||
|
||
## Вопросы безопасности
|
||
|
||
Все запросы соответствуют границам пользователя/коллекции.
|
||
Поддерживается аутентификация по токену через `--token` или `$TRUSTGRAPH_TOKEN`.
|
||
|
||
## Стратегия тестирования
|
||
|
||
Ручная проверка с использованием образцовых данных:
|
||
```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"
|
||
```
|
||
|
||
## Ссылки
|
||
|
||
Объяснимость во время выполнения запроса: `docs/tech-specs/query-time-explainability.md`
|
||
Происхождение во время извлечения: `docs/tech-specs/extraction-time-provenance.md`
|
||
Существующий пример интерфейса командной строки: `trustgraph-cli/trustgraph/cli/invoke_graph_rag.py`
|