Módulo 4: ChromaDB Setup y Configuración

Módulo 4: ChromaDB Setup y Configuración

Siguiente →

Descripción del módulo

¡Llegó el momento de implementar! Después de 3 módulos conceptuales (Por qué, Cómo, Qué features), ahora construirás tu primer vector database con ChromaDB.

Este módulo es 80% hands-on: Código ejecutable, configuración real, debugging práctico. Aplicarás todo lo aprendido:

  • Configurar HNSW con parámetros óptimos (Módulo 2)
  • Implementar metadata filtering (Módulo 3)
  • Batch ingestion eficiente (Módulo 3)
  • Monitoreo básico (Módulo 3)

Al finalizar este módulo, tendrás:

  • ✅ ChromaDB funcionando localmente
  • ✅ Collection configurada con HNSW optimizado
  • ✅ Pipeline de ingestion para 10K-100K documentos
  • ✅ Queries con metadata filtering funcionales
  • ✅ Benchmarks de performance (latency, throughput)

Este módulo es 80% código, 20% conceptual. Prepara tu IDE!

🎯 Objetivo del módulo

Objetivo profesional:

Implementar y configurar ChromaDB localmente con HNSW optimizado, metadata filtering, y batch ingestion eficiente, validando performance con benchmarks reales (latency <50ms, throughput >1K docs/sec).

¿Por qué ChromaDB para empezar?

  • ✅ Zero setup: Funciona en Python sin servidor externo
  • ✅ HNSW nativo: Alta accuracy (98%) out-of-the-box
  • ✅ Perfecto para MVP: 10K-500K vectores sin complejidad
  • ✅ Migration path: ChromaDB → Pinecone/Weaviate cuando escales

Analogía: ChromaDB es como SQLite para vector databases. Simple, local, perfecto para aprender y prototipar.

📚 Contenido del módulo

Cápsula 01: Introducción al módulo (estás aquí)

  • Objetivo y filosofía del módulo
  • Por qué ChromaDB para aprender
  • Setup requirements y progresión

Cápsula 02: ChromaDB Installation y Setup

  • Installation (pip install chromadb)
  • Client modes (ephemeral, persistent, client-server)
  • Primera collection (hello world)
  • Verificar instalación funcional

Cápsula 03: Collection Configuration (HNSW Parameters)

  • Configurar HNSW (M, efConstruction, efSearch)
  • Distance metrics (cosine, L2, dot product)
  • Collection metadata y settings
  • Validar configuración óptima

Cápsula 04: Metadata Filtering Implementation

  • Agregar metadata a documentos
  • Where clauses (equality, range, logical)
  • Pre-filtering vs post-filtering en ChromaDB
  • Benchmark filtering impact (latency reduction)

Cápsula 05: Batch Ingestion Pipeline

  • Single vs batch insert (benchmark)
  • Optimal batch size para ChromaDB (1000-5000)
  • Progress tracking y error handling
  • Concurrent batches (ThreadPoolExecutor)

Cápsula 06: Query Optimization

  • Basic query (top-k similarity)
  • Query con metadata filtering
  • Ajustar n_results según accuracy needed
  • Benchmark query performance (p50, p95, p99)

Cápsula 07: Persistence y Durability

  • Ephemeral vs persistent client
  • Data directory configuration
  • Backup strategies (simple copy)
  • Recovery y migrations

Cápsula 08: Mini-Proyecto - Document Search System

  • Problema: Indexar 10K Wikipedia articles
  • Pipeline completo (embed → batch insert → query)
  • Metadata filtering por category y date
  • Benchmark final (latency, accuracy, throughput)
  • Resumen y transición a Módulo 5

🔗 Conexión con otros módulos

Prerequisitos:

  • Módulo 1: Por qué Vector DBs (entiendes necesidad)
  • Módulo 2: Cómo funcionan HNSW (configurarás parámetros informadamente)
  • Módulo 3: Features esenciales (implementarás filtering, batch ops)

Este módulo prepara para:

  • Módulo 5: ChromaDB + RAG completo (integrarás LLM + vector DB)
  • Módulo 6-8: Production (escalarás, migrarás, optimizarás)

Flujo completo:

Módulo 1-3: Fundamentos conceptuales (100% teoría)
  ↓
Módulo 4: ChromaDB Setup ← Estás aquí (80% código)
  ↓
Módulo 5: ChromaDB + RAG (90% código, integración completa)
  ↓
Módulo 6-8: Production considerations (70% práctico)

⏱️ Tiempo estimado

Lectura + Código: 90-120 minutos

Desglose por cápsula:

  • Cápsula 01: 5 min (introducción)
  • Cápsula 02: 12-15 min (installation + setup)
  • Cápsula 03: 12-15 min (HNSW configuration)
  • Cápsula 04: 12-15 min (metadata filtering)
  • Cápsula 05: 15-18 min (batch ingestion)
  • Cápsula 06: 10-12 min (query optimization)
  • Cápsula 07: 8-10 min (persistence)
  • Cápsula 08: 25-30 min (mini-proyecto)

Total: 99-130 minutos

Nota: Este módulo requiere ejecutar código (no solo leer). Planea tiempo para experimentar.

🎓 ¿Qué aprenderás en este módulo?

Al finalizar este módulo, serás capaz de:

1. Setup ChromaDB correctamente

  • ✅ Instalar ChromaDB (pip)
  • ✅ Elegir client mode (ephemeral vs persistent)
  • ✅ Crear collections con configuración óptima
  • ✅ Debuggear errores comunes (dependency issues)

2. Configurar HNSW inteligentemente

  • ✅ Ajustar M, efConstruction, efSearch según requisitos
  • ✅ Elegir distance metric (cosine, L2, dot product)
  • ✅ Validar accuracy vs latency trade-off
  • ✅ Benchmark configuraciones (A/B testing)

3. Implementar metadata filtering

  • ✅ Agregar metadata estructurada (category, date, tags)
  • ✅ Queries con where clauses (equality, range, logical)
  • ✅ Medir impact en latency (10x speedup esperado)
  • ✅ Debuggear queries lentos (profiling)

4. Optimizar batch ingestion

  • ✅ Implementar batch insert (1000-5000 batch size)
  • ✅ Progress tracking (tqdm, logging)
  • ✅ Error handling (retry logic)
  • ✅ Concurrent batches (4x speedup)

5. Benchmark performance

  • ✅ Medir latency (p50, p95, p99)
  • ✅ Medir throughput (docs/sec, queries/sec)
  • ✅ Medir accuracy (retrieval recall@10)
  • ✅ Identificar bottlenecks (profiling)

💡 Filosofía del módulo

Por qué hands-on después de 3 módulos conceptuales

Podrías preguntarte: "¿Por qué no empezar con código desde Módulo 1?"

Respuesta: Fundamentos primero → Implementación informada.

Sin fundamentos (típico tutorial):

# Tutorial típico: "Copia este código"
collection = client.create_collection("docs")
collection.add(documents=["Hello"], ids=["1"])
results = collection.query(query_texts=["Hi"], n_results=1)

# ❌ Problema: No entiendes POR QUÉ funciona, CÓMO optimizar

Con fundamentos (este curso):

# Con conocimiento de Módulos 1-3
collection = client.create_collection(
    name="docs",
    metadata={
        # Módulo 2: Configurar HNSW inteligentemente
        "hnsw:M": 32,  # Alta accuracy (entiendes trade-off)
        "hnsw:construction_ef": 200,
        "hnsw:search_ef": 100,
        "hnsw:space": "cosine"  # Text embeddings
    }
)

# Módulo 3: Batch insert (100x faster que single)
collection.add(
    documents=batch_docs,  # 1000 docs
    metadatas=batch_metadata,  # Filtering support
    ids=batch_ids
)

# Módulo 3: Metadata filtering (10x speedup)
results = collection.query(
    query_texts=["Hi"],
    where={"category": "support"},  # Pre-filter
    n_results=10
)

# ✅ Ventaja: Entiendes cada parámetro, puedes optimizar

Diferenciador clave vs competencia

90% de tutoriales ChromaDB:

  • Muestran código básico sin explicar configuración
  • No cubren batch ingestion, metadata filtering optimization
  • No benchmarking (no sabes si es rápido o lento)

Este módulo:

  • Código con contexto (POR QUÉ cada parámetro)
  • Benchmarks reales (latency, throughput antes/después)
  • Decision framework (cuándo ajustar M, efSearch)

🚫 Qué NO cubre este módulo

Este módulo NO cubre:

❌ Integración con LLM (eso es Módulo 5)

  • No conectarás OpenAI API todavía
  • No construirás RAG system completo
  • Solo vector database aislada

❌ Production deployment (eso es Módulos 6-8)

  • No Docker, Kubernetes, cloud deployment
  • Solo local development
  • Migration a Pinecone viene después

❌ Advanced features (eso es Módulo 7-8)

  • No distributed sharding
  • No custom distance metrics
  • No multi-tenancy avanzado

Scope claro: Este módulo es sobre ChromaDB fundamentals bien hechos. Integración y production vienen después.

✅ Criterios de éxito

Completaste exitosamente este módulo cuando:

Puedes ejecutar estos comandos sin errores:

import chromadb

# 1. Setup
client = chromadb.PersistentClient(path="./chroma_db")

# 2. Collection con HNSW optimizado
collection = client.create_collection(
    name="test",
    metadata={"hnsw:M": 32, "hnsw:space": "cosine"}
)

# 3. Batch insert
collection.add(
    documents=["doc1", "doc2", "doc3"],
    metadatas=[{"cat": "a"}, {"cat": "b"}, {"cat": "a"}],
    ids=["1", "2", "3"]
)

# 4. Query con filtering
results = collection.query(
    query_texts=["doc1"],
    where={"cat": "a"},
    n_results=2
)

print(results)  # ✅ Debe devolver ["doc1", "doc3"]

Puedes responder estas preguntas:

  1. ✅ ¿Cuál es optimal batch size para ChromaDB?

    • Respuesta: 1000-5000 docs (625K docs/min throughput)

  2. ✅ ¿Cómo configurar HNSW para accuracy >95%?

    • Respuesta: M=32, efConstruction=200, efSearch=100-200

  3. ✅ ¿Cuándo usar ephemeral vs persistent client?

    • Respuesta: Ephemeral para testing/prototyping, Persistent para desarrollo/producción

  4. ✅ ¿Cómo medir si metadata filtering está optimizado?

    • Respuesta: Benchmark latency con/sin filtering. Esperado: 10x speedup si filter reduce search space 90%

  5. ✅ ¿Cuál es latency esperada para 100K vectores con HNSW?

    • Respuesta: p50 ~15ms, p95 ~40ms, p99 ~80ms (1536-dim, cosine)

Si respondiste 4-5/5 correctamente Y código ejecuta sin errores → ✅ Módulo completado

🛠️ Setup Requirements

Software necesario

Python:

  • Python 3.8+ (recomendado 3.10+)
  • pip (package manager)

Librerías:

pip install chromadb
pip install numpy  # Para embeddings mock
pip install tqdm   # Progress bars

IDE recomendado:

  • VS Code con Python extension
  • Jupyter Notebook (alternativa)
  • PyCharm Community Edition

Hardware mínimo:

  • RAM: 8 GB (16 GB recomendado)
  • Storage: 5 GB free space
  • CPU: Cualquier CPU moderno (HNSW es CPU-bound)

Preparación antes de empezar

1. Verificar Python version:

python --version  # Debe ser >= 3.8

2. Crear virtual environment (recomendado):

python -m venv venv
source venv/bin/activate  # Mac/Linux
# venv\Scripts\activate   # Windows

3. Instalar ChromaDB:

pip install chromadb

4. Verificar instalación:

import chromadb
print(chromadb.__version__)  # Debe imprimir version (e.g., 0.4.22)

Si todos los pasos funcionan → ✅ Listo para empezar

📖 Cómo usar este módulo

Estrategia recomendada:

  1. Lee + Ejecuta código en paralelo

    • Lee cápsula en un monitor/window
    • Ejecuta código en otro
    • Experimenta con parámetros

  2. No copies código ciegamente

    • Entiende cada línea (usa comentarios)
    • Experimenta: Cambia M=16 a M=32, mide diferencia
    • Rompe código intencionalmente (aprende debugging)

  3. Benchmarking es crítico

    • Ejecuta benchmarks antes/después de optimizaciones
    • Valida que optimizaciones funcionan (no assumptions)
    • Ejemplo: "Batch insert debería ser 100x faster" → Medir!

  4. Mini-proyecto es obligatorio

    • Cápsula 08 es donde consolidas todo
    • No saltees: Es donde aprendes debugging real
    • Si falla, debuggea (mejor aprendizaje)

Tiempo sugerido:

Opción A: Dos sesiones (recomendado)

  • Sesión 1: Cápsulas 01-04 (setup, config, filtering) = 45-60 min
  • Sesión 2: Cápsulas 05-08 (batch, query, mini-proyecto) = 60-70 min

Opción B: Una sesión intensa

  • Todo de corrido = 120-130 min
  • Ventaja: Contexto fresco
  • Desventaja: Fatiga (mucho código)

Recomendación: Opción A (dos sesiones con breaks).

🔗 Recursos para este módulo

Documentación oficial:

  1. ChromaDB Docs - Getting started, API reference
  2. ChromaDB GitHub - Issues, examples

Notebooks de ejemplo:

  1. ChromaDB Quickstart - Official tutorial
  2. ChromaDB with LangChain - Integration example

Debugging:

  1. ChromaDB Troubleshooting - Common issues
  2. Stack Overflow tag: chromadb

Nota: Este módulo es autocontenido (no requieres leer docs externas). Recursos son para profundizar después.

🚀 ¿Listo para empezar?

Próximo paso:

Ve a Cápsula 02: ChromaDB Installation y Setup

Ahí aprenderás:

  1. Installation (pip install chromadb)
  2. Client modes (ephemeral vs persistent vs client-server)
  3. Primera collection (hello world funcional)
  4. Verificar que todo funciona correctamente

Antes de continuar, asegúrate de:

  • ✅ Python 3.8+ instalado
  • ✅ Virtual environment activado (recomendado)
  • ✅ ChromaDB instalado (pip install chromadb)
  • ✅ IDE abierto y listo

Si todo está listo → Sigue a Cápsula 02!

Tiempo de lectura: 5 minutos
Siguiente: 02-installation-setup.md

← AnteriorCápsula 08: Features Comparison y Resumen del MóduloSiguiente →Cápsula 02: ChromaDB Installation y Setup