En 04-01 dejamos funcionando una búsqueda semántica de fuerza bruta con dos vergüenzas confesas: cada consulta compara la pregunta contra todos los vectores del corpus, y esos vectores viven en una lista de Python que se evapora al reiniciar el proceso, obligando a re-embeber (y re-pagar) toda la documentación en cada arranque. Para el mini-corpus de seis fragmentos daba igual; para las cientos de páginas de la wiki de Nubelia, no. Esta lección presenta la pieza de infraestructura que resuelve ambos problemas: la base de datos vectorial. Veremos qué aporta exactamente (persistencia, índices aproximados, metadatos con filtrado), montaremos ChromaDB en local paso a paso —será la base vectorial de DocuBot durante el resto del curso—, entenderemos a nivel conceptual el trade-off exactitud/velocidad de los índices ANN, y cerraremos con un mapa de alternativas para que sepas elegir con criterio cuando el proyecto no sea DocuBot.

1. Por qué la fuerza bruta no escala
2. Qué aporta una base de datos vectorial
3. Índices ANN: cambiar una pizca de exactitud por mucha velocidad
4. ChromaDB paso a paso: la colección de DocuBot
5. Metadatos y filtrado: buscar solo donde tiene sentido
6. Panorama de alternativas: cómo elegir

Pongamos números al problema. Nuestra función buscar() de 04-01 hace, por cada consulta, una similitud coseno contra cada vector del corpus — coste O(n): crece linealmente con el número de fragmentos.

Y la latencia no es el único problema. Con la lista en memoria:

• Cada arranque re-embebe todo el corpus: minutos de espera y una factura de embeddings repetida sin necesidad — justo el tipo de gasto evitable que aprendimos a perseguir en 03-04.
• No hay actualización incremental: si Nubelia publica una página nueva, o hay que re-embeber todo o hay que inventarse una gestión manual de qué está embebido y qué no.
• No hay filtros: si el usuario pregunta por la versión 2026.2 del producto, la fuerza bruta le puede devolver alegremente documentación de la 2024, porque solo mira cercanía de significado.
• Un solo proceso: dos instancias de DocuBot no pueden compartir la lista.

Sonará familiar: son los mismos motivos por los que las aplicaciones no guardan sus datos en diccionarios de Python sino en una base de datos. Los vectores no son una excepción — solo necesitan una base de datos que sepa hacer la operación "dame los k vecinos más cercanos" de forma eficiente.

Una base de datos vectorial es un almacén especializado en vectores + su texto + sus metadatos, con tres superpoderes:

1. Persistencia. Los vectores se guardan en disco. Embeber el corpus se paga una vez (en la ingesta, que construiremos en 04-03) y las consultas lo reutilizan para siempre. Reiniciar el servicio cuesta cero.
2. Índices ANN (Approximate Nearest Neighbors, vecinos más cercanos aproximados). En lugar de comparar contra todo, el índice organiza los vectores para encontrar los más cercanos visitando solo una pequeña fracción — la búsqueda pasa de O(n) a algo cercano a logarítmico. La palabra "aproximado" tiene letra pequeña; la desgranamos en el siguiente apartado.
3. Metadatos y filtrado. Cada vector lleva adjunto un diccionario de metadatos (categoría, versión, URL de origen, fecha...) y las consultas pueden combinar cercanía semántica con filtros exactos: "los 4 chunks más parecidos a esta pregunta que sean de la categoría permisos y de la versión 2026.2". Para DocuBot esto conecta directamente con el clasificador de 6 categorías de 02-02: clasificar la pregunta primero permite buscar solo en la sección relevante de la documentación.

Además, según el producto: API de upsert (insertar-o-actualizar, clave para re-ingestas), borrado por id, réplicas, control de acceso... Lo esencial es entender que la base vectorial no calcula embeddings (eso sigue siendo trabajo de nuestro embeddings.py, aunque algunas ofrecen hacerlo por comodidad) ni genera respuestas (eso es el LLM): es la pieza intermedia que recuerda y encuentra.

¿Cómo encuentra el vecino más cercano sin mirar todos los vectores? La idea general de los índices ANN es preorganizar los vectores en una estructura que permita descartar regiones enteras del espacio sin visitarlas.

El índice más popular hoy es HNSW (Hierarchical Navigable Small World), que usan Chroma, Qdrant, Weaviate o pgvector. Sin entrar en matemática, la intuición:

• Imagina los vectores como ciudades en el mapa de significados, conectadas con carreteras a sus vecinas cercanas.
• HNSW añade encima capas de autopistas: una capa superior con pocas ciudades muy separadas y conexiones de larga distancia, capas intermedias más densas, y abajo la red local completa.
• Una búsqueda entra por la autopista (saltos largos hacia la región correcta), va bajando de capa (saltos cada vez más finos) y termina explorando solo el vecindario local de la respuesta.
• Resultado: en vez de visitar los 50.000 vectores, visita unos cientos.

La letra pequeña es la palabra aproximado: el índice no garantiza encontrar exactamente los k vecinos más cercanos; garantiza encontrar casi siempre casi todos. La métrica que lo mide se llama recall del índice (porcentaje de los verdaderos k vecinos que el índice devuelve — no lo confundas todavía con el recall de recuperación de 04-05, que mide otra cosa a otro nivel).

Dos consecuencias prácticas para no obsesionarse:

• A la escala de DocuBot (miles de chunks), los valores por defecto de cualquier base vectorial dan recall altísimo con latencia de milisegundos. No toques los parámetros del índice hasta tener un problema medible.
• Perder ocasionalmente el 4º vecino más cercano casi nunca importa en RAG: si tu respuesta depende de recuperar exactamente ese chunk y ningún otro parecido, el problema real suele estar en el chunking o en la redundancia del corpus, no en el índice.

ChromaDB es una base vectorial open source que corre en local (embebida en tu proceso Python o como servidor), persiste en disco y tiene una API mínima — ideal para desarrollo y para proyectos del tamaño de DocuBot. Instalación:

Creamos el módulo que centralizará el acceso (los módulos 4, 5 y 6 lo importarán tal cual):

Desglose:

• PersistentClient(path=...) guarda todo en el directorio indicado. Ahí está la persistencia: mata el proceso, vuelve a arrancar, y los vectores siguen. (Existe también chromadb.Client() puramente en memoria, útil solo para tests.)
• get_or_create_collection: una colección es el equivalente a una tabla — un conjunto de vectores con el mismo modelo de embeddings detrás. docs_nubelia será nuestra colección canónica.
• {"hnsw:space": "cosine"}: le decimos al índice HNSW que mida con coseno, coherente con 04-01. Ojo a un matiz que causa confusión: Chroma devuelve distancias, no similitudes, y con espacio coseno la relación es similitud = 1 - distancia. Distancia 0.2 ⇒ similitud 0.8.

Añadimos documentos. Un punto de diseño deliberado: calculamos los embeddings nosotros, con el embed() de 04-01, y se los pasamos ya hechos a Chroma. Chroma puede calcularlos por su cuenta con un modelo local por defecto, pero perderíamos el control sobre qué modelo se usa — y ya sabemos de 04-01 que mezclar modelos de embeddings es un error silencioso y letal.

Tres detalles importantes:

• upsert en lugar de add: si el id ya existe, actualiza en vez de fallar o duplicar. Es lo que hará re-ejecutable la ingesta de 04-03.
• Los ids son responsabilidad nuestra y conviene que sean deterministas (derivados del origen del chunk), no aleatorios: así la misma página re-ingerida sobrescribe sus propios chunks.
• Chroma guarda el texto junto al vector (documents): al consultar recuperamos directamente el fragmento para el bloque <documentacion>, sin una segunda base de datos.

Y la consulta:

Fíjate en la forma del resultado: cada campo es una lista de listas (resultado["documents"][0]), porque query acepta varias consultas a la vez y devuelve una lista de resultados por consulta. Como enviamos una sola pregunta, siempre indexamos con [0]. Es el tropiezo número uno con la API de Chroma.

El parámetro where combina la búsqueda semántica con filtros exactos sobre los metadatos:

¿Cuándo filtrar en DocuBot? Dos casos con recorrido:

• Por categoría, reutilizando el clasificador de 02-02: si prompt_clasificacion() dice que la pregunta es de facturacion, buscar solo en esa categoría elimina de raíz que un chunk de la API "se cuele" por parecido superficial. (En 04-04 decidiremos cuándo compensa activar este filtro y cuándo es mejor buscar en todo.)
• Por versión del producto: cuando conviven documentación de la versión actual y de versiones antiguas, el filtro evita responder con instrucciones obsoletas — un tipo de error especialmente dañino en soporte.

Una advertencia simétrica: cada filtro es una apuesta. Si el clasificador se equivoca de categoría, el filtro esconde justamente los chunks correctos y la recuperación fracasa sin ruido. Filtra cuando el metadato sea fiable (la versión lo es; una clasificación automática, solo a veces), y mide el efecto con la evaluación de 04-05 antes de dejarlo fijo.

Chroma es nuestra elección didáctica y perfectamente válida para DocuBot, pero el ecosistema es amplio. Lo honesto no es un ranking sino un mapa de criterios:

Los criterios de decisión, en orden razonable de importancia:

1. ¿Local o gestionado? La misma disyuntiva de 01-03 con los LLMs: control y privacidad del dato frente a comodidad operativa. Para documentación interna, dónde viven los vectores importa (los embeddings no son cifrado: de un vector se puede reconstruir mucho del contenido).
2. ¿Qué opera ya tu equipo? Si hay PostgreSQL en producción, pgvector suele ganar por simplicidad operativa aunque otra opción sea "mejor" sobre el papel.
3. Escala real (no aspiracional): miles de vectores → cualquiera vale, empieza simple; decenas de millones → servidor dedicado o gestionado.
4. Filtrado y funciones: si tus consultas dependen de filtros ricos o búsqueda híbrida, mira Qdrant/Weaviate antes.

La buena noticia: como nuestro código aísla el acceso en vectordb.py y los embeddings en embeddings.py, migrar de base vectorial más adelante es un cambio localizado, no una reescritura.

• Confundir distancia con similitud. Chroma devuelve distancias; con espacio coseno, similitud = 1 - distancia. Si tus "similitudes" salen mejores cuanto más bajas, estás leyendo distancias. Convierte en un solo sitio y trabaja siempre en similitud.
• Olvidar metadata={"hnsw:space": "cosine"} al crear la colección: el espacio por defecto puede no ser coseno, y los números dejarán de casar con los de 04-01. Se fija al crear la colección — cambiarlo después implica recrearla.
• Dejar que la base calcule los embeddings con su modelo por defecto. Tendrás un corpus embebido con un modelo y preguntas embebidas con otro: resultados malos sin ningún error visible. Pasa siempre embeddings= calculados con tu embed().
• Ids aleatorios (uuid4) en la carga. Cada re-ingesta duplicará el corpus entero. Ids deterministas + upsert es la pareja correcta.
• Olvidar el [0] al leer los resultados de query (son listas de listas, una por consulta).
• Optimizar el índice ANN prematuramente. A escala DocuBot, los defaults sobran. Mide primero (04-05), ajusta después.
• Consejo: guarda en los metadatos todo lo que puedas necesitar para filtrar o citar (categoría, versión, URL, fecha). Añadir un metadato a posteriori significa re-procesar todo el corpus.

1. Persistencia demostrada. Ejecuta poblar_demo.py, cierra el intérprete de Python, ábrelo de nuevo y, sin volver a añadir nada, ejecuta una consulta sobre obtener_coleccion(). Comprueba con coleccion.count() que los 4 documentos siguen ahí. ¿Qué habría pasado con la lista VECTORES de 04-01?
2. El filtro que ayuda y el filtro que estorba. Con los 4 documentos de la demo, consulta "¿cuántas tareas puedo tener en un proyecto?" primero sin filtro y luego con where={"categoria": "api"}. Compara resultados y explica qué lección práctica se extrae sobre los filtros por clasificación automática.
3. Upsert idempotente. Ejecuta poblar_demo.py tres veces seguidas y comprueba coleccion.count(). Después, cambia el texto del documento informes-export-01 (por ejemplo, añade "La exportación a PDF está prevista para 2027."), re-ejecuta y consulta "¿puedo exportar a PDF?" para verificar que recuperas la versión nueva. ¿Qué dos decisiones del código hacen esto posible?

1. count() devuelve 4 y la consulta funciona: PersistentClient escribió los vectores en ./docubot_db y los recarga del disco. La lista VECTORES de 04-01 habría desaparecido con el proceso, y reconstruirla habría exigido volver a llamar a la API de embeddings para todo el corpus — pagando en tiempo y dinero. Esa es exactamente la diferencia entre una estructura en memoria y una base de datos.

2. Sin filtro, el chunk de "El plan Pro permite hasta 500 tareas por proyecto" sale primero con similitud claramente superior — recuperación correcta. Con where={"categoria": "api"}, ese chunk queda excluido de raíz (su categoría es facturacion) y la consulta devuelve el chunk de autenticación de la API, que es lo más parecido dentro del filtro pero irrelevante para la pregunta. Lección: un filtro basado en una clasificación equivocada no degrada la búsqueda — la sabotea, y además con similitudes bajas que parecen "resultados normales". Por eso en 04-04 trataremos el filtro por categoría como opcional y condicionado a la confianza del clasificador, y por eso el umbral mínimo de similitud del ejercicio 1 de 04-01 será nuestra red de seguridad.

3. count() sigue siendo 4 tras tres ejecuciones: upsert con los mismos ids sobrescribe en lugar de duplicar (si hubiéramos usado add con ids nuevos cada vez, tendríamos 12). Al cambiar el texto de informes-export-01, la re-ejecución recalcula su embedding y sobrescribe vector, texto y metadatos bajo el mismo id, así que la consulta recupera la versión actualizada. Las dos decisiones: ids deterministas (el documento "sabe" cuál es su id) y upsert. Son la base del script de ingesta re-ejecutable de la próxima lección — junto con un tercer paso que aquí hicimos mentalmente: invalidar los cachés de respuestas de 03-04/04-01, porque la documentación acaba de cambiar.

DocuBot ya tiene memoria de largo plazo: la colección docs_nubelia de ChromaDB persiste los vectores en disco (se embebe una vez, se consulta siempre), los encuentra en milisegundos gracias a un índice HNSW que cambia una pizca de exactitud por órdenes de magnitud de velocidad, y guarda junto a cada vector el texto original y unos metadatos (categoría, versión, URL) que permiten filtrar la búsqueda y que pronto alimentarán el campo fuentes del contrato JSON. Hemos encapsulado el acceso en vectordb.py::obtener_coleccion(), aprendido a convertir las distancias de Chroma en las similitudes de 04-01, y situado a Chroma en un mapa de alternativas (pgvector, Qdrant, Weaviate, Pinecone, FAISS) donde la elección correcta depende de criterios —dato local o gestionado, qué opera ya el equipo, escala real— y no de rankings. Pero nuestra colección sigue poblada con cuatro fragmentos escritos a mano en un script de demo. La documentación real de Nubelia son cientos de páginas markdown en la wiki y los repos, con encabezados, tablas y secciones de longitudes salvajes. Convertir ese material bruto en chunks bien cortados, con metadatos ricos y mediante un script de ingesta re-ejecutable es el oficio que aprendemos en la siguiente lección: ingesta y chunking de documentos (04-03).