Cápsula 08: Proyecto - RAG Production-Ready

Descripción de la cápsula

Llegaste al cierre de la guía: entregar un sistema RAG completo, evaluado y desplegable. Esta cápsula consolida todo lo construido en las cápsulas anteriores y te guía paso a paso para integrar cada pieza en un proyecto portfolio-quality.

Al completar esta cápsula tendrás:

• Sistema RAG con 1,000+ documentos indexados en ChromaDB
• API FastAPI con endpoints /ingest, /search, /ask, /health, /metrics
• Docker deployment con docker-compose (rag-api + chromadb-server)
• Suite de tests (unit, integration, performance, accuracy)
• Observabilidad (Prometheus, logging estructurado)
• README con arquitectura, API reference y guía de deployment

Y lo más importante: una base sólida para la Guía #8 (Advanced RAG Techniques), donde migrarás a Pinecone, agregarás re-ranking y evaluarás tu RAG de forma sistemática.

---

Entregables Obligatorios

#	Entregable	Verificación
1	Código del sistema (ingestion, retrieval, generation, API)	docker-compose up funciona
2	Configuración Docker (Dockerfile, docker-compose.yml)	Un comando levanta todo
3	Test set y resultados de evaluación	Accuracy report en metrics-report.md
4	Documento de decisiones técnicas	DECISIONS.md o sección en README
5	Checklist de production readiness	Tabla en README o archivo separado

---

Estructura Final del Proyecto

rag-project/
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI app, routers
│   ├── config.py               # Settings, env vars
│   ├── api/
│   │   ├── routes/
│   │   │   ├── ingest.py
│   │   │   ├── search.py
│   │   │   ├── ask.py
│   │   │   └── health.py
│   │   └── deps.py             # Dependencies (ChromaDB client, etc.)
│   ├── ingestion/
│   │   ├── chunking.py
│   │   ├── pipeline.py
│   │   └── loaders.py
│   ├── retrieval/
│   │   ├── retriever.py
│   │   └── filters.py
│   ├── generation/
│   │   └── generator.py
│   ├── cache/
│   │   ├── embedding_cache.py
│   │   └── result_cache.py
│   ├── metrics.py              # Prometheus
│   └── logging_config.py
├── tests/
│   ├── conftest.py
│   ├── unit/
│   ├── integration/
│   ├── performance/
│   └── evaluation/
│       └── golden_set.json
├── scripts/
│   ├── ingest_sample_docs.py    # Generar 1000+ docs de prueba
│   └── run_evaluation.py
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
├── requirements-dev.txt
├── .env.example
├── README.md
├── DEPLOYMENT.md
├── CHANGELOG.md
└── metrics-report.md

---

Guía Paso a Paso de Integración

Paso 1: Setup inicial (5 min)

mkdir -p rag-project/app/{api,ingestion,retrieval,generation,cache}
mkdir -p rag-project/tests/{unit,integration,performance,evaluation}
cd rag-project

Crea requirements.txt:

fastapi>=0.104.0
uvicorn[standard]>=0.24.0
chromadb>=0.4.0
openai>=1.0.0
httpx>=0.24.0
pydantic-settings>=2.0.0
prometheus-client>=0.19.0
tenacity>=8.2.0
python-dotenv>=1.0.0

Paso 2: Configuración (10 min)

# app/config.py
import os
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    chroma_host: str = os.getenv("CHROMA_HOST", "localhost")
    chroma_port: int = int(os.getenv("CHROMA_PORT", "8001"))
    chroma_collection: str = os.getenv("CHROMA_COLLECTION", "rag_docs")
    openai_api_key: str = os.getenv("OPENAI_API_KEY", "")
    chunk_size: int = 512
    chunk_overlap: int = 64
    top_k: int = 5

    class Config:
        env_file = ".env"

settings = Settings()

Paso 3: Ingestion pipeline (15 min)

Implementa app/ingestion/chunking.py, pipeline.py y loaders.py siguiendo la Cápsula 03. El pipeline debe:

• Cargar documentos (o generar 1000+ de prueba)
• Chunkear con chunk_size=512, overlap=64
• Generar embeddings con OpenAI
• Insertar en ChromaDB con IDs estables

Paso 4: Retrieval y Generation (15 min)

Implementa app/retrieval/retriever.py y app/generation/generator.py siguiendo la Cápsula 04. El contrato:

• retrieve(question, collection, top_k=5) → documentos + metadatas
• generate_answer(question, docs) → respuesta + fuentes

Paso 5: API FastAPI (15 min)

# app/main.py
from fastapi import FastAPI
from app.api.routes import ingest, search, ask, health
from app.metrics import setup_metrics

app = FastAPI(title="RAG API", version="1.0.0")
app.include_router(health.router, tags=["health"])
app.include_router(ingest.router, prefix="/ingest", tags=["ingest"])
app.include_router(search.router, prefix="/search", tags=["search"])
app.include_router(ask.router, prefix="/ask", tags=["ask"])
setup_metrics(app)

Paso 6: Docker y docker-compose (10 min)

Copia el Dockerfile y docker-compose.yml de la Cápsula 06. Ajusta rutas si tu estructura difiere.

Paso 7: Tests (20 min)

Copia la estructura de tests de la Cápsula 05. Asegúrate de tener:

• Unit: chunking, filters
• Integration: /health, /search, /ask
• Performance: p95 < 2s, throughput > 20 QPS
• Accuracy: golden set > 90%

Paso 8: Hardening (15 min)

Aplica lo de la Cápsula 07:

• Retries para ChromaDB y OpenAI
• Fallbacks en /ask
• Rate limiting
• README y DEPLOYMENT.md

Paso 9: Evaluación final (10 min)

Ejecuta:

docker-compose up -d
pytest tests/ -v --tb=short
python scripts/run_evaluation.py

Genera metrics-report.md con resultados.

---

Código de Integración Completo (Resumen)

app/main.py (esqueleto)

from fastapi import FastAPI
from app.config import settings
from app.api.routes import health, search, ask, ingest

app = FastAPI(title="RAG API", version="1.0.0", docs_url="/docs")
app.include_router(health.router)
app.include_router(search.router, prefix="/search")
app.include_router(ask.router, prefix="/ask")
app.include_router(ingest.router, prefix="/ingest")

app/api/routes/ask.py (ejemplo completo)

from fastapi import APIRouter, HTTPException, Depends
from pydantic import BaseModel, Field
from app.retrieval.retriever import retrieve
from app.generation.generator import generate_answer
from app.config import settings
from app.deps import get_collection

router = APIRouter()

class AskPayload(BaseModel):
    question: str = Field(..., min_length=1, max_length=500)

@router.post("")
async def ask_endpoint(payload: AskPayload, collection=Depends(get_collection)):
    docs = await retrieve(payload.question, collection, top_k=settings.top_k)
    if not docs or not docs.get("documents") or not docs["documents"][0]:
        return {"answer": "No encontré información suficiente.", "sources": [], "confidence": 0}
    answer = await generate_answer(payload.question, docs["documents"][0])
    return {
        "answer": answer,
        "sources": docs.get("metadatas", [[]])[0],
        "confidence": 0.85,
    }

---

Criterios de Aprobación Sugeridos

Criterio	Umbral
Accuracy en golden set	≥ 85% (objetivo 90%)
Latencia p95 /ask	< 2.5s (objetivo 2s)
Throughput /search	≥ 20 QPS
Endpoints principales	/health, /search, /ask operativos
Recuperación ante fallos	Fallbacks validados manualmente
Observabilidad	Logs estructurados, /metrics accesible

---

Rúbrica de Cierre Recomendada

Área	Criterio	Estado
Funcionalidad	Ingestion, search y ask operativos	⬜
Calidad	Accuracy y errores dentro de umbral	⬜
Operación	Observabilidad y runbooks mínimos	⬜
Resiliencia	Fallbacks y rollback documentado	⬜
Seguridad	Auth + rate limiting + validación	⬜
Documentación	README, API reference, deployment	⬜

---

Ejemplo de Resultado del Proyecto

## Resultado del Proyecto RAG

- **Accuracy:** 0.87 (umbral 0.85) ✅
- **p95 /ask:** 1.9s (umbral 2.5s) ✅
- **Throughput:** 24 QPS (objetivo 20) ✅
- **Error rate:** 0.6% (umbral 1%) ✅
- **Estado final:** Aprobado para piloto controlado

### Riesgos abiertos
- Dependencia de proveedor LLM para picos de tráfico
- Falta prueba de carga de 10x tráfico

### Próxima iteración
- Caching semántico de resultados
- Mejoras de observabilidad por tenant

---

Qué Aprendiste en Toda la Guía

Al completar los 8 módulos de la guía Vector Databases Fundamentals, ahora puedes:

1. Explicar por qué RAG necesita vector databases — SQL/NoSQL no escalan para búsqueda por similaridad; numpy no gestiona millones de vectores en memoria.

2. Entender la arquitectura interna — indexing layer (HNSW, IVF), query engine, storage. Sabes qué hace M, efConstruction, y cuándo importan.

3. Dominar ChromaDB — setup local, CRUD de vectores, metadata filtering, batch ingestion, persistencia. Construiste un sistema que indexa 1,000+ documentos.

4. Comparar el landscape — Pinecone, Weaviate, Qdrant, Milvus. Conoces managed vs self-hosted, pricing, y cuándo migrar.

5. Decidir qué DB usar — Aplicaste un framework de decisión (cost, scale, features) para elegir tecnología.

6. Preparar RAG para producción — scaling, backups, monitoring, migrations, optimización de costos.

7. Construir un sistema RAG completo — ingestion → ChromaDB → retrieval → generation → API REST, con Docker, tests, observabilidad y hardening.

Lo que falta (y viene en la Guía #8):

• Migración ChromaDB → Pinecone (managed cloud)
• Re-ranking con cross-encoders
• Query optimization (expansion, rewriting)
• Chunking avanzado (recursive, semantic)
• RAG evaluation sistemática (retrieval + generation metrics)

---

Checklist de Completitud

Marca cada ítem al completarlo:

Funcionalidad

• Ingestion pipeline procesa 1,000+ documentos
• ChromaDB persiste datos en volumen
• /search retorna resultados con scores y metadata
• /ask genera respuestas con fuentes
• /ingest acepta documentos vía API o script

Calidad

• Accuracy ≥ 85% en golden set
• Latencia p95 /ask < 2.5s
• Error rate < 1%

Operación

• Docker Compose levanta todo con un comando
• /health verifica ChromaDB
• /metrics expone Prometheus
• Logs estructurados (JSON) con trace_id

Resiliencia

• Retries en ChromaDB y OpenAI
• Fallbacks cuando retrieval o generation fallan
• Plan de rollback documentado

Seguridad

• API key opcional en headers
• Rate limiting en /ask
• Validación de inputs (Pydantic)

Documentación

• README con arquitectura, setup, API reference
• DEPLOYMENT.md con instrucciones
• CHANGELOG con decisiones relevantes
• metrics-report.md con resultados de evaluación

---

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

Este proyecto es la base directa para la Guía #8. No es código desechable: es la fundación que evoluciona.

En la Guía #8 harás:

Transformación	Descripción
ChromaDB → Pinecone	Migración a vector DB managed en cloud
Retrieval + Re-ranking	Cross-encoders para mejorar precisión de top-k
Query optimization	Expansion, rewriting, decomposition
Chunking avanzado	Recursive, semantic chunking
RAG evaluation	Métricas de retrieval (MRR, recall) + generation (faithfulness, relevance)

Requisitos previos para Guía #8:

• Base del proyecto estable y versionada (Git)
• Métricas mínimas del piloto registradas
• Lista de mejoras priorizada por impacto
• Decisión preliminar sobre migración (si Pinecone encaja con tu caso)

---

Ejercicios del Proyecto con Soluciones Detalladas

Ejercicio 1: Script de ingestion de 1,000 documentos sintéticos

Objetivo: Crear scripts/ingest_sample_docs.py que genere 1,000 documentos de Wikipedia simulados e los indexe en ChromaDB.

Solución:

# scripts/ingest_sample_docs.py
import chromadb
from chromadb.utils import embedding_functions
import os

categories = ["science", "history", "technology", "arts", "sports"]
ef = embedding_functions.OpenAIEmbeddingFunction(api_key=os.getenv("OPENAI_API_KEY"))

client = chromadb.PersistentClient(path="./chroma_data")
collection = client.get_or_create_collection("rag_docs", embedding_function=ef)

docs, metadatas, ids = [], [], []
for i in range(1000):
    cat = categories[i % len(categories)]
    text = f"Article about {cat} topic {i}. This document contains information relevant to {cat}."
    docs.append(text)
    metadatas.append({"category": cat, "doc_id": i})
    ids.append(f"doc_{i}")

batch_size = 100
for i in range(0, len(docs), batch_size):
    collection.add(documents=docs[i:i+batch_size], metadatas=metadatas[i:i+batch_size], ids=ids[i:i+batch_size])
    print(f"Ingested {min(i+batch_size, len(docs))}/{len(docs)}")

print(f"Done. Total: {collection.count()} documents")

Ejercicio 2: Generar metrics-report.md automáticamente

Objetivo: Script que ejecuta evaluation y escribe metrics-report.md con tabla de resultados.

Solución:

# scripts/run_evaluation.py
import httpx
import time
import json

def run_eval():
    base = "http://localhost:8000"
    latencies = []
    for _ in range(50):
        s = time.perf_counter()
        r = httpx.post(f"{base}/ask", json={"question": "¿Qué es RAG?"}, timeout=10)
        latencies.append(time.perf_counter() - s)
    latencies.sort()
    p95 = latencies[int(0.95 * len(latencies))]
    # Accuracy: asumir golden set en tests; aquí simplificado
    report = f"""# Metrics Report

| Métrica | Valor | Umbral | Estado |
|---------|-------|--------|--------|
| p95 /ask | {p95:.2f}s | <2.5s | {'✅' if p95 < 2.5 else '❌'} |
"""
    with open("metrics-report.md", "w") as f:
        f.write(report)
    print(report)

if __name__ == "__main__":
    run_eval()

Ejercicio 3: README con diagrama de arquitectura

Objetivo: README completo con diagrama ASCII o Mermaid, setup en 5 pasos, y tabla de API.

Solución:

# RAG API con ChromaDB

Sistema RAG production-ready: 1,000+ docs, FastAPI, Docker, tests.

## Arquitectura

\`\`\`
┌─────────┐   ┌──────────┐   ┌─────────┐   ┌───────────┐   ┌────────┐
│ Documentos│──▶│ Chunking │──▶│Embeddings│──▶│ ChromaDB  │──▶│Retrieval│
└─────────┘   └──────────┘   └─────────┘   └───────────┘   └────┬────┘
                                                                 │
┌─────────┐   ┌──────────┐   ┌─────────┐                        │
│ Response │◀──│   LLM    │◀──│ Context │◀───────────────────────┘
└─────────┘   └──────────┘   └─────────┘
\`\`\`

## Setup (5 pasos)

1. Clone: \`git clone <repo>\`
2. Copy env: \`cp .env.example .env\` y añade \`OPENAI_API_KEY\`
3. Build: \`docker-compose build\`
4. Up: \`docker-compose up -d\`
5. Test: \`curl http://localhost:8000/health\`

## API Reference

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| /health | GET | Health + ChromaDB status |
| /search?q=&top_k=5 | GET | Búsqueda semántica |
| /ask | POST | {\"question\": \"...\"} |
| /ingest | POST | Ingestion batch |
| /metrics | GET | Prometheus |

---

Guía de Troubleshooting del Proyecto

Síntoma	Causa probable	Acción
/health devuelve 503	ChromaDB no alcanzable	Verificar que chromadb está up en docker-compose; revisar CHROMA_HOST
/ask tarda >10s	LLM timeout o embeddings lentos	Revisar OPENAI_API_KEY; reducir top_k
Accuracy < 85%	Chunking inadecuado o corpus pobre	Ajustar chunk_size/overlap; ampliar golden set
Build de Docker falla	Dependencias o memoria	docker system prune; aumentar memoria para Docker
Tests de integration fallan	API no levantada	docker-compose up -d antes de pytest
ChromaDB vacío tras reinicio	Volumen no persistente	Verificar que volumen está en docker-compose y no se usa docker-compose down -v

---

Decisiones Técnicas a Documentar (DECISIONS.md)

Incluye en tu proyecto un archivo DECISIONS.md con:

1. Por qué ChromaDB: Gratuito, local, suficiente para 1K-10K docs; migración a Pinecone planeada para escala.
2. Chunk size 512: Balance entre contexto y granularidad; validado con recall en golden set.
3. top_k = 5: Suficiente para la mayoría de preguntas; latencia aceptable.
4. Embedding model: text-embedding-3-small por costo/calidad para MVP.
5. LLM: GPT-3.5-turbo para generación; GPT-4 opcional para casos complejos.
6. Sin Redis inicial: Cache en memoria para desarrollo; Redis en siguiente iteración.

---

Ejemplo de CHANGELOG.md

# Changelog

## [1.0.0] - 2026-03-13

### Added
- Ingestion pipeline para 1,000+ documentos
- Endpoints /health, /search, /ask, /ingest
- Docker deployment con docker-compose
- Suite de tests (unit, integration, performance, accuracy)
- Métricas Prometheus y logging estructurado
- Retry logic y fallbacks para ChromaDB y OpenAI
- Rate limiting y validación de inputs

### Decisions
- ChromaDB como vector store inicial (migración a Pinecone en Guía #8)
- chunk_size=512, overlap=64
- Umbrales: accuracy ≥85%, p95 <2.5s

---

Criterios de Portfolio Quality

Tu proyecto está listo para portfolio si:

• Un recruiter puede clonar y ejecutar en < 5 minutos
• README explica claramente qué hace y cómo usarlo
• Hay evidencia de tests (badge o mención en README)
• El código está organizado y con tipos/documentación mínima
• Hay decisiones técnicas documentadas
• Conectas explícitamente con "próximo paso: Guía #8"

---

Script de Verificación Pre-Entrega

Ejecuta antes de marcar el proyecto como completado:

#!/bin/bash
# scripts/pre_submit_check.sh
set -e
echo "1. Docker Compose..."
docker-compose up -d
sleep 10

echo "2. Health check..."
curl -sf http://localhost:8000/health | jq .

echo "3. Search..."
curl -sf "http://localhost:8000/search?q=vector&top_k=3" | jq '.documents | length'

echo "4. Ask..."
curl -sf -X POST http://localhost:8000/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"¿Qué es RAG?"}' | jq '.answer, .sources'

echo "5. Metrics..."
curl -sf http://localhost:8000/metrics | head -20

echo "6. Tests..."
pytest tests/ -v --tb=short -x

echo "✅ Pre-submit check passed"
docker-compose down

---

Integración con Cápsulas Anteriores

Cápsula	Qué aporta a este proyecto
01-02	Arquitectura y diagrama de flujo
03	Pipeline de ingestion, chunking, batch
04	Retrieval, generation, contrato de API
05	Fixtures, tests unit/integration/performance/accuracy
06	Dockerfile, docker-compose, Prometheus, logs
07	Retries, fallbacks, rate limit, README
08	Integración total y checklist de cierre

---

Formato de Entrega Recomendado

Estructura mínima para compartir (GitHub, portfolio):

project/
├── app/
├── tests/
├── scripts/
├── docker-compose.yml
├── Dockerfile
├── README.md           # Arquitectura, setup, API, troubleshooting
├── DEPLOYMENT.md       # Staging, producción, rollback
├── CHANGELOG.md        # Decisiones y versiones
├── metrics-report.md   # Tabla final de métricas
└── .env.example

---

Troubleshooting de Cierre

"Cumplimos funcionalidad, fallamos operación"

No cierres el proyecto hasta cubrir mínimos de observabilidad y resiliencia. Un sistema sin health checks ni fallbacks no está production-ready.

"Métricas correctas en test set, no en tráfico real"

Incorpora feedback real (logs de preguntas fallidas) y recalibra umbrales. El golden set es una aproximación; el tráfico real puede revelar edge cases.

"Equipo quiere pasar a la siguiente guía ya"

Cierra primero la deuda crítica de hardening. Migrar a Pinecone con un sistema frágil arrastrará problemas multiplicados.

"No tenemos 1,000 documentos reales"

Usa el script de documentos sintéticos del Ejercicio 1. El objetivo es validar que el pipeline escala; el contenido puede ser simulado.

"Docker build falla por memoria"

Reduce batch_size en ingestion o usa una máquina con más RAM para el build. En CI, considera build en servidor remoto.

---

Siguientes Pasos Sugeridos

1. Definir backlog de mejoras — Top 5 priorizado por impacto (ej: caching, re-ranking, más documentos).
2. Priorizar evaluación de retrieval — Recall@k, MRR con juicios humanos o LLM-as-judge.
3. Preparar transición a Guía #8 — Revisar prerequisitos, tener API key de Pinecone si aplica.

---

Resumen

• Completaste el proyecto integrador de la guía Vector Databases Fundamentals.
• Tienes un sistema RAG con ChromaDB, FastAPI, Docker, tests, observabilidad y hardening.
• Sabes qué aprendiste en toda la guía y qué viene en la Guía #8 (Advanced RAG).
• Tienes una base sólida para evolucionar a técnicas avanzadas de RAG: migración a Pinecone, re-ranking, query optimization, evaluación sistemática.

¡Felicidades! Construiste un sistema que un AI Engineer mostraría en una entrevista. Sigue con la Guía #8 para llevarlo al siguiente nivel.

---

Plantilla de golden_set.json Extendido

Para tener cobertura completa, usa al menos 40 preguntas en tu golden set:

[
  {"question": "¿Qué es un vector database?", "expected_keywords": ["vector", "embedding", "búsqueda"], "category": "frequent"},
  {"question": "¿Cómo funciona HNSW?", "expected_keywords": ["grafo", "aproximado", "vecino"], "category": "frequent"},
  {"question": "¿Cuándo usar ChromaDB?", "expected_keywords": ["local", "desarrollo", "RAG"], "category": "frequent"},
  {"question": "¿Qué es RAG?", "expected_keywords": ["retrieval", "generación", "documentos"], "category": "frequent"},
  {"question": "¿Cuál es la diferencia entre HNSW e IVF?", "expected_keywords": ["grafo", "clustering"], "category": "difficult"},
  {"question": "¿Qué pasó el 15 de marzo de 2030 en Marte?", "expected_keywords": ["no tengo", "evidencia", "desconocido"], "category": "out_of_coverage"}
]

Categorías recomendadas: 20 frequent, 10 difficult, 10 out_of_coverage.

---

Comparativa: Antes vs Después de la Guía

Aspecto	Antes de la guía	Después del Módulo 8
Vector DB	No sabías cuándo ni por qué	Entiendes arquitectura, usas ChromaDB
RAG	Concepto teórico	Sistema completo con ingestion, retrieval, generation
Producción	"Funciona en mi máquina"	Docker, tests, métricas, hardening
Decisión tecnológica	Intuición	Framework de decisión documentado
Siguiente paso	Incierto	Guía #8: Pinecone, re-ranking, evaluation

---

Recursos Adicionales

• GitHub README Best Practices
• Keep a Changelog — Formato de CHANGELOG
• Guía #8: Advanced RAG Techniques — Próximo paso
• ChromaDB Documentation — Referencia
• FastAPI Deployment — Opciones de deploy
• RAGAS Evaluation — Métricas RAG
• Pinecone Getting Started — Para Guía #8
• Semantic Chunking — Chunking avanzado

---

Preguntas Frecuentes del Proyecto Final

¿Puedo usar otro LLM en lugar de OpenAI?
Sí. Sustituye app/generation/generator.py por la integración con Anthropic, local LLM (Ollama), etc. El contrato (question + docs → answer) se mantiene.

¿ChromaDB es suficiente para producción?
Para 1K-100K docs y tráfico moderado, sí. Para millones de vectores o multi-tenant a escala, la Guía #8 con Pinecone es el camino.

¿Necesito Redis para el cache?
No es obligatorio. Puedes empezar con cache en memoria. Redis aporta persistencia y compartir cache entre réplicas.

¿Cómo añado más documentos después del deploy?
Usa POST /ingest con el lote nuevo. Los IDs deben ser únicos. Si usas IDs determinísticos (ej: hash del contenido), la re-ingestion es idempotente.

¿Qué hago si accuracy no llega al 90%?
Revisa: (1) chunk_size y overlap, (2) top_k, (3) calidad del corpus, (4) prompt de generación. Añade casos fallidos al golden set y itera.

---

Timeline Sugerido de Implementación

Si dispones de 3-4 horas para el proyecto completo:

Bloque	Duración	Actividad
1	45 min	Setup, config, ingestion pipeline, script de 1000 docs
2	45 min	Retrieval, generation, endpoints API
3	45 min	Docker, docker-compose, health, metrics
4	45 min	Tests (unit, integration), golden set, accuracy
5	30 min	Hardening (retries, fallbacks, rate limit)
6	30 min	README, DEPLOYMENT.md, CHANGELOG, evaluación final

Ajusta según prioridades. Lo crítico: que funcione end-to-end y esté en Docker antes de refinar detalles.

---

Checklist de Transición a Guía #8

Antes de comenzar la Guía #8 (Advanced RAG Techniques), verifica:

• Proyecto en Git con commits coherentes
• README actualizado con estado actual
• Métricas del piloto (accuracy, latencia) registradas
• Lista de mejoras priorizada (top 5)
• Cuenta Pinecone creada (si vas a migrar)
• Entiendes qué problemas resolverá re-ranking y query optimization

---

Tiempo estimado: 60-90 minutos (integración completa)
Siguiente guía: Advanced RAG Techniques — Migración a stack más avanzado y optimizaciones de retrieval.

---

Mensaje Final

Completaste los 8 módulos de la guía Vector Databases Fundamentals. Pasaste de "¿qué es un vector?" a "tengo un sistema RAG desplegado con ChromaDB, Docker, tests y monitoreo". Eso es un logro real.

El proyecto que construiste no es un ejercicio académico. Es una base reutilizable para la Guía #8, donde migrarás a Pinecone, añadirás re-ranking y evaluarás tu RAG de forma sistemática. Cada decisión que documentaste (chunk_size, top_k, ChromaDB vs managed) te servirá para justificar cambios en entrevistas y en producción.

Sigue con la Guía #8 cuando estés listo. El camino de AI Engineering es iterativo: lo que hoy es "production-ready" mañana será "MVP que evolucionamos". Lo importante es que ya sabes cómo construir esa base.

---

Resumen de Entregables por Cápsula

Cápsula	Entregable clave
01-02	Diagrama de arquitectura, contratos entre componentes
03	Pipeline de ingestion para 1,000+ docs, validaciones
04	Endpoints /search, /ask con contrato estable
05	Fixtures, tests unit/integration/performance/accuracy
06	Dockerfile, docker-compose, Prometheus, logging
07	Retries, fallbacks, rate limit, README
08	Integración total, checklist, conexión Guía #8

Cada entregable es verificable: puedes marcar la cápsula como completada cuando el ítem correspondiente funciona en tu proyecto.

---

Comandos de Verificación Rápida

Antes de dar por cerrado el proyecto, ejecuta:

docker-compose up -d && sleep 15
curl -s http://localhost:8000/health | jq
curl -s -X POST http://localhost:8000/ask -H "Content-Type: application/json" -d '{"question":"¿Qué es RAG?"}' | jq '.answer'
pytest tests/ -v --tb=line -q

Si los tres comandos pasan, tu sistema está listo para entrega.