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

layout	title	parent
default	Flujos de extracción	Spanish (Beta)

Flujos de extracción

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 describe cómo los datos fluyen a través de la canalización de extracción de TrustGraph, desde la presentación del documento hasta el almacenamiento en almacenes de conocimiento.

Resumen

┌──────────┐     ┌─────────────┐     ┌─────────┐     ┌────────────────────┐
│ Librarian│────▶│ PDF Decoder │────▶│ Chunker │────▶│ Knowledge          │
│          │     │ (PDF only)  │     │         │     │ Extraction         │
│          │────────────────────────▶│         │     │                    │
└──────────┘     └─────────────┘     └─────────┘     └────────────────────┘
                                          │                    │
                                          │                    ├──▶ Triples
                                          │                    ├──▶ Entity Contexts
                                          │                    └──▶ Rows
                                          │
                                          └──▶ Document Embeddings

Almacenamiento de contenido

Almacenamiento de objetos (S3/Minio)

El contenido de los documentos se almacena en un almacenamiento de objetos compatible con S3: Formato de la ruta: doc/{object_id} donde object_id es un UUID Todos los tipos de documentos se almacenan aquí: documentos fuente, páginas, fragmentos

Almacenamiento de metadatos (Cassandra)

Los metadatos de los documentos almacenados en Cassandra incluyen: ID del documento, título, tipo (MIME) Referencia al almacenamiento de objetos object_id Referencia parent_id para documentos secundarios (páginas, fragmentos) document_type: "fuente", "página", "fragmento", "respuesta"

Umbral de contenido en línea frente a transmisión

La transmisión de contenido utiliza una estrategia basada en el tamaño: < 2MB: El contenido se incluye directamente en el mensaje (codificado en base64) ≥ 2MB: Solo se envía document_id; el procesador recupera el contenido a través de la API del bibliotecario

Etapa 1: Envío de documentos (Bibliotecario)

Punto de entrada

Los documentos ingresan al sistema a través de la operación add-document del bibliotecario:

1. El contenido se carga en el almacenamiento de objetos
2. Se crea un registro de metadatos en Cassandra
3. Devuelve el ID del documento

Activación de la extracción

La operación add-processing activa la extracción: Especifica document_id, flow (ID de la canalización), collection (almacén de destino) La operación load_document() del bibliotecario recupera el contenido y lo publica en la cola de entrada del flujo

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)

Enrutamiento: Basado en el campo kind: application/pdf → cola document-load → Decodificador de PDF text/plain → cola text-load → Fragmentador

Etapa 2: Decodificador de PDF

Convierte documentos PDF en páginas de texto.

Proceso

1. Obtener contenido (inline data o a través de document_id desde el bibliotecario)
2. Extraer páginas utilizando PyPDF
3. Para cada página: Guardar como documento hijo en el bibliotecario ({doc_id}/p{page_num}) Emitir triples de procedencia (página derivada del documento) Enviar al 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: Fragmentador

Divide el texto en fragmentos de un tamaño configurado.

Parámetros (configurables)

chunk_size: Tamaño de fragmento objetivo en caracteres (predeterminado: 2000) chunk_overlap: Solapamiento entre fragmentos (predeterminado: 100)

Proceso

1. Obtener el contenido del texto (en línea o a través del bibliotecario)
2. Dividir utilizando un divisor de caracteres recursivo
3. Para cada fragmento: Guardar como documento hijo en el bibliotecario ({parent_id}/c{index}) Emitir triples de procedencia (fragmento derivado de página/documento) Enviar a los procesadores de extracción

Esquema: Fragmento

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

Jerarquía de Identificadores de Documentos

Los documentos secundarios codifican su linaje en el identificador: Fuente: doc123 Página: doc123/p5 Fragmento de página: doc123/p5/c2 Fragmento de texto: doc123/c2

Etapa 4: Extracción de Conocimiento

Múltiples patrones de extracción disponibles, seleccionados por la configuración del flujo.

Patrón A: Basic GraphRAG

Dos procesadores paralelos:

kg-extract-definitions Entrada: Fragmento Salida: Triples (definiciones de entidades), EntityContexts Extrae: etiquetas de entidades, definiciones

kg-extract-relationships Entrada: Fragmento Salida: Triples (relaciones), EntityContexts Extrae: relaciones sujeto-predicado-objeto

Patrón B: Basado en Ontología (kg-extract-ontology)

Entrada: Fragmento Salida: Triples, EntityContexts Utiliza una ontología configurada para guiar la extracción

Patrón C: Basado en Agente (kg-extract-agent)

Entrada: Fragmento Salida: Triples, EntityContexts Utiliza un marco de agente para la extracción

Patrón D: Extracción de Filas (kg-extract-rows)

Entrada: Fragmento Salida: Filas (datos estructurados, no triples) Utiliza una definición de esquema para extraer registros estructurados

Esquema: Triples

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: Filas

Rows
├── metadata: Metadata
├── row_schema: RowSchema
│   ├── name: str
│   ├── description: str
│   └── fields: list[Field]
└── rows: list[dict[str, str]]   # Extracted records

Etapa 5: Generación de Incrustaciones (Embeddings)

Incrustaciones de Grafos (Graph Embeddings)

Convierte los contextos de las entidades en incrustaciones vectoriales.

Proceso:

1. Recibir EntityContexts (Contextos de Entidades)
2. Llamar al servicio de incrustaciones con el texto del contexto
3. Salida: GraphEmbeddings (mapeo de entidad a vector)

Esquema: GraphEmbeddings

GraphEmbeddings
├── metadata: Metadata
└── entities: list[EntityEmbeddings]
    └── EntityEmbeddings
        ├── entity: Term         # Entity identifier
        ├── vector: list[float]  # Embedding vector
        └── chunk_id: str        # Source chunk (provenance)

Incrustaciones de documentos

Convierte texto de fragmentos directamente en incrustaciones vectoriales.

Proceso:

1. Recibir fragmento
2. Llamar al servicio de incrustaciones con el texto del fragmento
3. Salida: Incrustaciones de documentos

Esquema: Incrustaciones de documentos

DocumentEmbeddings
├── metadata: Metadata
└── chunks: list[ChunkEmbeddings]
    └── ChunkEmbeddings
        ├── chunk_id: str        # Chunk identifier
        └── vector: list[float]  # Embedding vector

Incrustaciones de filas

Convierte los campos de índice de fila en incrustaciones vectoriales.

Proceso:

1. Recibir filas
2. Incrustar campos de índice configurados
3. Salida a la tienda de vectores de filas

Etapa 6: Almacenamiento

Triple Store

Recibe: Triples Almacenamiento: Cassandra (tablas centradas en entidades) Los grafos con nombre separan el conocimiento central de la procedencia: "" (predeterminado): Hechos de conocimiento central urn:graph:source: Procedencia de extracción urn:graph:retrieval: Explicabilidad en tiempo de consulta

Tienda de vectores (Incrustaciones de grafos)

Recibe: GraphEmbeddings Almacenamiento: Qdrant, Milvus o Pinecone Indexado por: IRI de entidad Metadatos: chunk_id para la procedencia

Tienda de vectores (Incrustaciones de documentos)

Recibe: DocumentEmbeddings Almacenamiento: Qdrant, Milvus o Pinecone Indexado por: chunk_id

Tienda de filas

Recibe: Filas Almacenamiento: Cassandra Estructura de tabla basada en esquema

Tienda de vectores de filas

Recibe: Incrustaciones de filas Almacenamiento: Base de datos de vectores Indexado por: Campos de índice de fila

Análisis de campos de metadatos

Campos utilizados activamente

Campo	Uso
metadata.id	Identificador de documento/fragmento, registro, procedencia
metadata.user	Multitenencia, enrutamiento de almacenamiento
metadata.collection	Selección de colección de destino
document_id	Referencia de bibliotecario, enlace de procedencia
chunk_id	Seguimiento de la procedencia a través de la canalización

<<<<<<< HEAD

Campos potencialmente redundantes

Campo	Estado
metadata.metadata	Establecido en [] por todos los extractores; los metadatos a nivel de documento ahora se gestionan por el bibliotecario en el momento de la presentación

=======

Campos eliminados

Campo	Estado
metadata.metadata	Eliminado de la clase Metadata. Los triples de metadatos a nivel de documento ahora se emiten directamente por el bibliotecario a la triple store en el momento de la presentación, y no se transmiten a través de la canalización de extracción.

e3bcbf73 (The metadata field (list of triples) in the pipeline Metadata class)

Patrón de campos de bytes

Todos los campos de contenido (data, text, chunk) son bytes, pero se decodifican inmediatamente a cadenas UTF-8 por todos los procesadores. Ningún procesador utiliza bytes sin procesar.

Configuración del flujo

Los flujos se definen externamente y se proporcionan al bibliotecario a través del servicio de configuración. Cada flujo especifica:

Colas de entrada (text-load, document-load) Cadena de procesadores Parámetros (tamaño del fragmento, método de extracción, etc.)

Patrones de flujo de ejemplo: pdf-graphrag: PDF → Decodificador → Fragmentador → Definiciones + Relaciones → Incrustaciones text-graphrag: Texto → Fragmentador → Definiciones + Relaciones → Incrustaciones pdf-ontology: PDF → Decodificador → Fragmentador → Extracción de ontología → Incrustaciones text-rows: Texto → Fragmentador → Extracción de filas → Tienda de filas