mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-25 08:26: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
GitHub
parent
19f73e4cdc
commit
f95fd4f052
560 changed files with 236300 additions and 99 deletions
271
docs/tech-specs/query-time-explainability.pt.md
Normal file
271
docs/tech-specs/query-time-explainability.pt.md
Normal file
|
|
@ -0,0 +1,271 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Explicabilidade em Tempo de Consulta"
|
||||
parent: "Portuguese (Beta)"
|
||||
---
|
||||
|
||||
# Explicabilidade em Tempo de Consulta
|
||||
|
||||
> **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
|
||||
|
||||
Implementado
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Esta especificação descreve como o GraphRAG registra e comunica dados de explicabilidade durante a execução da consulta. O objetivo é a rastreabilidade completa: desde a resposta final, passando pelas arestas selecionadas, até aos documentos de origem.
|
||||
|
||||
A explicabilidade em tempo de consulta captura o que o pipeline do GraphRAG fez durante o raciocínio. Isso se conecta à rastreabilidade em tempo de extração, que registra a origem dos fatos do grafo de conhecimento.
|
||||
|
||||
## Terminologia
|
||||
|
||||
| Termo | Definição |
|
||||
|------|------------|
|
||||
| **Explicabilidade** | O registro de como um resultado foi derivado |
|
||||
| **Sessão** | Uma única execução de consulta do GraphRAG |
|
||||
| **Seleção de Arestas** | Seleção de arestas relevantes impulsionada por LLM, com raciocínio |
|
||||
| **Cadeia de Rastreabilidade** | Caminho de aresta → trecho → página → documento |
|
||||
|
||||
## Arquitetura
|
||||
|
||||
### Fluxo de Explicabilidade
|
||||
|
||||
```
|
||||
GraphRAG Query
|
||||
│
|
||||
├─► Session Activity
|
||||
│ └─► Query text, timestamp
|
||||
│
|
||||
├─► Retrieval Entity
|
||||
│ └─► All edges retrieved from subgraph
|
||||
│
|
||||
├─► Selection Entity
|
||||
│ └─► Selected edges with LLM reasoning
|
||||
│ └─► Each edge links to extraction provenance
|
||||
│
|
||||
└─► Answer Entity
|
||||
└─► Reference to synthesized response (in librarian)
|
||||
```
|
||||
|
||||
### Pipeline de GraphRAG em Duas Etapas
|
||||
|
||||
1. **Seleção de Arestas**: O LLM seleciona as arestas relevantes do subgrafo, fornecendo a justificativa para cada uma.
|
||||
2. **Síntese**: O LLM gera a resposta a partir das arestas selecionadas.
|
||||
|
||||
Essa separação permite a explicabilidade - sabemos exatamente quais arestas contribuíram.
|
||||
|
||||
### Armazenamento
|
||||
|
||||
Triplas de explicabilidade armazenadas em uma coleção configurável (padrão: `explainability`).
|
||||
Utiliza a ontologia PROV-O para relações de procedência.
|
||||
Reificação RDF-star para referências de arestas.
|
||||
O conteúdo da resposta é armazenado no serviço de bibliotecário (não inline - muito grande).
|
||||
|
||||
### Streaming em Tempo Real
|
||||
|
||||
Os eventos de explicabilidade são transmitidos ao cliente enquanto a consulta é executada:
|
||||
|
||||
1. Sessão criada → evento emitido.
|
||||
2. Arestas recuperadas → evento emitido.
|
||||
3. Arestas selecionadas com justificativa → evento emitido.
|
||||
4. Resposta sintetizada → evento emitido.
|
||||
|
||||
O cliente recebe `explain_id` e `explain_collection` para buscar detalhes completos.
|
||||
|
||||
## Estrutura de URI
|
||||
|
||||
Todos os URIs usam o namespace `urn:trustgraph:` com UUIDs:
|
||||
|
||||
| Entidade | Padrão de URI |
|
||||
|--------|-------------|
|
||||
| Sessão | `urn:trustgraph:session:{uuid}` |
|
||||
| Recuperação | `urn:trustgraph:prov:retrieval:{uuid}` |
|
||||
| Seleção | `urn:trustgraph:prov:selection:{uuid}` |
|
||||
| Resposta | `urn:trustgraph:prov:answer:{uuid}` |
|
||||
| Seleção de Aresta | `urn:trustgraph:prov:edge:{uuid}:{index}` |
|
||||
|
||||
## Modelo RDF (PROV-O)
|
||||
|
||||
### Atividade da Sessão
|
||||
|
||||
```turtle
|
||||
<session-uri> a prov:Activity ;
|
||||
rdfs:label "GraphRAG query session" ;
|
||||
prov:startedAtTime "2024-01-15T10:30:00Z" ;
|
||||
tg:query "What was the War on Terror?" .
|
||||
```
|
||||
|
||||
### Entidade de Recuperação
|
||||
|
||||
```turtle
|
||||
<retrieval-uri> a prov:Entity ;
|
||||
rdfs:label "Retrieved edges" ;
|
||||
prov:wasGeneratedBy <session-uri> ;
|
||||
tg:edgeCount 50 .
|
||||
```
|
||||
|
||||
### Entidade de Seleção
|
||||
|
||||
```turtle
|
||||
<selection-uri> a prov:Entity ;
|
||||
rdfs:label "Selected edges" ;
|
||||
prov:wasDerivedFrom <retrieval-uri> ;
|
||||
tg:selectedEdge <edge-sel-0> ;
|
||||
tg:selectedEdge <edge-sel-1> .
|
||||
|
||||
<edge-sel-0> tg:edge << <s> <p> <o> >> ;
|
||||
tg:reasoning "This edge establishes the key relationship..." .
|
||||
```
|
||||
|
||||
### Entidade de Resposta
|
||||
|
||||
```turtle
|
||||
<answer-uri> a prov:Entity ;
|
||||
rdfs:label "GraphRAG answer" ;
|
||||
prov:wasDerivedFrom <selection-uri> ;
|
||||
tg:document <urn:trustgraph:answer:{uuid}> .
|
||||
```
|
||||
|
||||
A `tg:document` referencia a resposta armazenada no serviço de bibliotecário.
|
||||
|
||||
## Constantes do Namespace
|
||||
|
||||
Definido em `trustgraph-base/trustgraph/provenance/namespaces.py`:
|
||||
|
||||
| Constante | URI |
|
||||
|----------|-----|
|
||||
| `TG_QUERY` | `https://trustgraph.ai/ns/query` |
|
||||
| `TG_EDGE_COUNT` | `https://trustgraph.ai/ns/edgeCount` |
|
||||
| `TG_SELECTED_EDGE` | `https://trustgraph.ai/ns/selectedEdge` |
|
||||
| `TG_EDGE` | `https://trustgraph.ai/ns/edge` |
|
||||
| `TG_REASONING` | `https://trustgraph.ai/ns/reasoning` |
|
||||
| `TG_CONTENT` | `https://trustgraph.ai/ns/content` |
|
||||
| `TG_DOCUMENT` | `https://trustgraph.ai/ns/document` |
|
||||
|
||||
## Esquema GraphRagResponse
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class GraphRagResponse:
|
||||
error: Error | None = None
|
||||
response: str = ""
|
||||
end_of_stream: bool = False
|
||||
explain_id: str | None = None
|
||||
explain_collection: str | None = None
|
||||
message_type: str = "" # "chunk" or "explain"
|
||||
end_of_session: bool = False
|
||||
```
|
||||
|
||||
### Tipos de Mensagem
|
||||
|
||||
| message_type | Propósito |
|
||||
|--------------|---------|
|
||||
| `chunk` | Texto de resposta (em fluxo ou final) |
|
||||
| `explain` | Evento de explicabilidade com referência IRI |
|
||||
|
||||
### Ciclo de Vida da Sessão
|
||||
|
||||
1. Múltiplas mensagens `explain` (sessão, recuperação, seleção, resposta)
|
||||
2. Múltiplas mensagens `chunk` (resposta em fluxo)
|
||||
3. Mensagem `chunk` final com `end_of_session=True`
|
||||
|
||||
## Formato de Seleção de Arestas
|
||||
|
||||
O LLM retorna JSONL com as arestas selecionadas:
|
||||
|
||||
```jsonl
|
||||
{"id": "edge-hash-1", "reasoning": "This edge shows the key relationship..."}
|
||||
{"id": "edge-hash-2", "reasoning": "Provides supporting evidence..."}
|
||||
```
|
||||
|
||||
O `id` é um hash de `(labeled_s, labeled_p, labeled_o)` calculado por `edge_id()`.
|
||||
|
||||
## Preservação de URIs
|
||||
|
||||
### O Problema
|
||||
|
||||
O GraphRAG exibe rótulos legíveis para humanos para o LLM, mas a explicabilidade precisa de URIs originais para rastreamento de origem.
|
||||
|
||||
### Solução
|
||||
|
||||
`get_labelgraph()` retorna ambos:
|
||||
`labeled_edges`: Lista de `(label_s, label_p, label_o)` para o LLM
|
||||
`uri_map`: Dicionário mapeando `edge_id(labels)` → `(uri_s, uri_p, uri_o)`
|
||||
|
||||
Ao armazenar dados de explicabilidade, os URIs de `uri_map` são usados.
|
||||
|
||||
## Rastreamento de Origem
|
||||
|
||||
### Do Borda à Fonte
|
||||
|
||||
As arestas selecionadas podem ser rastreadas de volta aos documentos de origem:
|
||||
|
||||
1. Consulta para o subgrafo contendo: `?subgraph tg:contains <<s p o>>`
|
||||
2. Siga a cadeia `prov:wasDerivedFrom` até o documento raiz
|
||||
3. Cada etapa na cadeia: chunk → página → documento
|
||||
|
||||
### Suporte de Triplas Citadas do Cassandra
|
||||
|
||||
O serviço de consulta do Cassandra suporta a correspondência de triplas citadas:
|
||||
|
||||
```python
|
||||
# In get_term_value():
|
||||
elif term.type == TRIPLE:
|
||||
return serialize_triple(term.triple)
|
||||
```
|
||||
|
||||
Isso permite consultas como:
|
||||
```
|
||||
?subgraph tg:contains <<http://example.org/s http://example.org/p "value">>
|
||||
```
|
||||
|
||||
## Uso da Interface de Linha de Comando (CLI)
|
||||
|
||||
```bash
|
||||
tg-invoke-graph-rag --explainable -q "What was the War on Terror?"
|
||||
```
|
||||
|
||||
### Formato de Saída
|
||||
|
||||
```
|
||||
[session] urn:trustgraph:session:abc123
|
||||
|
||||
[retrieval] urn:trustgraph:prov:retrieval:abc123
|
||||
|
||||
[selection] urn:trustgraph:prov:selection:abc123
|
||||
Selected 12 edge(s)
|
||||
Edge: (Guantanamo, definition, A detention facility...)
|
||||
Reason: Directly connects Guantanamo to the War on Terror
|
||||
Source: Chunk 1 → Page 2 → Beyond the Vigilant State
|
||||
|
||||
[answer] urn:trustgraph:prov:answer:abc123
|
||||
|
||||
Based on the provided knowledge statements...
|
||||
```
|
||||
|
||||
### Recursos
|
||||
|
||||
Eventos de explicabilidade em tempo real durante a consulta.
|
||||
Resolução de rótulos para componentes de borda via `rdfs:label`.
|
||||
Rastreamento da cadeia de origem via `prov:wasDerivedFrom`.
|
||||
Cache de rótulos para evitar consultas repetidas.
|
||||
|
||||
## Arquivos Implementados
|
||||
|
||||
| Arquivo | Propósito |
|
||||
|------|---------|
|
||||
| `trustgraph-base/trustgraph/provenance/uris.py` | Geradores de URI |
|
||||
| `trustgraph-base/trustgraph/provenance/namespaces.py` | Constantes de namespace RDF |
|
||||
| `trustgraph-base/trustgraph/provenance/triples.py` | Construtores de triplas |
|
||||
| `trustgraph-base/trustgraph/schema/services/retrieval.py` | Esquema GraphRagResponse |
|
||||
| `trustgraph-flow/trustgraph/retrieval/graph_rag/graph_rag.py` | Núcleo GraphRAG com preservação de URI |
|
||||
| `trustgraph-flow/trustgraph/retrieval/graph_rag/rag.py` | Serviço com integração de bibliotecário |
|
||||
| `trustgraph-flow/trustgraph/query/triples/cassandra/service.py` | Suporte para consultas de triplas entre aspas |
|
||||
| `trustgraph-cli/trustgraph/cli/invoke_graph_rag.py` | CLI com exibição de explicabilidade |
|
||||
|
||||
## Referências
|
||||
|
||||
PROV-O (Ontologia de Proveniência W3C): https://www.w3.org/TR/prov-o/
|
||||
RDF-star: https://w3c.github.io/rdf-star/
|
||||
Proveniência no momento da extração: `docs/tech-specs/extraction-time-provenance.md`
|
||||
Loading…
Add table
Add a link
Reference in a new issue