trustgraph/docs/tech-specs/universal-decoder.pt.md

layout	title	parent
default	Decodificador Universal de Documentos	Portuguese (Beta)

Decodificador Universal de Documentos

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.

Título

Decodificador universal de documentos alimentado por unstructured — ingira qualquer formato de documento comum através de um único serviço com total rastreabilidade e integração com o sistema de gerenciamento de informações, registrando as posições de origem como metadados de gráfico de conhecimento para rastreabilidade de ponta a ponta.

Problema

Atualmente, o TrustGraph possui um decodificador específico para PDF. Suportar formatos adicionais (DOCX, XLSX, HTML, Markdown, texto simples, PPTX, etc.) requer ou a escrita de um novo decodificador para cada formato ou a adoção de uma biblioteca de extração universal. Cada formato tem uma estrutura diferente — alguns são baseados em páginas, outros não — e a cadeia de rastreabilidade deve registrar de onde em cada documento original cada trecho de texto extraído se originou.

Abordagem

Biblioteca: unstructured

Utilize unstructured.partition.auto.partition(), que detecta automaticamente o formato a partir do tipo MIME ou da extensão do arquivo e extrai elementos estruturados (Título, TextoNarrativo, Tabela, ItemDeLista, etc.). Cada elemento carrega metadados, incluindo:

page_number (para formatos baseados em páginas, como PDF, PPTX) element_id (único para cada elemento) coordinates (caixa delimitadora para PDFs) text (o conteúdo de texto extraído) category (tipo de elemento: Título, TextoNarrativo, Tabela, etc.)

Tipos de Elementos

unstructured extrai elementos tipados de documentos. Cada elemento tem uma categoria e metadados associados:

Elementos de texto: Title — títulos de seções NarrativeText — parágrafos do corpo do texto ListItem — itens de listas (com marcadores/numerados) Header, Footer — cabeçalhos/rodapés de página FigureCaption — legendas para figuras/imagens Formula — expressões matemáticas Address, EmailAddress — informações de contato CodeSnippet — blocos de código (do Markdown)

Tabelas: Table — dados tabulares estruturados. unstructured fornece ambos element.text (texto simples) e element.metadata.text_as_html (HTML completo <table> com linhas, colunas e cabeçalhos preservados). Para formatos com estrutura de tabela explícita (DOCX, XLSX, HTML), a extração é altamente confiável. Para PDFs, a detecção de tabelas depende da estratégia hi_res com análise de layout.

Imagens: Image — imagens incorporadas detectadas por meio de análise de layout (requer hi_res estratégia). Com extract_image_block_to_payload=True, retorna os dados da imagem como base64 em element.metadata.image_base64. O texto OCR da imagem está disponível em element.text.

Tratamento de Tabelas

Tabelas são um tipo de saída de primeira classe. Quando o decodificador encontra um elemento Table, ele preserva a estrutura HTML em vez de converter para texto simples. Isso fornece ao extrator LLM downstream uma entrada muito melhor para extrair conhecimento estruturado de dados tabulares.

O texto da página/seção é montado da seguinte forma: Elementos de texto: texto simples, unidos por quebras de linha Elementos de tabela: marcação de tabela HTML de text_as_html, envolvida em um marcador <table> para que o LLM possa distinguir tabelas de texto narrativo

Por exemplo, uma página com um título, um parágrafo e uma tabela produz:

Financial Overview

Revenue grew 15% year-over-year driven by enterprise adoption.

<table>
<tr><th>Quarter</th><th>Revenue</th><th>Growth</th></tr>
<tr><td>Q1</td><td>$12M</td><td>12%</td></tr>
<tr><td>Q2</td><td>$14M</td><td>17%</td></tr>
</table>

Isso preserva a estrutura da tabela por meio da divisão em partes e no processo de extração pipeline, onde o LLM pode extrair relacionamentos diretamente de células estruturadas, em vez de adivinhar o alinhamento das colunas a partir de espaços em branco.

Tratamento de Imagens

As imagens são extraídas e armazenadas no sistema como documentos filhos com document_type="image" e um ID urn:image:{uuid}. Elas recebem triplas de procedência com o tipo tg:Image, vinculadas à página/seção pai por meio de prov:wasDerivedFrom. Os metadados da imagem (coordenadas, dimensões, element_id) são registrados na procedência.

É crucial que as imagens NÃO sejam emitidas como saídas do tipo TextDocument. Elas são armazenadas apenas — não enviadas para o chunker ou qualquer processo de texto pipeline. Isso é intencional:

1. Ainda não existe um pipeline de processamento de imagens (a integração do modelo de visão é um trabalho futuro).
2. Alimentar dados de imagem em base64 ou fragmentos de OCR no processo de extração de texto produziria triplas de grafo de conhecimento (KG) inúteis.

As imagens também são excluídas do texto da página montado — quaisquer elementos Image são ignorados silenciosamente ao concatenar os textos dos elementos para uma página/seção. A cadeia de procedência registra que as imagens existem e onde elas apareceram no documento, para que possam ser recuperadas por um futuro pipeline de processamento de imagens sem reingestão do documento.

Trabalho futuro

Direcionar entidades tg:Image para um modelo de visão para descrição, interpretação de diagramas ou extração de dados de gráficos. Armazenar descrições de imagens como documentos de texto filhos que são alimentados no processo de divisão/extração padrão. Vincular o conhecimento extraído de volta às imagens de origem por meio da procedência.

Estratégias de Seção

Para formatos baseados em páginas (PDF, PPTX, XLSX), os elementos são sempre agrupados por página/slide/planilha primeiro. Para formatos não baseados em páginas (DOCX, HTML, Markdown, etc.), o decodificador precisa de uma estratégia para dividir o documento em seções. Isso é configurável em tempo de execução por meio de --section-strategy.

Cada estratégia é uma função de agrupamento sobre a lista de unstructured elementos. A saída é uma lista de grupos de elementos; o restante do pipeline (montagem de texto, armazenamento do bibliotecário, rastreabilidade, emissão de TextDocument ) é idêntico, independentemente da estratégia.

whole-document (padrão)

Emita todo o documento como uma única seção. Deixe que o divisor de blocos (chunker) lide com toda a divisão.

Abordagem mais simples, bom ponto de partida Pode produzir um TextDocument muito grande para arquivos grandes, mas o divisor de blocos lida com isso Melhor quando você deseja o máximo de contexto por seção

heading

Divida nos elementos de cabeçalho (Title). Cada seção é um cabeçalho mais todo o conteúdo até o próximo cabeçalho de nível igual ou superior. Cabeçalhos aninhados criam seções aninhadas.

Produz unidades coerentes em termos de tópico Funciona bem para documentos estruturados (relatórios, manuais, especificações) Fornece ao LLM de extração o contexto do cabeçalho junto com o conteúdo Recua para whole-document se nenhum cabeçalho for encontrado

element-type

Divida quando o tipo de elemento muda significativamente — especificamente, comece uma nova seção nas transições entre texto narrativo e tabelas. Elementos consecutivos da mesma categoria ampla (texto, texto, texto ou tabela, tabela) permanecem agrupados.

Mantém as tabelas como seções independentes Bom para documentos com conteúdo misto (relatórios com tabelas de dados) As tabelas recebem atenção especial na extração

count

Agrupe um número fixo de elementos por seção. Configurável via --section-element-count (padrão: 20).

Simples e previsível Não respeita a estrutura do documento Útil como uma opção de fallback ou para experimentação

size

Acumula elementos até que um limite de caracteres seja atingido, então inicia uma nova seção. Respeita os limites dos elementos — nunca divide no meio de um elemento. Configurável via --section-max-size (padrão: 4000 caracteres).

Produz tamanhos de seção aproximadamente uniformes Respeita os limites dos elementos (ao contrário do "chunker" subsequente) Bom compromisso entre estrutura e controle de tamanho Se um único elemento exceder o limite, ele se torna sua própria seção

Interação com formatos baseados em página

Para formatos baseados em página, o agrupamento de páginas sempre tem prioridade. As estratégias de seção podem ser aplicadas opcionalmente dentro de uma página se ela for muito grande (por exemplo, uma página PDF com uma tabela enorme), controlado por --section-within-pages (padrão: falso). Quando falso, cada página é sempre uma seção, independentemente do tamanho.

Detecção de Formato

O decodificador precisa saber o tipo MIME do documento para passar para unstructured's partition(). Dois caminhos:

Caminho do "Librarian" (document_id definido): busca os metadados do documento do "librarian" primeiro — isso nos dá o kind (tipo MIME) que foi registrado no momento do upload. Em seguida, busca o conteúdo do documento. Duas chamadas ao "librarian", mas a busca de metadados é leve. Caminho "inline" (compatibilidade com versões anteriores, data definido): sem metadados disponíveis na mensagem. Use python-magic para detectar o formato a partir dos bytes do conteúdo como uma alternativa.

Não são necessárias alterações no esquema Document — o bibliotecário já armazena o tipo MIME.

Arquitetura

Um único serviço universal-decoder que:

1. Recebe uma mensagem Document (inline ou via referência ao bibliotecário).
2. Se o caminho for o do bibliotecário: busca os metadados do documento (obtém o tipo MIME), então busca o conteúdo. Se o caminho for inline: detecta o formato a partir dos bytes do conteúdo.
3. Chama partition() para extrair os elementos.
4. Agrupa elementos: por página para formatos baseados em página, por estratégia de seção configurada para formatos não baseados em página. seção.
5. Para cada página/seção: Gera um ID urn:page:{uuid} ou urn:section:{uuid} Monta o texto da página: narrativa como texto simples, tabelas como HTML, imagens ignoradas Calcula os deslocamentos de caracteres para cada elemento dentro do texto da página. Salva no "librarian" como documento filho. Emite triplas de procedência com metadados posicionais. Envia TextDocument para o processo de divisão em partes (chunking).
6. Para cada elemento de imagem: Gera um ID urn:image:{uuid}. Salva os dados da imagem no "librarian" como documento filho. Emite triplas de procedência (armazenadas apenas, não enviadas para o processo de divisão em partes).

Manipulação de Formato

Formato	Tipo MIME	Baseado em Página	Notas
PDF	application/pdf	Sim	Agrupamento por página
DOCX	application/vnd.openxmlformats...	Não	Usa estratégia de seção
PPTX	application/vnd.openxmlformats...	Sim	Agrupamento por slide
XLSX/XLS	application/vnd.openxmlformats...	Sim	Agrupamento por planilha
HTML	text/html	Não	Usa estratégia de seção
Markdown	text/markdown	Não	Usa estratégia de seção
Texto Simples	text/plain	Não	Usa estratégia de seção
CSV	text/csv	Não	Usa estratégia de seção
RST	text/x-rst	Não	Usa estratégia de seção
RTF	application/rtf	Não	Usa estratégia de seção
ODT	application/vnd.oasis...	Não	Usa estratégia de seção
TSV	text/tab-separated-values	Não	Usa estratégia de seção

Metadados de Proveniência

Cada entidade de página/seção registra metadados de posição como triplas de proveniência em GRAPH_SOURCE, permitindo rastreabilidade completa desde as triplas do grafo até as posições no documento de origem.

Campos existentes (já em derived_entity_triples)

page_number — número da página/planilha/slide (indexado a partir de 1, apenas para documentos baseados em página) char_offset — deslocamento de caractere desta página/seção dentro do texto completo do documento char_length — comprimento do caractere do texto desta página/seção

Novos campos (extender derived_entity_triples)

mime_type — formato original do documento (por exemplo, application/pdf) element_types — lista separada por vírgula de categorias de unstructured encontradas nesta página/seção (por exemplo, "Título,TextoNarrativo,Tabela") table_count — número de tabelas nesta página/seção image_count — número de imagens nesta página/seção

Estes requerem novos predicados do namespace TG:

TG_SECTION_TYPE  = "https://trustgraph.ai/ns/Section"
TG_IMAGE_TYPE    = "https://trustgraph.ai/ns/Image"
TG_ELEMENT_TYPES = "https://trustgraph.ai/ns/elementTypes"
TG_TABLE_COUNT   = "https://trustgraph.ai/ns/tableCount"
TG_IMAGE_COUNT   = "https://trustgraph.ai/ns/imageCount"

Esquema URN de imagem: urn:image:{uuid}

(TG_MIME_TYPE já existe.)

Novo tipo de entidade

Para formatos não paginados (DOCX, HTML, Markdown, etc.) onde o decodificador emite todo o documento como uma única unidade em vez de dividi-lo por página, a entidade recebe um novo tipo:

TG_SECTION_TYPE = "https://trustgraph.ai/ns/Section"

Isso distingue seções de páginas ao consultar a procedência:

Entidade	Tipo	Quando usado
Documento	tg:Document	Arquivo original carregado
Página	tg:Page	Formatos baseados em páginas (PDF, PPTX, XLSX)
Seção	tg:Section	Formatos não baseados em páginas (DOCX, HTML, MD, etc.)
Imagem	tg:Image	Imagens incorporadas (armazenadas, não processadas)
Trecho	tg:Chunk	Saída do processador de trechos
Subgrafo	tg:Subgraph	Saída da extração de grafo de conhecimento

O tipo é definido pelo decodificador com base em se está agrupando por página ou emitindo uma seção de documento inteiro. derived_entity_triples recebe um parâmetro booleano opcional section — quando verdadeiro, a entidade é classificada como tg:Section em vez de tg:Page.

Cadeia completa de procedência

KG triple
  → subgraph (extraction provenance)
    → chunk (char_offset, char_length within page)
      → page/section (page_number, char_offset, char_length within doc, mime_type, element_types)
        → document (original file in librarian)

Cada link é um conjunto de triplas no grafo nomeado GRAPH_SOURCE.

Configuração do Serviço

Argumentos de linha de comando:

--strategy              Partitioning strategy: auto, hi_res, fast (default: auto)
--languages             Comma-separated OCR language codes (default: eng)
--section-strategy      Section grouping: whole-document, heading, element-type,
                        count, size (default: whole-document)
--section-element-count Elements per section for 'count' strategy (default: 20)
--section-max-size      Max chars per section for 'size' strategy (default: 4000)
--section-within-pages  Apply section strategy within pages too (default: false)

Além dos argumentos padrão FlowProcessor e da fila de bibliotecários.

Integração de Fluxo

O decodificador universal ocupa a mesma posição no fluxo de processamento que o decodificador PDF atual:

Document → [universal-decoder] → TextDocument → [chunker] → Chunk → ...

Ele registra: input consumidor (schema de documento) output produtor (schema TextDocument) triples produtor (schema de triplas) Requisição/resposta do bibliotecário (para busca e armazenamento de documentos filhos)

Implantação

Novo contêiner: trustgraph-flow-universal-decoder Dependência: unstructured[all-docs] (inclui PDF, DOCX, PPTX, etc.) Pode ser executado em conjunto ou substituir o decodificador PDF existente, dependendo da configuração do fluxo O decodificador PDF existente permanece disponível para ambientes onde as dependências unstructured são muito pesadas

O que Muda

Componento	Alteração
provenance/namespaces.py	Adicionar TG_SECTION_TYPE, TG_IMAGE_TYPE, TG_ELEMENT_TYPES, TG_TABLE_COUNT, TG_IMAGE_COUNT
provenance/triples.py	Adicionar argumentos mime_type, element_types, table_count, image_count (kwargs)
provenance/__init__.py	Exportar novas constantes
Novo: decoding/universal/	Novo módulo de serviço de decodificação
setup.cfg / pyproject	Adicionar dependência unstructured[all-docs]
Docker	Nova imagem de contêiner
Definições de fluxo	Conectar universal-decoder como entrada de documento

O que não muda

Chunker (recebe TextDocument, funciona como antes) Extratores subsequentes (recebem Chunk, inalterados) Librarian (armazena documentos filhos, inalterado) Schema (Document, TextDocument, Chunk inalterados) Proveniência em tempo de consulta (inalterado)

Riscos

unstructured[all-docs] tem muitas dependências (poppler, tesseract, libreoffice para alguns formatos). A imagem do contêiner será maior. Mitigação: oferecer uma variante de [light] sem dependências de OCR/office. Alguns formatos podem produzir extração de texto de baixa qualidade (PDFs digitalizados sem OCR, layouts complexos de XLSX). Mitigação: parâmetro strategy configurável e o decodificador OCR Mistral existente permanece disponível para OCR de PDF de alta qualidade. As atualizações de versão de unstructured podem alterar os metadados dos elementos. Mitigação: fixar a versão, testar a qualidade da extração por formato.