trustgraph/docs/tech-specs/extraction-flows.pt.md

layout	title	parent
default	Fluxos de Extração	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