Recuperación semántica con ChromaDB y embeddings para una plataforma multiagente
Pasando una plataforma empresarial multiagente a una recuperación semántica real: segmentación consciente de palabras, distancia de coseno en ChromaDB, capas de prueba y el siguiente paso de RetrievalAgent.
Fuentes: Building Real Semantic Retrieval for an Enterprise Multi-Agent AI Platform
Se ha alcanzado un nuevo hito en el proyecto Enterprise Multi-Agent AI Platform: su pipeline de recuperación ahora realiza búsquedas semánticas reales, utilizando embeddings almacenados en ChromaDB. La arquitectura ha evolucionado desde la preparación de documentos hasta un proceso de recuperación funcional, que ejecuta primero SourceDocument, luego DocumentChunker, seguido de EmbeddingService, después OpenAI Embeddings, luego ChromaDB, la búsqueda semántica, y finalmente RetrievedDocument.
Se trata de un cambio significativo en la etapa de desarrollo. La plataforma ya no se limita a preparar documentos y generar embeddings; puede almacenar conocimiento empresarial vectorizado, buscarlo por su significado, clasificar los fragmentos relevantes y entregar resultados estructurados. Su desarrollo también reveló algunos problemas relacionados con la calidad de la recuperación que fueron necesarios solucionar antes de poder integrar el pipeline en el RetrievalAgent.
El pipeline toma forma
La arquitectura de recuperación está organizada de la siguiente manera:
Enterprise Documents
│
▼
SourceDocument
│
▼
DocumentChunker
│
▼
DocumentChunk[]
│
▼
EmbeddingService
│
▼
OpenAI Embeddings
│
▼
ChromaDB
│
▼
Semantic Search
│
▼
RetrievedDocument[]
│
▼
RetrievalAgent
Cada capa tiene una responsabilidad única, y eso es intencional. El objetivo nunca fue contar con una sola función RAG grande que cargue archivos, divida texto, genere embeddings, gestione la base de datos vectorial, ejecute búsquedas y produzca una respuesta. En su lugar, el sistema está compuesto por límites arquitectónicos claros.
Etapa 1: documentos de origen
Todo comienza con el conocimiento empresarial. Con el tiempo, ese contenido puede provenir de archivos PDF, DOCX y TXT, informes financieros, políticas internas, documentación técnica, material de investigación y bases de conocimiento empresariales. El modelo SourceDocument le da a ese material una forma estándar antes de que ingrese al proceso. Conceptualmente, se ve así:
SourceDocument
├── document_id
├── content
├── source
└── metadata
El principio importante aquí es la trazabilidad. Todo lo que se recupere más tarde debe seguir teniendo un vínculo con el origen del cual proviene.
Etapa 2: fragmentación
Los documentos grandes, por lo general, no deberían incluirse como un único bloque. DocumentChunker convierte cada SourceDocument en partes más pequeñas listas para su recuperación:
SourceDocument
│
▼
DocumentChunker
│
├── Chunk 0
├── Chunk 1
├── Chunk 2
└── Chunk N
Cada fragmento mantiene su chunk_id, document_id, content, source, chunk_index y metadatos. Por lo tanto, la búsqueda semántica puede funcionar con unidades pequeñas de información sin perder el vínculo con el documento original.
Mejorando la calidad de los fragmentos
Al ejecutar el verdadero proceso de recuperación se detectó un problema. La división en fragmentos basada en caracteres puede interrumpir el texto prosaico en puntos inoportunos, a veces incluso a través de una palabra entera. Un límite podría generar conceptualmente un fragmento que termine de esta manera:
...important financial risks for
seguido por un fragmento que comienza de esta manera:
the upcoming quarter...
O, en casos peores, una división en medio de una palabra. Esos fragmentos son técnicamente válidos, pero la calidad de recuperación depende de algo más que de estructuras de datos válidas. Los límites determinan la calidad semántica de todo lo que se incrusta.
Por lo tanto, la estrategia de fragmentación se modificó para dar prioridad a los límites entre palabras en el texto prosaico normal, manteniendo como alternativa los límites por carácter para textos sin espacios en blanco útiles. El fragmentador ahora tiene dos modos de funcionamiento:
Normal prose
↓
Prefer word-aware boundaries
Text without whitespace
↓
Fallback to character boundaries
Se trata de un pequeño detalle de implementación que contiene una gran lección arquitectónica: superar las pruebas no implica necesariamente que la calidad de la recuperación sea buena, y los datos reales revelan problemas que las pruebas unitarias aisladas no siempre pueden mostrar.
Etapa 3: embeddings
Una vez que los fragmentos están listos, el EmbeddingService convierte su texto en vectores numéricos.
DocumentChunk
│
▼
EmbeddingService
│
▼
Embedding Model
│
▼
Vector Representation
El servicio admite embeddings de texto único para consultas y embeddings por lotes para fragmentos de documentos. Una prueba de integración local anterior confirmó una dimensión vectorial de 1,536. El número en sí es menos importante que el hecho de que la implementación de los embeddings permanezca detrás de los límites del servicio, por lo que el Agente de Recuperación nunca necesita saber cómo se generan los vectores.
Etapa 4: Almacenamiento vectorial de ChromaDB
La siguiente capa es el almacenamiento persistente de vectores. Cada fragmento ahora puede guardarse junto con su vector y metadatos. Conceptualmente:
DocumentChunk
+
Embedding
+
Metadata
│
▼
ChromaDB
│
▼
Persistent Vector Collection
Un registro vectorial puede contener información como:
Vector Record
├── chunk_id
├── embedding
├── content
├── document_id
├── source
├── chunk_index
└── metadata
Un vector sin información adicional no sirve de nada para el resto de la aplicación. La plataforma necesita recuperar el contenido real y saber de dónde proviene ese contenido.
Etapa 5: búsqueda semántica
Con los fragmentos incrustados en ChromaDB, el sistema puede realizar búsquedas semánticas. La ruta de la consulta es la siguiente:
User Query
│
▼
EmbeddingService
│
▼
Query Embedding
│
▼
ChromaDB
│
▼
Similarity Search
│
▼
Top-K Relevant Chunks
│
▼
RetrievedDocument[]
La recuperación de información ha pasado de buscar documentos que contengan exactamente estas palabras a encontrar fragmentos cuyo significado se ajuste mejor a la consulta. Esa es una de las capacidades fundamentales detrás de RAG.
Una corrección en la métrica de similitud
Las pruebas reales revelaron un segundo problema. Las bases de datos vectoriales admiten diferentes métricas de distancia o similitud, y si la colección utiliza una métrica mientras la aplicación interpreta la distancia devuelta como otra, la puntuación de relevancia resulta engañosa. Para este flujo de trabajo, la colección ChromaDB se configuró explícitamente para usar distancia coseno, de modo que la capa de recuperación puede interpretar consistentemente los resultados como similitud basada en el coseno.
Query Embedding
│
▼
ChromaDB
│
▼
Cosine Distance
│
▼
Similarity Score
│
▼
Ranked Results
La recuperación semántica no se trata solo de devolver documentos, sino también de comprender cuán relevantes son.
Resultados reales de recuperación
Después de realizar la división en fragmentos y los ajustes de similitud, el proceso se probó con una consulta real sobre riesgos financieros. Los resultados ordenados presentaron puntuaciones de similitud de aproximadamente 0,6181, 0,5520 y 0,4198, y el contexto recuperado incluyó la información relevante sobre riesgo de liquidez y volatilidad del mercado. Por lo tanto, el proceso completó con éxito todo este flujo:
Question
↓
Query Embedding
↓
ChromaDB
↓
Semantic Similarity
↓
Relevant Chunks
↓
Financial Risk Context
En ese momento, la infraestructura de recuperación dejó de ser un trabajo de configuración y comenzó a demostrar una verdadera recuperación de conocimiento semántico.
Por qué es importante la prueba real de recuperación
Las pruebas unitarias simuladas siguen siendo extremadamente valiosas. Ofrecen velocidad, determinismo, seguridad en los procesos de integración continua, costo cero en API externas, escenarios de fallo controlados e isolamiento de la lógica de la aplicación. Sin embargo, no pueden responder a todas las preguntas. Una prueba simulada puede confirmar que algo funciona desde el punto de vista estructural:
EmbeddingService
↓
Expected Vector
Pero no puede demostrar por completo que la cadena siguiente genere un buen comportamiento de recuperación:
Real Document
↓
Real Chunking
↓
Real Embedding
↓
Real Vector Database
↓
Real Semantic Query
↓
Useful Context
Por lo tanto, la estrategia de pruebas mantiene separados varios niveles de validación.
Estrategia de pruebas
La plataforma está avanzando hacia tres capas complementarias de pruebas.
Las pruebas unitarias son rápidas y deterministas, y forman parte del flujo normal de CI:
Application Logic
↓
Mock External Dependencies
↓
Controlled Results
↓
Assertions
Las pruebas de integración validan la infraestructura real y pueden ejecutarse por separado del rápido conjunto de CI:
Application
↓
Real Embedding Provider
↓
Real ChromaDB
↓
End-to-End Retrieval
Las pruebas de rendimiento y resiliencia se vuelven necesarias a medida que la plataforma madura:
Realistic Workload
↓
Concurrent Requests
↓
Latency
Throughput
Rate Limits
Failures
Cost
Scalability
Un sistema de IA listo para producción necesita los tres elementos. Simular servicios externos en pruebas unitarias no reemplaza a las pruebas de integración, y estas a su vez no sustituyen a las pruebas de rendimiento. Cada capa responde a una pregunta técnica diferente.
CI permanece en estado positivo
Tras las mejoras en la recuperación de datos, el conjunto de pruebas rápido sigue funcionando bien: 17 pruebas han superado la verificación y 2 pruebas de integración fueron descartadas. Esto es importante porque el pipeline RAG se vuelve cada vez más sofisticado sin sacrificar la validación determinista del CI. El ciclo de desarrollo continúa de la siguiente manera:
Code Change
↓
Fast Unit Tests
↓
Commit
↓
Push
↓
GitHub Actions
↓
CI Validation
↓
Keep Green
Las pruebas contra servicios reales permanecen disponibles como ejecución separada.
Conectar RAG a la plataforma multiagente
La infraestructura de recuperación no existe de forma aislada. Está diseñada para convertirse en la capa de conocimiento del sistema multiagente más amplio, y la arquitectura general se dirige hacia allí:
User
│
▼
Supervisor Agent
│
▼
Planning Agent
│
▼
Execution Plan
│
▼
Agent Registry
│
┌────────────┼────────────┐
▼ ▼ ▼
RetrievalAgent ResearchAgent AnalysisAgent
│
▼
RetrievalService
│
▼
EmbeddingService
│
▼
ChromaDB
│
▼
Semantic Search
│
▼
Relevant Context
│
▼
Downstream Agents
Este es el punto en el que RAG y la orquestación multiagente comienzan a fusionarse.
Mantener simple al agente de recuperación
Un objetivo clave es mantener al RetrievalAgent enfocado en su propia tarea. No debería necesitar conocer sobre algoritmos de particionamiento, la implementación de embeddings, las dimensiones vectoriales, los detalles internos de ChromaDB, los cálculos de similitud ni la configuración de almacenamiento. En su lugar:
RetrievalAgent
↓
RetrievalService
↓
VectorStoreService
↓
EmbeddingService + ChromaDB
El agente solicita conocimientos relevantes, y la infraestructura de recuperación decide cómo se encuentran esos conocimientos. Esta separación permite que la implementación subyacente evolucione sin necesidad de reescribir el agente.
Siguiente hito: reemplazar la recuperación temporal
El siguiente paso es claro. El Agente de Recuperación aún debe conectarse directamente a la infraestructura real de recuperación. Hoy en día se presenta de esta manera:
BEFORE
RetrievalAgent
↓
Temporary Local Documents
y el objetivo es este:
NEXT
RetrievalAgent
↓
RetrievalService
↓
VectorStoreService
↓
EmbeddingService
↓
ChromaDB
↓
Semantic Search
↓
Enterprise Knowledge
Después de esa integración, el agente deja de devolver resultados temporales codificados manualmente y obtiene conocimiento de la colección real de documentos indexados.
De la infraestructura a la ejecución multiagente
Esa integración marca otra transición. La mayor parte del trabajo realizado hasta ahora se ha dedicado a construir la infraestructura de recuperación. Una vez que RetrievalAgent consume el verdadero pipeline semántico, la arquitectura puede soportar flujos de trabajo como este:
User Request
↓
Supervisor
↓
Planning Agent
↓
Execution Plan
↓
Retrieval Agent
↓
Enterprise Knowledge
↓
Analysis Agent
↓
Report Agent
↓
Quality Review
↓
Final Response
RAG pasa a ser una capacidad dentro de un sistema de ejecución multiagente más amplio y ya no es una función de recuperación independiente.
El camino por delante
La hoja de ruta de recuperación avanza desde componentes fundamentales hacia capacidades orientadas a la producción:
Document Contracts ✅
↓
Chunking ✅
↓
Embeddings ✅
↓
ChromaDB Vector Storage ✅
↓
Semantic Search ✅
↓
RetrievalAgent Integration ← NEXT
↓
Reranking
↓
Caching & Cost Controls
↓
Observability & Metrics
↓
Multi-Tenant Isolation
↓
Production Hardening
Las etapas posteriores adquieren mayor importancia a medida que la plataforma pasa de una arquitectura funcional a operaciones empresariales.
La RAG en producción necesita más que solo la recuperación de información
Obtener fragmentos relevantes de ChromaDB es un hito, pero no representa el final de la arquitectura. Una plataforma de recuperación en producción debe poder manejar eventualmente:
- La reclasificación, ya que la similitud vectorial inicial no siempre proporciona el orden óptimo.
- El caché, dado que los embeddings y búsquedas repetidas aumentan la latencia y el costo.
- La observabilidad, para poder medir la latencia de recuperación, la latencia de los embeddings, el número de documentos, las puntuaciones, los fallos y el costo.
- La evolución de los modelos y del espacio vectorial, ya que cambiar de modelo de embeddings puede requerir índices versionados y un proceso controlado de re-embedding.
- El manejo de límites de tasa, ya que los proveedores externos de IA imponen restricciones operativas que no son deterministas.
Estos puntos deben formar parte del plan de desarrollo, pero deberían añadirse dentro de límites estables y no mezclarse en una única implementación grande desde el primer día.
El principio de ingeniería
La lección más importante de esta etapa es diseñar primero la abstracción, verificar el comportamiento con datos reales y luego reforzar las características de producción a medida que la arquitectura crece. La progresión ha sido intencionada:
Data Contract
↓
Chunking
↓
Unit Testing
↓
Embeddings
↓
Mocked Provider Testing
↓
Real Integration Validation
↓
Vector Storage
↓
Semantic Retrieval
↓
Retrieval Quality Improvements
↓
Agent Integration
Cada etapa expone una clase diferente de problema, y esa es precisamente la razón por la que la arquitectura incremental resulta beneficiosa.
De los documentos a la ejecución multiagente
La visión general está tomando forma:
Enterprise Knowledge
↓
Document Processing
↓
Chunking
↓
Embeddings
↓
Vector Storage
↓
Semantic Retrieval
↓
Retrieval Agent
↓
Multi-Agent Orchestration
↓
Analysis + Research + Reporting
↓
Quality Review
↓
Grounded Enterprise Response
RAG no es toda la plataforma. Es la infraestructura de conocimiento que permite a los agentes especializados trabajar dentro de un contexto empresarial concreto.
Marcador actual
Lo que existe hoy en día: modelos de documentos uniformes, fragmentación tanto sin considerar los límites entre palabras como sí, un servicio de embeddings con pruebas unitarias simuladas además de una ejecución real de validación, almacenamiento persistente en ChromaDB con similitud coseno definida explícitamente, búsqueda semántica que devuelve resultados ordenados, y un conjunto rápido de 17 pruebas aprobadas. El siguiente hito es conectar RetrievalAgent al verdadero pipeline de recuperación semántica, momento en el que el sistema deja de ser simplemente un subsistema RAG para comenzar a ejecutar operaciones multiagente impulsadas por RAG.
La IA empresarial no significa simplemente conectar un LLM a una base de datos vectorial y declarar victoria. Las capas necesitan contratos, los contratos requieren pruebas, las integraciones demandan una validación real, y el sistema necesita espacio para evolucionar. El proceso ha pasado de documentos, fragmentos, embeddings y vectores a documentos, fragmentos, embeddings, ChromaDB, búsqueda semántica y contexto empresarial relevante. Lo que viene a continuación es que ese contexto fluya hacia RetrievalAgent y luego hacia la ejecución multiagente. El ciclo de trabajo se mantiene constante: construir, probar, medir, mejorar, integrar y escalar.