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

layout	title	parent
default	Decodificador Universal de Documentos	Spanish (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 impulsado por unstructured: ingrese cualquier formato de documento común a través de un servicio único con un registro completo de la procedencia y la integración de la biblioteca, registrando las posiciones de origen como metadatos del gráfico de conocimiento para la trazabilidad de extremo a extremo.

Problema

Actualmente, TrustGraph tiene un decodificador específico para PDF. Para admitir formatos adicionales (DOCX, XLSX, HTML, Markdown, texto plano, PPTX, etc.), es necesario escribir un nuevo decodificador por formato o adoptar una biblioteca de extracción universal. Cada formato tiene una estructura diferente; algunos son basados en páginas, otros no, y la cadena de procedencia debe registrar de dónde se originó cada parte del texto extraído en el documento original.

Enfoque

Biblioteca: unstructured

Utilice unstructured.partition.auto.partition(), que detecta automáticamente el formato a partir del tipo MIME o la extensión del archivo y extrae elementos estructurados (Título, TextoNarrativo, Tabla, ElementoLista, etc.). Cada elemento lleva metadatos que incluyen:

page_number (para formatos basados en páginas como PDF, PPTX) element_id (único para cada elemento) coordinates (cuadro delimitador para PDF) text (el contenido de texto extraído) category (tipo de elemento: Título, TextoNarrativo, Tabla, etc.)

Tipos de Elemento

unstructured extrae elementos tipados de los documentos. Cada elemento tiene una categoría y metadatos asociados:

Elementos de texto: Title — encabezados de sección NarrativeText — párrafos del cuerpo ListItem — elementos de lista con viñetas/numerados Header, Footer — encabezados/pies de página FigureCaption — leyendas para figuras/imágenes Formula — expresiones matemáticas Address, EmailAddress — información de contacto CodeSnippet — bloques de código (de Markdown)

Tablas: Table — datos tabulares estructurados. unstructured proporciona tanto element.text (texto plano) como element.metadata.text_as_html (HTML completo <table> con filas, columnas y encabezados conservados). Para formatos con una estructura de tabla explícita (DOCX, XLSX, HTML), la extracción es muy fiable. Para PDF, la detección de tablas depende de la estrategia de hi_res con el análisis de diseño.

Imágenes: Image — imágenes integradas detectadas mediante el análisis de diseño (requiere la estrategia de hi_res). Con extract_image_block_to_payload=True, devuelve los datos de la imagen como base64 en element.metadata.image_base64. El texto OCR de la imagen está disponible en element.text.

Manejo de Tablas

Las tablas son una salida de primera clase. Cuando el decodificador encuentra un elemento Table, conserva la estructura HTML en lugar de aplanarla a texto plano. Esto proporciona a la biblioteca de extracción LLM descendente una mejor entrada para extraer conocimiento estructurado de los datos tabulares.

El texto de la página/sección se ensambla de la siguiente manera: Elementos de texto: texto plano, unido con saltos de línea Elementos de tabla: marcado de tabla HTML de text_as_html, envuelto en un marcador <table> para que el LLM pueda distinguir las tablas del texto narrativo.

Por ejemplo, una página con un encabezado, un párrafo y una tabla produce:

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>

Esto preserva la estructura de la tabla mediante la segmentación y en la canalización de extracción, donde el LLM puede extraer relaciones directamente de celdas estructuradas en lugar de adivinar la alineación de columnas a partir de espacios en blanco.

Manejo de imágenes

Las imágenes se extraen y se almacenan en la biblioteca como documentos secundarios con un document_type="image" y un ID urn:image:{uuid}. Obtienen tripletas de procedencia con el tipo tg:Image, vinculadas a su página/sección principal a través de prov:wasDerivedFrom. Los metadatos de la imagen (coordenadas, dimensiones, element_id) se registran en la procedencia.

Es crucial que las imágenes NO se emitan como salidas de TextDocument. Se almacenan únicamente; no se envían a la canalización de segmentación ni a ningún proceso de texto. Esto es intencional:

1. Todavía no existe una canalización de procesamiento de imágenes (la integración del modelo de visión es un trabajo futuro).
2. Alimentar datos de imagen en base64 o fragmentos de OCR en la canalización de extracción de texto produciría tripletas de KG basura.

Las imágenes también se excluyen del texto de la página ensamblada; cualquier Image elemento se omite silenciosamente al concatenar los textos de los elementos para una página/sección. La cadena de procedencia registra que las imágenes existen y dónde aparecieron en el documento, por lo que pueden ser recuperadas por una futura canalización de procesamiento de imágenes sin volver a importar el documento.

Trabajo futuro

Enviar tg:Image entidades a un modelo de visión para descripción, interpretación de diagramas o extracción de datos de gráficos. Almacenar las descripciones de las imágenes como documentos de texto secundarios que se integran en la canalización estándar de fragmentación/extracción. Vincular el conocimiento extraído de nuevo a las imágenes de origen a través de la procedencia.

Estrategias de sección

Para formatos basados en páginas (PDF, PPTX, XLSX), los elementos siempre se agrupan por página/diapositiva/hoja primero. Para formatos no basados en páginas (DOCX, HTML, Markdown, etc.), el decodificador necesita una estrategia para dividir el documento en secciones. Esto se puede configurar en tiempo de ejecución a través de --section-strategy.

Cada estrategia es una función de agrupación sobre la lista de unstructured elementos. La salida es una lista de grupos de elementos; el resto de la canalización (ensamblaje de texto, almacenamiento en la biblioteca, procedencia, emisión de TextDocument) es idéntico independientemente de la estrategia.

whole-document (predeterminado)

Emite todo el documento como una sola sección. Permite que el fragmentador (chunker) posterior gestione todas las divisiones.

Enfoque más simple, buena línea de base Puede producir un TextDocument muy grande para archivos grandes, pero el fragmentador se encarga de eso. Mejor cuando se desea el máximo contexto por sección.

heading

Divide en elementos de encabezado (Title). Cada sección es un encabezado más todo el contenido hasta el siguiente encabezado de igual o mayor nivel. Los encabezados anidados crean secciones anidadas.

Produce unidades temáticamente coherentes. Funciona bien para documentos estructurados (informes, manuales, especificaciones). Proporciona al LLM de extracción el contexto del encabezado junto con el contenido. Retrocede a whole-document si no se encuentran encabezados.

element-type

Divide cuando el tipo de elemento cambia significativamente; específicamente, comienza una nueva sección en las transiciones entre texto narrativo y tablas. Los elementos consecutivos de la misma categoría general (texto, texto, texto o tabla, tabla) permanecen agrupados.

Mantiene las tablas como secciones independientes. Bueno para documentos con contenido mixto (informes con tablas de datos). Las tablas reciben una atención de extracción dedicada.

count

Agrupa un número fijo de elementos por sección. Configurable a través de --section-element-count (predeterminado: 20).

Simple y predecible. No respeta la estructura del documento. Útil como alternativa o para la experimentación.

size

Acumula elementos hasta que se alcanza un límite de caracteres, luego comienza una nueva sección. Respeta los límites de los elementos; nunca los divide a la mitad. Configurable a través de --section-max-size (por defecto: 4000 caracteres).

Produce tamaños de sección aproximadamente uniformes. Respeta los límites de los elementos (a diferencia del fragmentador posterior). Buen compromiso entre estructura y control de tamaño. Si un solo elemento excede el límite, se convierte en su propia sección.

Interacción con formatos basados en páginas

Para formatos basados en páginas, el agrupamiento de páginas siempre tiene prioridad. Las estrategias de sección opcionalmente se pueden aplicar dentro de una página si es muy grande (por ejemplo, una página PDF con una tabla enorme), controlado por --section-within-pages (por defecto: falso). Cuando es falso, cada página es siempre una sección, independientemente del tamaño.

Detección de formato

El decodificador necesita conocer el tipo MIME del documento para pasarlo a unstructured's partition(). Dos caminos:

Ruta del bibliotecario (document_id configurado): primero, recupera los metadatos del documento del bibliotecario; esto nos da el kind (tipo MIME) que se registró en el momento de la carga. Luego, recupera el contenido del documento. Dos llamadas al bibliotecario, pero la recuperación de metadatos es ligera. Ruta integrada (compatibilidad con versiones anteriores, data configurado): no hay metadatos disponibles en el mensaje. Usa python-magic para detectar el formato a partir de los bytes del contenido como una opción alternativa.

No se necesitan cambios en el esquema Document; el bibliotecario ya almacena el tipo MIME.

Arquitectura

Un único servicio universal-decoder que:

1. Recibe un mensaje Document (en línea o a través de una referencia a la biblioteca).
2. Si la ruta es a través de la biblioteca: recupera los metadatos del documento (obtiene el tipo MIME), luego recupera el contenido. Si la ruta es en línea: detecta el formato a partir de los bytes del contenido.
3. Llama a partition() para extraer los elementos.
4. Agrupa elementos: por página para formatos basados en páginas, por estrategia de sección configurada para formatos no basados en páginas. sección.
5. Para cada página/sección: Genera un ID urn:page:{uuid} o urn:section:{uuid} Ensambla el texto de la página: el texto narrativo como texto plano, las tablas como HTML, imágenes omitidas Calcula los desplazamientos de caracteres para cada elemento dentro del texto de la página. Guarda en el sistema de gestión de documentos como documento hijo. Emite triples de procedencia con metadatos de posición. Envía TextDocument a la siguiente etapa para la segmentación.
6. Para cada elemento de imagen: Genera un ID urn:image:{uuid}. Guarda los datos de la imagen en el sistema de gestión de documentos como documento hijo. Emite triples de procedencia (almacenados solo, no enviados a la siguiente etapa).

Manejo de formatos

Formato	Tipo MIME	Basado en páginas	Notas
PDF	application/pdf	Sí	Agrupación por página
DOCX	application/vnd.openxmlformats...	No	Utiliza estrategia de secciones
PPTX	application/vnd.openxmlformats...	Sí	Agrupación por diapositiva
XLSX/XLS	application/vnd.openxmlformats...	Sí	Agrupación por hoja
HTML	text/html	No	Utiliza estrategia de secciones
Markdown	text/markdown	No	Utiliza estrategia de secciones
Texto plano	text/plain	No	Utiliza estrategia de secciones
CSV	text/csv	No	Utiliza estrategia de secciones
RST	text/x-rst	No	Utiliza estrategia de secciones
RTF	application/rtf	No	Utiliza estrategia de secciones
ODT	application/vnd.oasis...	No	Utiliza estrategia de secciones
TSV	text/tab-separated-values	No	Utiliza estrategia de secciones

Metadatos de procedencia

Cada entidad de página/sección registra metadatos de posición como metadatos de procedencia en GRAPH_SOURCE, lo que permite una trazabilidad completa desde las triples del grafo de conocimiento hasta las posiciones del documento de origen.

Campos existentes (ya están en derived_entity_triples)

page_number — número de página/hoja/diapositiva (indexado desde 1, solo para páginas) char_offset — desplazamiento de caracteres de esta página/sección dentro del texto completo del documento. char_length — longitud de caracteres del texto de esta página/sección.

Nuevos campos (extender derived_entity_triples)

mime_type — formato original del documento (por ejemplo, application/pdf) element_types — lista separada por comas de categorías de elementos unstructured encontradas en esta página/sección (por ejemplo, "Título,TextoNarrativo,Tabla") table_count — número de tablas en esta página/sección. image_count — número de imágenes en esta página/sección.

Estos requieren nuevos predicados del espacio de nombres 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 imagen: urn:image:{uuid}

(TG_MIME_TYPE ya existe.)

Nuevo tipo de entidad

Para formatos que no son de página (DOCX, HTML, Markdown, etc.) donde el decodificador emite todo el documento como una sola unidad en lugar de dividirlo por página, la entidad obtiene un nuevo tipo:

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

Esto distingue las secciones de las páginas al consultar el origen:

Entidad	Tipo	Cuándo se utiliza
Documento	tg:Document	Archivo original subido
Página	tg:Page	Formatos basados en páginas (PDF, PPTX, XLSX)
Sección	tg:Section	Formatos que no son de página (DOCX, HTML, MD, etc.)
Imagen	tg:Image	Imágenes incrustadas (almacenadas, no procesadas)
Fragmento	tg:Chunk	Resultado del fragmentador
Subgrafo	tg:Subgraph	Resultado de la extracción del grafo de conocimiento

El tipo se establece por el decodificador según si se está agrupando por página o emitiendo una sección de todo el documento. derived_entity_triples obtiene un parámetro booleano opcional section; cuando es verdadero, la entidad se clasifica como tg:Section en lugar de tg:Page.

Cadena completa de origen

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 enlace es un conjunto de triples en el grafo denominado GRAPH_SOURCE.

Configuración del servicio

Argumentos de línea de comandos:

--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)

Además de los argumentos estándar de FlowProcessor y la cola del bibliotecario.

Integración del flujo

El decodificador universal ocupa la misma posición en el flujo de procesamiento que el decodificador PDF actual:

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

Se registra: input consumidor (esquema de documento) output productor (esquema de TextDocument) triples productor (esquema de Triples) Solicitud/respuesta del bibliotecario (para la recuperación y el almacenamiento de documentos secundarios)

Despliegue

Nuevo contenedor: trustgraph-flow-universal-decoder Dependencia: unstructured[all-docs] (incluye PDF, DOCX, PPTX, etc.) Puede ejecutarse junto con o reemplazar el decodificador PDF existente, dependiendo de la configuración del flujo. El decodificador PDF existente permanece disponible para entornos donde las dependencias de unstructured son demasiado pesadas.

¿Qué Cambia?

Component	Change
provenance/namespaces.py	Add TG_SECTION_TYPE, TG_IMAGE_TYPE, TG_ELEMENT_TYPES, TG_TABLE_COUNT, TG_IMAGE_COUNT
provenance/triples.py	Add mime_type, element_types, table_count, image_count kwargs
provenance/__init__.py	Export new constants
New: decoding/universal/	New decoder service module
setup.cfg / pyproject	Add unstructured[all-docs] dependency
Docker	New container image
Flow definitions	Wire universal-decoder as document input

What Doesn't Change

Chunker (receives TextDocument, works as before) Downstream extractors (receive Chunk, unchanged) Librarian (stores child documents, unchanged) Schema (Document, TextDocument, Chunk unchanged) Query-time provenance (unchanged)

Risks

unstructured[all-docs] has heavy dependencies (poppler, tesseract, libreoffice for some formats). Container image will be larger. Mitigation: offer a [light] variant without OCR/office deps. Some formats may produce poor text extraction (scanned PDFs without OCR, complex XLSX layouts). Mitigation: configurable strategy parameter, and the existing Mistral OCR decoder remains available for high-quality PDF OCR. unstructured version updates may change element metadata. Mitigation: pin version, test extraction quality per format.