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
8.4 KiB
Markdown
228 lines
8.4 KiB
Markdown
---
|
|
layout: default
|
|
title: "Especificação Técnica da Interface de Linha de Comando (CLI) para Explicabilidade"
|
|
parent: "Portuguese (Beta)"
|
|
---
|
|
|
|
# Especificação Técnica da Interface de Linha de Comando (CLI) para Explicabilidade
|
|
|
|
> **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.
|
|
|
|
## Status
|
|
|
|
Rascunho
|
|
|
|
## Visão Geral
|
|
|
|
Esta especificação descreve ferramentas de linha de comando para depurar e explorar dados de explicabilidade no TrustGraph. Essas ferramentas permitem que os usuários rastreiem como as respostas foram derivadas e depurem a cadeia de origem desde as arestas até os documentos de origem.
|
|
|
|
Três ferramentas de linha de comando:
|
|
|
|
1. **`tg-show-document-hierarchy`** - Mostrar a hierarquia de documento → página → trecho → aresta
|
|
2. **`tg-list-explain-traces`** - Listar todas as sessões GraphRAG com perguntas
|
|
3. **`tg-show-explain-trace`** - Mostrar o rastreamento completo de explicabilidade para uma sessão
|
|
|
|
## Objetivos
|
|
|
|
**Depuração**: Permitir que os desenvolvedores inspecionem os resultados do processamento de documentos
|
|
**Auditabilidade**: Rastrear qualquer fato extraído de volta ao seu documento de origem
|
|
**Transparência**: Mostrar exatamente como o GraphRAG derivou uma resposta
|
|
**Usabilidade**: Interface de linha de comando simples com configurações padrão sensatas
|
|
|
|
## Contexto
|
|
|
|
O TrustGraph possui dois sistemas de rastreabilidade:
|
|
|
|
1. **Rastreabilidade em tempo de extração** (veja `extraction-time-provenance.md`): Registra os relacionamentos de documento → página → trecho → aresta durante a ingestão. Armazenado em um grafo chamado `urn:graph:source` usando `prov:wasDerivedFrom`.
|
|
|
|
2. **Explicabilidade em tempo de consulta** (veja `query-time-explainability.md`): Registra a cadeia de pergunta → exploração → foco → síntese durante as consultas GraphRAG. Armazenado em um grafo chamado `urn:graph:retrieval`.
|
|
|
|
Limitações atuais:
|
|
Não há uma maneira fácil de visualizar a hierarquia de documentos após o processamento
|
|
É necessário consultar manualmente as triplas para ver os dados de explicabilidade
|
|
Não há uma visão consolidada de uma sessão GraphRAG
|
|
|
|
## Design Técnico
|
|
|
|
### Ferramenta 1: tg-show-document-hierarchy
|
|
|
|
**Propósito**: Dado um ID de documento, percorrer e exibir todas as entidades derivadas.
|
|
|
|
**Uso**:
|
|
```bash
|
|
tg-show-document-hierarchy "urn:trustgraph:doc:abc123"
|
|
tg-show-document-hierarchy --show-content --max-content 500 "urn:trustgraph:doc:abc123"
|
|
```
|
|
|
|
**Argumentos**:
|
|
| Arg | Descrição |
|
|
|-----|-------------|
|
|
| `document_id` | URI do documento (posicional) |
|
|
| `-u/--api-url` | URL do gateway (padrão: `$TRUSTGRAPH_URL`) |
|
|
| `-t/--token` | Token de autenticação (padrão: `$TRUSTGRAPH_TOKEN`) |
|
|
| `-U/--user` | ID do usuário (padrão: `trustgraph`) |
|
|
| `-C/--collection` | Coleção (padrão: `default`) |
|
|
| `--show-content` | Incluir conteúdo do blob/documento |
|
|
| `--max-content` | Máximo de caracteres por blob (padrão: 200) |
|
|
| `--format` | Saída: `tree` (padrão), `json` |
|
|
|
|
**Implementação**:
|
|
1. Consultar triplas: `?child prov:wasDerivedFrom <document_id>` em `urn:graph:source`
|
|
2. Consultar recursivamente os filhos de cada resultado
|
|
3. Construir estrutura de árvore: Documento → Páginas → Blocos
|
|
4. Se `--show-content`, buscar conteúdo da API do bibliotecário
|
|
5. Exibir como árvore indentada ou JSON
|
|
|
|
**Exemplo de Saída**:
|
|
```
|
|
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]
|
|
```
|
|
|
|
### Ferramenta 2: tg-list-explain-traces
|
|
|
|
**Propósito**: Listar todas as sessões (perguntas) do GraphRAG em uma coleção.
|
|
|
|
**Uso**:
|
|
```bash
|
|
tg-list-explain-traces
|
|
tg-list-explain-traces --limit 20 --format json
|
|
```
|
|
|
|
**Argumentos**:
|
|
| Arg | Descrição |
|
|
|-----|-------------|
|
|
| `-u/--api-url` | URL do gateway |
|
|
| `-t/--token` | Token de autenticação |
|
|
| `-U/--user` | ID do usuário |
|
|
| `-C/--collection` | Coleção |
|
|
| `--limit` | Resultados máximos (padrão: 50) |
|
|
| `--format` | Saída: `table` (padrão), `json` |
|
|
|
|
**Implementação**:
|
|
1. Consulta: `?session tg:query ?text` em `urn:graph:retrieval`
|
|
2. Consulta de carimbos de data/hora: `?session prov:startedAtTime ?time`
|
|
3. Exibir como tabela
|
|
|
|
**Exemplo de Saída**:
|
|
```
|
|
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
|
|
```
|
|
|
|
### Ferramenta 3: tg-show-explain-trace
|
|
|
|
**Propósito**: Mostrar a cascata completa de explicabilidade para uma sessão GraphRAG.
|
|
|
|
**Uso**:
|
|
```bash
|
|
tg-show-explain-trace "urn:trustgraph:question:abc123"
|
|
tg-show-explain-trace --max-answer 1000 --show-provenance "urn:trustgraph:question:abc123"
|
|
```
|
|
|
|
**Argumentos**:
|
|
| Arg | Descrição |
|
|
|-----|-------------|
|
|
| `question_id` | URI da pergunta (posicional) |
|
|
| `-u/--api-url` | URL do gateway |
|
|
| `-t/--token` | Token de autenticação |
|
|
| `-U/--user` | ID do usuário |
|
|
| `-C/--collection` | Coleção |
|
|
| `--max-answer` | Número máximo de caracteres para a resposta (padrão: 500) |
|
|
| `--show-provenance` | Rastrear arestas para documentos de origem |
|
|
| `--format` | Saída: `text` (padrão), `json` |
|
|
|
|
**Implementação**:
|
|
1. Obter o texto da pergunta do predicado `tg:query`
|
|
2. Encontrar a exploração: `?exp prov:wasGeneratedBy <question_id>`
|
|
3. Encontrar o foco: `?focus prov:wasDerivedFrom <exploration_id>`
|
|
4. Obter as arestas selecionadas: `<focus_id> tg:selectedEdge ?edge`
|
|
5. Para cada aresta, obter `tg:edge` (tripla entre aspas) e `tg:reasoning`
|
|
6. Encontrar a síntese: `?synth prov:wasDerivedFrom <focus_id>`
|
|
7. Obter a resposta de `tg:document` através do bibliotecário
|
|
8. Se `--show-provenance`, rastrear as arestas para os documentos de origem
|
|
|
|
**Exemplo de Saída**:
|
|
```
|
|
=== 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]
|
|
```
|
|
|
|
## Arquivos a Criar
|
|
|
|
| Arquivo | Propósito |
|
|
|------|---------|
|
|
| `trustgraph-cli/trustgraph/cli/show_document_hierarchy.py` | Ferramenta 1 |
|
|
| `trustgraph-cli/trustgraph/cli/list_explain_traces.py` | Ferramenta 2 |
|
|
| `trustgraph-cli/trustgraph/cli/show_explain_trace.py` | Ferramenta 3 |
|
|
|
|
## Arquivos a Modificar
|
|
|
|
| Arquivo | Alteração |
|
|
|------|--------|
|
|
| `trustgraph-cli/setup.py` | Adicionar entradas de console_scripts |
|
|
|
|
## Notas de Implementação
|
|
|
|
1. **Segurança do conteúdo binário**: Tente decodificar UTF-8; se falhar, mostre `[Binary: {size} bytes]`
|
|
2. **Truncamento**: Respeite `--max-content`/`--max-answer` com indicador `[truncated]`
|
|
3. **Triplas entre aspas**: Analise o formato RDF-star a partir do predicado `tg:edge`
|
|
4. **Padrões**: Siga os padrões de CLI existentes a partir de `query_graph.py`
|
|
|
|
## Considerações de Segurança
|
|
|
|
Todas as consultas respeitam os limites de usuário/coleção
|
|
Autenticação por token suportada via `--token` ou `$TRUSTGRAPH_TOKEN`
|
|
|
|
## Estratégia de Teste
|
|
|
|
Verificação manual com dados de amostra:
|
|
```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"
|
|
```
|
|
|
|
## Referências
|
|
|
|
Explicabilidade em tempo de consulta: `docs/tech-specs/query-time-explainability.md`
|
|
Proveniência em tempo de extração: `docs/tech-specs/extraction-time-provenance.md`
|
|
Exemplo de CLI existente: `trustgraph-cli/trustgraph/cli/invoke_graph_rag.py`
|