mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 00:46:22 +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
355
docs/tech-specs/extraction-flows.pt.md
Normal file
355
docs/tech-specs/extraction-flows.pt.md
Normal file
|
|
@ -0,0 +1,355 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Fluxos de Extração"
|
||||
parent: "Portuguese (Beta)"
|
||||
---
|
||||
|
||||
# Fluxos de Extração
|
||||
|
||||
> **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.
|
||||
|
||||
Este documento descreve como os dados fluem através do pipeline de extração do TrustGraph, desde o envio do documento até ao armazenamento nos repositórios de conhecimento.
|
||||
|
||||
## Visão Geral
|
||||
|
||||
```
|
||||
┌──────────┐ ┌─────────────┐ ┌─────────┐ ┌────────────────────┐
|
||||
│ Librarian│────▶│ PDF Decoder │────▶│ Chunker │────▶│ Knowledge │
|
||||
│ │ │ (PDF only) │ │ │ │ Extraction │
|
||||
│ │────────────────────────▶│ │ │ │
|
||||
└──────────┘ └─────────────┘ └─────────┘ └────────────────────┘
|
||||
│ │
|
||||
│ ├──▶ Triples
|
||||
│ ├──▶ Entity Contexts
|
||||
│ └──▶ Rows
|
||||
│
|
||||
└──▶ Document Embeddings
|
||||
```
|
||||
|
||||
## Armazenamento de Conteúdo
|
||||
|
||||
### Armazenamento de Blobs (S3/Minio)
|
||||
|
||||
O conteúdo do documento é armazenado em armazenamento de blobs compatível com S3:
|
||||
Formato do caminho: `doc/{object_id}`, onde object_id é um UUID
|
||||
Todos os tipos de documentos armazenados aqui: documentos de origem, páginas, trechos
|
||||
|
||||
### Armazenamento de Metadados (Cassandra)
|
||||
|
||||
Os metadados do documento armazenados no Cassandra incluem:
|
||||
ID do documento, título, tipo (MIME)
|
||||
Referência ao armazenamento de blobs `object_id`
|
||||
Referência `parent_id` para documentos filhos (páginas, trechos)
|
||||
`document_type`: "source", "page", "chunk", "answer"
|
||||
|
||||
### Limiar de Incorporação vs. Streaming
|
||||
|
||||
A transmissão de conteúdo usa uma estratégia baseada no tamanho:
|
||||
**< 2MB**: O conteúdo é incluído inline na mensagem (codificado em base64)
|
||||
**≥ 2MB**: Apenas `document_id` é enviado; o processador busca via API do bibliotecário
|
||||
|
||||
## Etapa 1: Envio de Documento (Bibliotecário)
|
||||
|
||||
### Ponto de Entrada
|
||||
|
||||
Os documentos entram no sistema através da operação `add-document` do bibliotecário:
|
||||
1. O conteúdo é carregado no armazenamento de blobs
|
||||
2. Um registro de metadados é criado no Cassandra
|
||||
3. Retorna o ID do documento
|
||||
|
||||
### Disparando a Extração
|
||||
|
||||
A operação `add-processing` dispara a extração:
|
||||
Especifica `document_id`, `flow` (ID do pipeline), `collection` (loja de destino)
|
||||
A operação `load_document()` do bibliotecário busca o conteúdo e o publica na fila de entrada do fluxo
|
||||
|
||||
### Esquema: Documento
|
||||
|
||||
```
|
||||
Document
|
||||
├── metadata: Metadata
|
||||
│ ├── id: str # Document identifier
|
||||
│ ├── user: str # Tenant/user ID
|
||||
│ ├── collection: str # Target collection
|
||||
│ └── metadata: list[Triple] # (largely unused, historical)
|
||||
├── data: bytes # PDF content (base64, if inline)
|
||||
└── document_id: str # Librarian reference (if streaming)
|
||||
```
|
||||
|
||||
**Roteamento**: Baseado no campo `kind`:
|
||||
`application/pdf` → fila `document-load` → Decodificador PDF
|
||||
`text/plain` → fila `text-load` → Fragmentador
|
||||
|
||||
## Etapa 2: Decodificador PDF
|
||||
|
||||
Converte documentos PDF em páginas de texto.
|
||||
|
||||
### Processo
|
||||
|
||||
1. Buscar conteúdo (inline `data` ou via `document_id` do bibliotecário)
|
||||
2. Extrair páginas usando PyPDF
|
||||
3. Para cada página:
|
||||
Salvar como documento filho no bibliotecário (`{doc_id}/p{page_num}`)
|
||||
Emitir triplas de procedência (página derivada do documento)
|
||||
Enviar para o fragmentador
|
||||
|
||||
### Esquema: TextDocument
|
||||
|
||||
```
|
||||
TextDocument
|
||||
├── metadata: Metadata
|
||||
│ ├── id: str # Page URI (e.g., https://trustgraph.ai/doc/xxx/p1)
|
||||
│ ├── user: str
|
||||
│ ├── collection: str
|
||||
│ └── metadata: list[Triple]
|
||||
├── text: bytes # Page text content (if inline)
|
||||
└── document_id: str # Librarian reference (e.g., "doc123/p1")
|
||||
```
|
||||
|
||||
## Etapa 3: Divisor em Blocos
|
||||
|
||||
Divide o texto em blocos de tamanho configurado.
|
||||
|
||||
### Parâmetros (configuráveis no fluxo)
|
||||
|
||||
`chunk_size`: Tamanho do bloco alvo em caracteres (padrão: 2000)
|
||||
`chunk_overlap`: Sobreposição entre blocos (padrão: 100)
|
||||
|
||||
### Processo
|
||||
|
||||
1. Buscar o conteúdo do texto (inline ou via bibliotecário)
|
||||
2. Dividir usando o divisor de caracteres recursivo
|
||||
3. Para cada bloco:
|
||||
Salvar como documento filho no bibliotecário (`{parent_id}/c{index}`)
|
||||
Emitir triplas de procedência (bloco derivado da página/documento)
|
||||
Encaminhar para os processadores de extração
|
||||
|
||||
### Esquema: Bloco
|
||||
|
||||
```
|
||||
Chunk
|
||||
├── metadata: Metadata
|
||||
│ ├── id: str # Chunk URI
|
||||
│ ├── user: str
|
||||
│ ├── collection: str
|
||||
│ └── metadata: list[Triple]
|
||||
├── chunk: bytes # Chunk text content
|
||||
└── document_id: str # Librarian chunk ID (e.g., "doc123/p1/c3")
|
||||
```
|
||||
|
||||
### Hierarquia de Identificação de Documentos
|
||||
|
||||
Documentos filhos codificam sua linhagem no ID:
|
||||
Fonte: `doc123`
|
||||
Página: `doc123/p5`
|
||||
Trecho da página: `doc123/p5/c2`
|
||||
Trecho de texto: `doc123/c2`
|
||||
|
||||
## Etapa 4: Extração de Conhecimento
|
||||
|
||||
Múltiplos padrões de extração disponíveis, selecionados pela configuração do fluxo.
|
||||
|
||||
### Padrão A: Basic GraphRAG
|
||||
|
||||
Dois processadores paralelos:
|
||||
|
||||
**kg-extract-definitions**
|
||||
Entrada: Trecho
|
||||
Saída: Triplas (definições de entidades), Contextos de Entidade
|
||||
Extrai: rótulos de entidades, definições
|
||||
|
||||
**kg-extract-relationships**
|
||||
Entrada: Trecho
|
||||
Saída: Triplas (relacionamentos), Contextos de Entidade
|
||||
Extrai: relações sujeito-predicado-objeto
|
||||
|
||||
### Padrão B: Orientado a Ontologia (kg-extract-ontology)
|
||||
|
||||
Entrada: Trecho
|
||||
Saída: Triplas, Contextos de Entidade
|
||||
Utiliza uma ontologia configurada para guiar a extração
|
||||
|
||||
### Padrão C: Baseado em Agente (kg-extract-agent)
|
||||
|
||||
Entrada: Trecho
|
||||
Saída: Triplas, Contextos de Entidade
|
||||
Utiliza um framework de agente para a extração
|
||||
|
||||
### Padrão D: Extração de Linhas (kg-extract-rows)
|
||||
|
||||
Entrada: Trecho
|
||||
Saída: Linhas (dados estruturados, não triplas)
|
||||
Utiliza uma definição de esquema para extrair registros estruturados
|
||||
|
||||
### Esquema: Triplas
|
||||
|
||||
```
|
||||
Triples
|
||||
├── metadata: Metadata
|
||||
│ ├── id: str
|
||||
│ ├── user: str
|
||||
│ ├── collection: str
|
||||
│ └── metadata: list[Triple] # (set to [] by extractors)
|
||||
└── triples: list[Triple]
|
||||
└── Triple
|
||||
├── s: Term # Subject
|
||||
├── p: Term # Predicate
|
||||
├── o: Term # Object
|
||||
└── g: str | None # Named graph
|
||||
```
|
||||
|
||||
### Esquema: EntityContexts
|
||||
|
||||
```
|
||||
EntityContexts
|
||||
├── metadata: Metadata
|
||||
└── entities: list[EntityContext]
|
||||
└── EntityContext
|
||||
├── entity: Term # Entity identifier (IRI)
|
||||
├── context: str # Textual description for embedding
|
||||
└── chunk_id: str # Source chunk ID (provenance)
|
||||
```
|
||||
|
||||
### Esquema: Linhas
|
||||
|
||||
```
|
||||
Rows
|
||||
├── metadata: Metadata
|
||||
├── row_schema: RowSchema
|
||||
│ ├── name: str
|
||||
│ ├── description: str
|
||||
│ └── fields: list[Field]
|
||||
└── rows: list[dict[str, str]] # Extracted records
|
||||
```
|
||||
|
||||
## Etapa 5: Geração de Embeddings
|
||||
|
||||
### Embeddings de Grafos
|
||||
|
||||
Converte contextos de entidades em embeddings vetoriais.
|
||||
|
||||
**Processo:**
|
||||
1. Receber EntityContexts
|
||||
2. Chamar o serviço de embeddings com o texto do contexto
|
||||
3. Output GraphEmbeddings (mapeamento de entidade para vetor)
|
||||
|
||||
**Esquema: GraphEmbeddings**
|
||||
|
||||
```
|
||||
GraphEmbeddings
|
||||
├── metadata: Metadata
|
||||
└── entities: list[EntityEmbeddings]
|
||||
└── EntityEmbeddings
|
||||
├── entity: Term # Entity identifier
|
||||
├── vector: list[float] # Embedding vector
|
||||
└── chunk_id: str # Source chunk (provenance)
|
||||
```
|
||||
|
||||
### Incorporações de Documentos
|
||||
|
||||
Converte texto em partes diretamente em incorporações vetoriais.
|
||||
|
||||
**Processo:**
|
||||
1. Receber Parte (Chunk)
|
||||
2. Chamar o serviço de incorporação com o texto da parte
|
||||
3. Saída: Incorporações de Documento (DocumentEmbeddings)
|
||||
|
||||
**Esquema: Incorporações de Documento (DocumentEmbeddings)**
|
||||
|
||||
```
|
||||
DocumentEmbeddings
|
||||
├── metadata: Metadata
|
||||
└── chunks: list[ChunkEmbeddings]
|
||||
└── ChunkEmbeddings
|
||||
├── chunk_id: str # Chunk identifier
|
||||
└── vector: list[float] # Embedding vector
|
||||
```
|
||||
|
||||
### Incorporações de Linhas
|
||||
|
||||
Converte campos de índice de linha em incorporações vetoriais.
|
||||
|
||||
**Processo:**
|
||||
1. Receber Linhas
|
||||
2. Incorporar campos de índice configurados
|
||||
3. Saída para o armazenamento vetorial de linhas
|
||||
|
||||
## Fase 6: Armazenamento
|
||||
|
||||
### Armazenamento Triplo
|
||||
|
||||
Recebe: Triplas
|
||||
Armazenamento: Cassandra (tabelas centradas em entidades)
|
||||
Grafos nomeados separam o conhecimento central da procedência:
|
||||
`""` (padrão): Fatos de conhecimento central
|
||||
`urn:graph:source`: Procedência de extração
|
||||
`urn:graph:retrieval`: Explicabilidade em tempo de consulta
|
||||
|
||||
### Armazenamento Vetorial (Incorporações de Grafos)
|
||||
|
||||
Recebe: Incorporações de Grafos
|
||||
Armazenamento: Qdrant, Milvus ou Pinecone
|
||||
Indexado por: IRI da entidade
|
||||
Metadados: chunk_id para procedência
|
||||
|
||||
### Armazenamento Vetorial (Incorporações de Documentos)
|
||||
|
||||
Recebe: Incorporações de Documentos
|
||||
Armazenamento: Qdrant, Milvus ou Pinecone
|
||||
Indexado por: chunk_id
|
||||
|
||||
### Armazenamento de Linhas
|
||||
|
||||
Recebe: Linhas
|
||||
Armazenamento: Cassandra
|
||||
Estrutura de tabela orientada por esquema
|
||||
|
||||
### Armazenamento Vetorial de Linhas
|
||||
|
||||
Recebe: Incorporações de linhas
|
||||
Armazenamento: Banco de dados vetorial
|
||||
Indexado por: campos de índice de linha
|
||||
|
||||
## Análise de Campos de Metadados
|
||||
|
||||
### Campos Ativamente Utilizados
|
||||
|
||||
| Campo | Uso |
|
||||
|-------|-------|
|
||||
| `metadata.id` | Identificador de documento/fragmento, registro, procedência |
|
||||
| `metadata.user` | Multilocação, roteamento de armazenamento |
|
||||
| `metadata.collection` | Seleção de coleção de destino |
|
||||
| `document_id` | Referência do bibliotecário, vinculação de procedência |
|
||||
| `chunk_id` | Rastreamento de procedência através do pipeline |
|
||||
|
||||
<<<<<<< HEAD
|
||||
### Campos Potencialmente Redundantes
|
||||
|
||||
| Campo | Status |
|
||||
|-------|--------|
|
||||
| `metadata.metadata` | Definido como `[]` por todos os extratores; metadados de nível de documento agora gerenciados pelo bibliotecário no momento do envio |
|
||||
=======
|
||||
### Campos Removidos
|
||||
|
||||
| Campo | Status |
|
||||
|-------|--------|
|
||||
| `metadata.metadata` | Removido da classe `Metadata`. Triplas de metadados de nível de documento agora são emitidas diretamente pelo bibliotecário para o armazenamento de triplas no momento do envio, e não são transmitidas através do pipeline de extração. |
|
||||
>>>>>>> e3bcbf73 (The metadata field (list of triples) in the pipeline Metadata class)
|
||||
|
||||
### Padrão de Campos de Bytes
|
||||
|
||||
Todos os campos de conteúdo (`data`, `text`, `chunk`) são `bytes`, mas são imediatamente decodificados para strings UTF-8 por todos os processadores. Nenhum processador usa bytes brutos.
|
||||
|
||||
## Configuração do Fluxo
|
||||
|
||||
Os fluxos são definidos externamente e fornecidos ao bibliotecário através do serviço de configuração. Cada fluxo especifica:
|
||||
|
||||
Filas de entrada (`text-load`, `document-load`)
|
||||
Cadeia de processadores
|
||||
Parâmetros (tamanho do fragmento, método de extração, etc.)
|
||||
|
||||
Padrões de fluxo de exemplo:
|
||||
`pdf-graphrag`: PDF → Decodificador → Fragmentador → Definições + Relacionamentos → Incorporações
|
||||
`text-graphrag`: Texto → Fragmentador → Definições + Relacionamentos → Incorporações
|
||||
`pdf-ontology`: PDF → Decodificador → Fragmentador → Extração de Ontologia → Incorporações
|
||||
`text-rows`: Texto → Fragmentador → Extração de Linhas → Armazenamento de Linhas
|
||||
Loading…
Add table
Add a link
Reference in a new issue