Capa por capa: Diseñando un verdadero pipeline de recuperación RAG para agentes de IA
Planifique una tubería RAG con los contratos SourceDocument y DocumentChunk, fragmentación, embeddings y ChromaDB, todo detrás de un RetrievalService que mantiene estable al agente.
Fuentes: Building a Real RAG Retrieval Pipeline for an Enterprise Multi-Agent AI Platform
Sustituir un agente de recuperación de juguetes por una verdadera pipeline RAG es un buen momento para reducir el ritmo y trabajar en capas. En una plataforma empresarial multiagente, RetrievalAgent inicialmente funcionaba con una implementación local deliberadamente simple. Eso fue suficiente para probar la arquitectura, pero el uso en producción requiere documentos reales, embeddings, almacenamiento vectorial y búsqueda semántica. El flujo deseado va desde los documentos, pasando por su ingesta, fragmentación y generación de embeddings hasta ChromaDB, y luego a la recuperación semántica, RetrievalAgent y toda la plataforma.
En lugar de construirlo todo de una sola vez, el plan consiste en añadir una capa a la vez, con pruebas en cada etapa y manteniendo el pipeline CI en estado positivo. Los objetivos son incrementos constantes, un CI funcional y una arquitectura sólida.
Las componentes de una pipeline RAG
Un pipeline completo agrupa varios aspectos de ingeniería independientes, los cuales el diagrama a continuación muestra desde los documentos originales en adelante.
Source Documents
↓
Document Ingestion
↓
Chunking
↓
Embeddings
↓
Vector Storage
↓
Semantic Search
↓
Retrieved Context
↓
Retrieval Agent
Es posible desarrollar cada componente simultáneamente, pero eso dificulta identificar las fallas. Cuando la calidad de la recuperación es deficiente, ¿dónde está el problema? Puede deberse al análisis de documentos, a la división en fragmentos, a los embeddings, al almacenamiento vectorial, a la lógica de consultas, a los metadatos o a la integración con agentes. Asignar a cada capa una responsabilidad clara, un contrato y unos límites de prueba permite responder a esas preguntas. El ritmo de trabajo consiste en desarrollar, probar, subir los cambios, validarlos en CI, mantener todo funcional y luego continuar.
Comience con el contrato de datos
Antes de utilizar embeddings o ChromaDB, la primera tarea es definir el contrato de datos. El pipeline debe distinguir entre dos conceptos: SourceDocument y DocumentChunk.
SourceDocument se refiere a la fuente de conocimiento original antes de que sea dividida. Puede tratarse de un archivo PDF, DOCX o TXT, documentación interna, informes financieros, políticas empresariales, manuales técnicos o contenido de una base de conocimientos. Su estructura conceptual es la siguiente:
SourceDocument
├── document_id
├── content
├── source
└── metadata
Cada documento original recibe, por lo tanto, una identidad estable dentro de la arquitectura de recuperación.
Los documentos empresariales de gran tamaño normalmente no deberían incluirse como un único bloque enorme de texto. Es necesario dividirlos en unidades más pequeñas y significativas, y esa es la función de DocumentChunk:
DocumentChunk
├── chunk_id
├── document_id
├── content
├── source
├── chunk_index
└── metadata
La relación entre los dos es uno-a-muchos:
SourceDocument
│
┌────────────┼────────────┐
▼ ▼ ▼
Chunk 0 Chunk 1 Chunk 2
│ │ │
└────────────┼────────────┘
↓
Same document_id
+ source metadata
Una sola fuente puede generar docenas de fragmentos, o incluso cientos, pero cada uno mantiene un enlace a su document_id y fuente originales. Ese enlace se vuelve crucial una vez que la recuperación semántica comienza a devolver fragmentos individuales de documentos mucho más grandes.
Por qué la trazabilidad está integrada desde el primer día
Imagínese un informe financiero de 50 páginas. El sistema puede dividirlo en docenas de fragmentos, y una búsqueda semántica podría devolver solo tres. El sistema aún debe poder indicar de qué documento original proviene la información. Reconstruir esa relación después de la recuperación es frágil, por lo que debe conservarse en cada paso del proceso.
Original Document
↓
SourceDocument
↓
DocumentChunk
↓
Embedding
↓
Vector Record
↓
Semantic Search
↓
RetrievedDocument
↓
Original Source
La trazabilidad forma parte de la arquitectura de datos desde el principio y no es algo añadido posteriormente.
Pruebas de los contratos
Con los modelos definidos, las pruebas automatizadas cubren tanto SourceDocument como DocumentChunk. Verifican que los modelos se construyan correctamente y que los campos clave funcionen como se espera, incluidos los IDs de los documentos, los detalles de origen, el contenido y los índices de los fragmentos.
Puede parecer un hito menor, pero estos modelos serán la base de todo el proceso de recuperación:
Document Models
↓
Chunking
↓
Embeddings
↓
ChromaDB
↓
Retrieval
↓
Agents
Un contrato defectuoso en la parte inicial de esa cadena puede afectar todo lo que viene después, por lo que la base de datos se protege antes de que se añada más infraestructura encima.
Otra decisión deliberada fue mantener esta etapa libre de dependencias externas. Aquí no se realizan llamadas a OpenAI ni a ChromaDB, y las pruebas solo validan los contratos del documento. Por lo tanto, el rápido conjunto de herramientas CI sigue siendo determinista.
Code Change
↓
Local Fast Tests
↓
Commit
↓
Push to GitHub
↓
GitHub Actions
↓
Clean CI Environment
↓
Fast Unit Tests
↓
CI PASSED ✅
La suite rápida sigue creciendo mientras que las pruebas de integración externa permanecen en su propio grupo separado. La regla que rige esto es que cada nueva capa se incorpora a la plataforma con protección automatizada.
El roadmap completo
El contrato para documentos es solo la primera capa. Aquí está toda la arquitectura objetivo:
Enterprise Documents
│
▼
Ingestion
│
▼
Chunking
│
▼
Embeddings
│
▼
ChromaDB
Vector Storage
│
▼
Semantic Retrieval
│
▼
Retrieved Context
│
▼
RetrievalAgent
│
▼
Multi-Agent Platform
Cada etapa tiene una responsabilidad específica y debe seguir siendo comprensible y verificable por sí sola.
A continuación viene el chunking
El siguiente componente es el Chunking Service, que convierte un SourceDocument en varios objetos DocumentChunk.
SourceDocument
│
▼
ChunkingService
│
├── DocumentChunk 0
├── DocumentChunk 1
├── DocumentChunk 2
└── DocumentChunk N
Con el tiempo, el servicio debe gestionar el tamaño y la superposición de los fragmentos, transmitir metadatos y detalles de la fuente, asignar un índice a cada fragmento y generar identificadores estables. Una decisión arquitectónica destacada es que la división en fragmentos no forma parte del Agente de Recuperación; este agente se encarga únicamente de las capacidades de recuperación y no debería asumir también la preparación de los documentos.
Embebidos y almacenamiento
Una vez implementada y probada la división en fragmentos, la capa siguiente genera embebidos vectoriales.
DocumentChunk
↓
Embedding Service
↓
Embedding Model
↓
Vector Representation
Cada fragmento se convierte en un vector que codifica su significado. Posteriormente, esos vectores se comparan con una consulta del usuario incorporada para encontrar material relacionado.
DocumentChunk
↓
EmbeddingService
↓
Embedding Provider
↓
Vector
Cambiar el modelo de incrustación más adelante debería afectar muy poco al resto del diseño de RAG.
Después de las incrustaciones viene el almacenamiento de vectores persistente. Para el desarrollo local, el cliente persistente de ChromaDB puede mantener los conocimientos indexados a través de los reinicios de la aplicación.
DocumentChunk
+
Embedding
+
Metadata
↓
ChromaDB
↓
Persistent Vector Collection
Un registro almacenado necesita algo más que un vector. También debe contener suficiente información para mantener el contexto y la trazabilidad:
Vector Record
├── chunk_id
├── embedding
├── content
├── document_id
├── source
├── chunk_index
└── metadata
Eso permite que la recuperación devuelva un contexto documental significativo y no solo vectores similares.
Búsqueda
Con el almacenamiento completo, el sistema puede realizar búsquedas semánticas. La ruta de la consulta es:
User Query
↓
Query Embedding
↓
ChromaDB Similarity Search
↓
Top-K Relevant Chunks
↓
Scores + Metadata
↓
Retrieved Context
En lugar de depender exclusivamente de coincidencias exactas con palabras clave, la recuperación semántica encuentra fragmentos conceptualmente relacionados con la solicitud del usuario. Luego, los resultados se convierten en el contrato de recuperación estandarizado que ya utiliza la plataforma.
Volver a conectar el agente
Solo cuando la infraestructura de recuperación funciona, todo el proceso se vuelve a conectar con RetrievalAgent. Desde el punto de vista del agente, la situación sigue siendo sencilla:
AgentRequest
↓
RetrievalAgent
↓
RetrievalService
↓
Relevant Documents
↓
Structured RetrievalResult
Detrás de RetrievalService, la implementación se vuelve mucho más sofisticada:
RetrievalService
↓
Query Embedding
↓
ChromaDB
↓
Semantic Search
↓
Ranking
↓
Retrieved Context
La separación es importante. El agente de recuperación debe considerar la recuperación como una capacidad y no necesita conocer nada sobre bases de datos vectoriales, generación de embeddings, almacenamiento por bloques ni ingestión de documentos.
El agente original funcionaba con datos locales, y la arquitectura se parecía más o menos a esto:
RetrievalAgent
↓
RetrievalService
↓
Local Documents
La implementación ahora puede evolucionar hacia algo más completo:
RetrievalAgent
↓
RetrievalService
↓
Semantic Retrieval
↓
ChromaDB
↓
Embedded Enterprise Documents
Fíjese en lo que permanece estable: el enlace desde RetrievalAgent hacia RetrievalService. Solo cambia la infraestructura detrás de ese contrato, y esa es precisamente la razón por la cual se creó la abstracción de recuperación antes de que aparecieran las bases de datos vectoriales. La infraestructura debe poder evolucionar libremente sin obligar a rediseñar la arquitectura del agente.
Integración en la plataforma
El pipeline RAG no existe por sí solo. Su propósito es suministrar conocimiento empresarial basado en datos al sistema multiagente más amplio.
User
│
▼
Supervisor Agent
│
▼
Planning Agent
│
▼
Execution Plan
│
▼
Agent Registry
│
┌────────────┼────────────┐
▼ ▼ ▼
RetrievalAgent ResearchAgent AnalysisAgent
│
▼
RetrievalService
│
▼
RAG Pipeline
│
▼
Relevant Context
│
▼
Downstream Agents
En esa imagen, el Agente de Recuperación conecta la capa donde ejecutan varios agentes con la capa que alberga el conocimiento empresarial.
Hay una lección que merece énfasis: RAG no es simplemente “añadir una base de datos vectorial”. Una arquitectura de recuperación sólida implica muchas decisiones:
- Contratos de documentos e ingestión
- Fragmentación y generación de embeddings
- Almacenamiento vectorial y metadatos
- Recuperación semántica y clasificación
- Rastreabilidad de fuentes
- Integración de agentes
- Pruebas y capacidad de observabilidad
La base de datos vectorial es un solo componente dentro de un sistema de recuperación mucho más amplio.
Un patrón repetitivo, a propósito
El ciclo de ingeniería para este hito es intencionalmente repetitivo:
Build One Layer
↓
Add Unit Tests
↓
Run Fast Suite
↓
Push to GitHub
↓
CI Validates
↓
Keep Green
↓
Build Next Layer
Permite que la complejidad aumente mientras se mantiene la confianza en el sistema existente. En lugar de agregar cinco componentes a la vez y depurarlos juntos, cada funcionalidad se valida antes de que llegue la siguiente.
Se ha completado el primer hito del verdadero pipeline: el contrato SourceDocument, el contrato DocumentChunk, pruebas para ambos modelos y una ejecución rápida de CI exitosa. El plan a seguir es:
1. Document Contract ✅ COMPLETE
↓
2. Chunking Service ← NEXT
↓
3. Embedding Service
↓
4. ChromaDB Integration
↓
5. Semantic Retrieval
↓
6. RetrievalAgent Integration
↓
7. End-to-End RAG Pipeline
Cada capa se implementa y se prueba de forma independiente antes de pasar al siguiente paso.
Por qué es importante
El primer agente de recuperación demostró que la arquitectura de agentes funcionaba. El objetivo ahora es reemplazar su recuperación temporal por una infraestructura real, pasando de la recuperación local a un pipeline de documentos, con fragmentación, embeddings, almacenamiento vectorial, búsqueda semántica y, finalmente, un agente habilitado para RAG. Dado que el agente depende de una abstracción de servicio y no directamente de ChromaDB, todo esto puede realizarse sin tener que rediseñar la plataforma multiagente.
Se aplica un principio más amplio: crear contratos estables alrededor de los componentes que se espera que cambien. Los modelos cambiarán, las bases de datos vectoriales podrían ser reemplazadas, las estrategias de fragmentación evolucionarán y los algoritmos de recuperación mejorarán, pero la plataforma que los rodea no debería necesitar ser reescrita cada vez.
Lo que se está desarrollando es una capacidad de recuperación que forma parte de una plataforma empresarial multiagente, no una demostración puntual de RAG. Allí, el Supervisor orquesta las operaciones, el Registro resuelve las capacidades disponibles, los agentes especializados ejecutan las tareas, RAG proporciona conocimiento basado en datos reales, las pruebas protegen el comportamiento del sistema, CI supervisa cada cambio y la capacidad de observabilidad mide el rendimiento en producción. El método nunca varía: se construye una capa, se prueba, se implementa, se mantiene CI en estado positivo, y luego se construye la siguiente capa.