Módulo 8: Proyecto Integrador RAG con ChromaDB

Descripción del módulo

Este módulo consolida todo lo aprendido en la guía en un proyecto final: un sistema RAG completo, testeable y desplegable. El objetivo no es solo que funcione, sino que tenga calidad de ingeniería y esté listo para tu portfolio.

¿Qué hace diferente este módulo?

En los módulos 1-7 aprendiste conceptos y técnicas por separado. Aquí integras todo en un flujo end-to-end:

Módulos 1-2: Por qué vector databases y cómo funcionan internamente → eliges ChromaDB con fundamento.
Módulo 3: Metadata filtering, hybrid search, multi-tenancy → los usas para filtrar por fuente.
Módulos 4-5: ChromaDB hands-on, batch operations → implementas ingestion a escala.
Módulo 6: Decision matrix para elegir DB → justificas ChromaDB en este contexto.
Módulo 7: Production considerations → aplicas observabilidad, scaling y hardening.

No es nuevo aprendizaje teórico. Es integración práctica: conectar las piezas, tomar decisiones de diseño, escribir código production-ready y documentarlo para evolución futura.

Mapa de conceptos por módulo

Para que veas concretamente qué aplicas de cada módulo:

Módulo	Concepto clave	Dónde lo usarás en el proyecto
1	Por qué vector DB vs SQL/NoSQL	README, justificación de arquitectura
1	RAG necesita búsqueda semántica rápida	Diseño del retrieval pipeline
2	HNSW, índices aproximados	ChromaDB usa HNSW por defecto; entiendes por qué es rápido
2	Trade-off recall vs latency	Elección de top_k y score_threshold
3	Metadata filtering	Filtros por doc_id, source en queries
3	Batch operations	Ingestion en lotes de 1K-2K
4	ChromaDB CRUD, PersistentClient	Todo el vector store
4	Similarity search con metadata	Endpoint `/search` y `/ask`
5	Comparación Pinecone/Weaviate	Decisión de usar ChromaDB ahora, migrar después
6	Decision matrix (costo, escala, self-hosted)	Justificación en documentación
7	Observabilidad, scaling, migrations	Logs, health check, Docker

Este mapeo te ayuda a no "olvidar" lo aprendido y a reforzar la conexión teoría-práctica.

Objetivo del módulo

Construir una solución RAG end-to-end con:

Ingestion para 1,000+ documentos: pipeline robusto con lotes, metadata consistente y validación.
Retrieval con filtros de metadata: top-k, where clauses y manejo de scores bajos.
Generación con citas: respuestas fundamentadas en evidencia, fuentes verificables.
API REST para consumo externo: FastAPI con Swagger/ReDoc, contratos estables.
Pruebas y observabilidad básicas: tests automatizados, métricas y trazabilidad.

El resultado será un sistema que puedas mostrar en un portfolio, desplegar con Docker y usar como base directa para la Guía #8 (Advanced RAG Techniques).

Conexión con Guía #8 (Advanced RAG)

Este proyecto está diseñado para ser reutilizable. Cuando avances a la Guía #8:

El mismo flujo de ingestion se adaptará a Pinecone o Weaviate con cambios mínimos.
La arquitectura modular (ingestion ↔ retrieval ↔ generation) facilita swapping de componentes.
El contrato de API (/ask, sources, trace_id) se mantendrá; lo que cambia es el vector store.

Pensar en evolución desde el diseño te evita reescribir código más adelante.

Ejemplo concreto de reusabilidad

En la Guía #8 trabajarás con Pinecone. El cambio sería aproximadamente:

# Actual (ChromaDB)
from chromadb import PersistentClient
client = PersistentClient(path="./chroma")
collection = client.get_collection("rag_docs")
results = collection.query(query_embeddings=[embedding], n_results=5)

# Guía #8 (Pinecone)
from pinecone import Pinecone
pc = Pinecone()
index = pc.Index("rag-index")
results = index.query(vector=embedding, top_k=5, include_metadata=True)

La lógica de retrieval (embed query, hacer búsqueda, filtrar por score) es la misma. Solo cambia el cliente. Si abstraes el vector store detrás de una interfaz, migrar es cambiar una implementación.

Estructura de cápsulas

Cápsula	Contenido	Enfoque
01	Introducción al proyecto	Qué integras, criterios de éxito, enfoque de trabajo
02	Arquitectura y diseño	Componentes, flujo de datos, decisiones de diseño
03	Pipeline de ingestion	1,000+ docs, chunking, embeddings, ChromaDB
04	Retrieval + Generation + API	Endpoints, `/ask`, citas, FastAPI
05	Testing y evaluación	Unitarias, integración, calidad, performance
06	Observabilidad y deployment	Logs, métricas, Docker
07	Hardening final	Seguridad, rate limiting, error handling
08	Entrega del proyecto	Checklist production-ready, documentación

Criterios de éxito del módulo

Al completar el proyecto, deberías poder afirmar:

Pipeline de ingestion estable para 1,000+ documentos (tiempo razonable, sin errores masivos).
Endpoint /ask que devuelve respuestas fundamentadas, fuentes y fallback explícito cuando no hay contexto suficiente.
Set mínimo de pruebas automatizadas (unitarias + integración) que pasen de forma reproducible.
Deployment reproducible con Docker (imagen que levanta API + ChromaDB con volumen persistente).
Evidencia de observabilidad básica: logs estructurados, métricas de latencia y trace_id en respuestas.

Enfoque de trabajo recomendado

1. Diseña arquitectura primero

Antes de escribir código, define:

Componentes y responsabilidades.
Contratos entre componentes (qué pasa entre ingestion → retrieval → generation).
Configuración externalizada (variables de entorno, no valores hardcodeados).

2. Construye vertical slice funcional

Implementa un flujo mínimo que funcione de punta a punta:

Ingestion de 10-20 documentos.
Retrieval manual.
Un endpoint /ask que devuelva respuesta.

Valida que el flujo tenga sentido antes de escalar.

3. Endurece con tests, métricas y hardening

Una vez funcional, agrega:

Tests automatizados.
Manejo de errores y límites.
Logs y métricas para diagnóstico.

4. Documenta decisiones para facilitar evolución

En un README o DESIGN.md, registra:

Por qué elegiste ChromaDB (vs otros).
Por qué chunk_size=512, batch_size=1000, etc.
Dependencias y versiones.

Mentalidad: no buscar perfección en v1

Un error frecuente es intentar que la primera versión tenga todo: tests exhaustivos, rate limiting, métricas avanzadas, documentación perfecta. Eso diluye el foco.

Enfoque recomendado:

v1: Pipeline funcional end-to-end. Ingestion de 1K docs, /ask que responde, Docker que levanta. Código limpio pero no sobrediseñado.
v1.1: Tests mínimos que demuestren que el core funciona. Health check, un test de integración de /ask.
v1.2: Observabilidad básica: logs con trace_id, métricas de latencia si tienes tiempo.
v2 (opcional): Rate limiting, alertas, migración a Pinecone para Guía #8.

Prioriza funcionalidad verificable sobre complejidad futura.

Ruta sugerida (timeline aproximado)

Día / Sesión	Cápsulas	Entregable
1	01, 02	Diseño en papel, decisiones documentadas
2	03	Pipeline de ingestion funcionando con 100+ docs
3	04	API con `/ask` y `/search` funcionando
4	03 (escalar)	Ingestion de 1,000+ docs verificada
5	05, 06	Tests, Docker, observabilidad básica
6	07, 08	Hardening, checklist, entrega

Ajusta según tu ritmo. Lo crítico es tener el vertical slice (02→03→04) funcionando antes de endurecer.

Qué necesitas para empezar

Prerequisitos técnicos:

Python 3.10+
ChromaDB instalado (módulo 4)
Cuenta OpenAI (para embeddings y generación)
FastAPI y dependencias de la guía (módulos 4-5)

Conocimientos previos:

Haber completado módulos 1-7 de esta guía (o equivalente).
Familiaridad con REST APIs y estructura de un proyecto Python.

Ejercicios previos al proyecto

Los siguientes ejercicios te preparan antes de codear:

Ejercicio 1: Mapeo de módulos a componentes

Lista qué concepto de cada módulo (1-7) usarás en el proyecto. Ejemplo:

Módulo 1 (por qué vector DB) → justificación en README.
Módulo 4 (ChromaDB CRUD) → operaciones add/query.
etc.

Solución: Crea una tabla o lista con módulo ↔ componente del proyecto. Esto te obliga a recordar y conectar el aprendizaje previo.

Ejercicio 2: Definir contrato de `/ask`

Antes de implementar, escribe el JSON de respuesta que quieres para /ask. Incluye: answer, sources, confidence, trace_id. ¿Qué harás si no hay documentos recuperados?

Solución: Define un esquema como:

{
  "answer": "string",
  "sources": [
    {"doc_id": "id", "title": "string", "score": 0.82}
  ],
  "confidence": 0.0,
  "trace_id": "uuid",
  "fallback_reason": null
}

Si no hay evidencia: answer = mensaje explícito "No tengo información suficiente", sources = [], confidence = 0, fallback_reason = "insufficient retrieval".

Ejercicio 3: Estimación de tiempo de ingestion

Si procesas 1,000 documentos con:

Chunking: ~100 ms por doc (aprox).
Embeddings: batch de 100, ~1 s por batch (OpenAI).
ChromaDB add: batch 1000, ~0.2 s por batch.

Estima tiempo total aproximado. ¿Dónde está el cuello de botella?

Solución: Orden de magnitud:

Chunking: 100 docs × 100 ms = 10 s (paralelizable).
Embeddings: 10 batches × 1 s = 10 s (limitado por API).
ChromaDB: 1 batch × 0.2 s = 0.2 s.

El cuello de botella típico es embedding generation (llamadas a API). Por eso se usan batches y, en producción, consideras caching o modelos locales.

Ejercicio 4: Checklist de producción (previa)

Antes de implementar, revisa el checklist de producción del módulo 7. Marca qué ítems aplicarás en este proyecto mínimo y cuáles dejarás para una segunda iteración.

Solución: Ejemplo de priorización:

Ahora: Logs básicos, health check, variables de entorno, Docker.
Después: Rate limiting avanzado, métricas con Prometheus, alertas.

Ejercicio 5: Reusabilidad para Guía #8

Enumera 3 cambios que tendrías que hacer si mañana migras de ChromaDB a Pinecone. ¿Dónde está acoplado el vector store en tu diseño?

Solución: Cambios típicos:

Sustituir cliente ChromaDB por cliente Pinecone.
Adaptar formato de IDs y metadata (Pinecone tiene restricciones propias).
Cambiar configuración de colecciones por índices.

Si separaste un módulo vector_store o similar con interfaz abstracta, el cambio se concentra ahí. Si ChromaDB está disperso en el código, la migración será costosa.

Ejercicio 6: Priorización de criterios de éxito

Los criterios de éxito son: (1) ingestion 1K+ docs, (2) /ask con fuentes y fallback, (3) tests mínimos, (4) Docker, (5) observabilidad. ¿En qué orden los implementarías y por qué?

Solución: Orden sugerido:

/ask con fuentes y fallback — Es el corazón del producto. Sin esto, no hay RAG.
Ingestion 1K+ docs — Necesitas datos para probar retrieval real. Puedes empezar con 100 y escalar.
Docker — Facilita reproducibilidad y deployment. Relativamente rápido de añadir.
Tests mínimos — Validan que no rompes nada al cambiar. Un test de integración de /ask es suficiente para v1.
Observabilidad — Logs y trace_id tienen alto impacto con bajo esfuerzo; métricas pueden esperar.

Troubleshooting previo al desarrollo

"No tengo claro por dónde empezar"

Prioriza: 1) arquitectura en papel/diagrama, 2) flujo mínimo (10 docs, 1 endpoint), 3) escalar y endurecer. No intentes hacer todo perfecto en la primera iteración.

"Tengo miedo de que el proyecto sea demasiado grande"

El scope mínimo es: ingestion de 1,000 docs, /ask funcional, Docker que levante todo. Tests y observabilidad pueden ser básicos. Reduce features antes de reducir calidad del core.

"No sé si mi diseño es correcto"

Revisa la cápsula 02 (Arquitectura). Los criterios clave: componentes separados, contratos explícitos, configuración externalizada. Si cumples eso, el diseño es razonable. Perfección no es el objetivo; coherencia sí.

"Quiero usar otra DB en lugar de ChromaDB"

Para este módulo, usa ChromaDB: es el foco de la guía, sin coste de API y fácil de instalar. Cuando pases a Guía #8, migrarás a Pinecone u otra. El ejercicio de diseño te prepara para ese cambio.

"¿Debo implementar todo desde cero?"

Puedes reutilizar código de los módulos 4-5 (ChromaDB, batch ingestion). Adapta y extiende; no empieces de cero en lo que ya viste. El valor está en la integración y las decisiones de producción.

Errores comunes al iniciar

Error	Por qué ocurre	Cómo evitarlo
Empezar a codear sin diseño	Ansiedad por "ver algo funcionando"	Dedica 30-60 min a la cápsula 02 antes de tocar código
Sobrediseñar la abstracción	Miedo a acoplamiento, experiencia con proyectos grandes	Para 1K docs y un solo vector store, una interfaz simple basta; no hagas 5 capas de abstracción
Ignorar el fallback	Asumir que retrieval siempre encontrará algo	Implementa desde el día 1: "No tengo información" cuando retrieval está vacío
Hardcodear API keys	Rapidez inicial	Usa `python-dotenv` y `.env` desde el primer commit; añade `.env` a `.gitignore`
No documentar decisiones	"Ya lo recuerdo"	Escribe 2-3 párrafos en README o DESIGN.md; en 2 semanas lo habrás olvidado

Resumen

Este módulo consolida lo aprendido en los módulos 1-7 en un sistema RAG completo.
El proyecto es integración, no nuevo contenido teórico: conectas ingestion, retrieval, generation y API.
El resultado es portfolio-worthy: desplegable, documentado y testeable.
El diseño es reutilizable: base directa para la Guía #8 (Advanced RAG) con Pinecone u otra DB.
Enfócate en arquitectura primero, luego flujo mínimo, después endurecimiento.
Criterios de éxito: ingestion 1K+ docs, /ask con fuentes y fallback, tests, Docker, observabilidad básica.
Documenta decisiones de diseño para facilitar evolución y migración futura.

Recursos adicionales

FastAPI Documentation
ChromaDB Documentation
Docker Documentation
RAG Paper (Lewis et al.) — "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks"
LangChain Text Splitters — RecursiveCharacterTextSplitter y alternativas
OpenAI Embeddings API
Vector Databases Fundamentals README — Contexto completo de la guía
Production RAG Considerations — Checklist y patrones

Checklist de lectura

Antes de pasar a la cápsula 02, verifica que puedas responder:

¿Qué integras de cada módulo (1-7) en este proyecto?
¿Por qué el diseño es reutilizable para la Guía #8?
¿Cuáles son los 5 criterios de éxito?
¿En qué orden implementarías: diseño, vertical slice, tests, Docker?
¿Qué hacer cuando retrieval devuelve 0 documentos?

Si puedes responder las 5 preguntas, estás listo para diseñar la arquitectura.

Qué no es este módulo

Para evitar expectativas incorrectas:

No es un tutorial de LangChain completo: Usamos LangChain solo para text splitters; el resto es código propio.
No es deployment a producción a gran escala: Docker y observabilidad básica sí; K8s, load balancers y HA quedan fuera.
No es fine-tuning de modelos: Usamos embeddings y LLM pre-entrenados.
No es evaluación exhaustiva de RAG: Habrá tests y métricas básicas; no un framework completo de evaluación.

El alcance es deliberado: un sistema funcional, limpio y extensible, no un producto enterprise completo.

Próximos pasos

Tras leer esta cápsula, pasa a 02-arquitectura-proyecto.md para definir el diseño. No saltes directo al código: los 20-30 minutos que inviertas en arquitectura te ahorrarán horas de refactoring. Si ya tienes experiencia con RAG o FastAPI, puedes revisar la cápsula 02 de forma más rápida, pero asegúrate de tener claros los 5 componentes y los contratos entre ellos antes de implementar.

Tiempo estimado: 15-20 minutos
Siguiente: 02-arquitectura-proyecto.md

← AnteriorCápsula 08: Proyecto - Production Readiness Checklist Siguiente →Cápsula 02: Arquitectura del Proyecto