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.es.md
Normal file
355
docs/tech-specs/extraction-flows.es.md
Normal file
|
|
@ -0,0 +1,355 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Flujos de extracción"
|
||||
parent: "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
|
||||
Loading…
Add table
Add a link
Reference in a new issue