RAG local con ChromaDB y Ollama: tutorial Python

Implementar un RAG en local con ChromaDB, Ollama y Python implica combinar tres piezas: un almacén vectorial que conserva los datos en disco (ChromaDB), un modelo de embeddings que convierte tus fragmentos en vectores (nomic-embed-text a través de Ollama) y un LLM de chat que responde basándose en los pasajes recuperados. Sin clave de API, sin fugas de datos. Esta guía te lleva de un PDF sin procesar a un chatbot que cita sus fuentes en 22 minutos.
#Por qué esta pila para un RAG local
Muchos tutoriales de RAG comienzan con LangChain o LlamaIndex. Estos frameworks son potentes, pero ocultan lo que sucede bajo el capó. Aquí escribimos el pipeline a mano con solo tres dependencias. Entenderás cada paso y sabrás qué optimizar más adelante.
- ChromaDB
- Almacén vectorial de código abierto, escrito íntegramente en Python, con modo persistente integrado (SQLite + índice HNSW). No hay que iniciar ningún servidor.
- Ollama
- Sirve tanto al modelo de embeddings (nomic-embed-text) como al LLM de chat (Qwen 3.5, Granite 4.2, Gemma 4). Un único endpoint HTTP en localhost:11434.
- Python nativo
- Unas pocas funciones, sin framework. Podrás conectar LangChain más adelante si lo necesitas, pero no es necesario para empezar.
#Prerrequisitos
Aprovecha nuestra experiencia y un recorrido guiado para crear tu copiloto local y dominar tu asistente de código.
- Espacio en línea de por vida
- PDF + archivos
- Reembolsado 30 d
- Python 3.10+
- ChromaDB requiere como mínimo la versión 3.10. Compruébelo con python --version.
- Ollama instalado y ejecutándose
- El daemon escucha por defecto en http://localhost:11434. Si empiezas desde cero, sigue primero la guía de instalación de Ollama.
- 8 GB de RAM
- 16 GB permiten trabajar con comodidad. El modelo de chat de 9B en Q4 ocupa aproximadamente 6 GB y el modelo de embeddings, alrededor de 300 MB.
- No es obligatorio tener una GPU
- La inferencia en CPU funciona, solo que es más lenta. Para ingerir un corpus grande, una GPU de 6 GB o más acelera mucho los embeddings.
#1. Instalar ChromaDB y preparar Ollama
Se crea un entorno virtual limpio, se instalan las tres bibliotecas necesarias y se descargan los modelos en Ollama.
Tres paquetes: chromadb para el almacén vectorial, ollama para el cliente oficial de Python y pypdf para leer PDF. Eso es todo.
El recorrido utiliza nomic-embed-text:v1.5 para hacer explícitos el modelo y sus prefijos de tarea. Sirve como ejemplo inicial; en un corpus francés, mide los resultados de búsqueda y compara especialmente BGE-M3. La calidad también depende de la división y de los documentos.
#2. Configurar el modelo de embeddings
Un embedding es un vector que representa el significado de un texto. Dos textos cercanos semánticamente tienen vectores cercanos. Es el motor del RAG: se buscan los chunks cuyo embedding se parece más al de la pregunta.
Deberías ver «Dimension du vecteur: 768». Si falla con model not found, es que no se ha ejecutado ollama pull nomic-embed-text.
#3. Ingesta de PDF en francés
La ingestión hace tres cosas: leer las páginas de un PDF, dividir el texto en chunks de tamaño razonable y almacenar cada chunk con su embedding en ChromaDB en modo persistente.
El chunker divide en bloques de 800 caracteres con 100 de solapamiento. Es un punto de partida: bloques ni demasiado pequeños (falta de contexto) ni demasiado grandes (diluyen la señal). Para contenido jurídico muy denso, reduce a 500. Para manuales técnicos con una maquetación más espaciada, aumenta a 1200.
Inicia la ingesta en una carpeta ./pdfs/ que contenga tus documentos:
#4. Búsqueda top-k en ChromaDB
La colección anterior elige explícitamente la distancia coseno, a diferencia del ajuste L2 predeterminado. La pregunta recibe el prefijo search_query:, y después ChromaDB encuentra los pasajes más cercanos en este índice. get_or_create_collection no transforma un índice antiguo cambiando únicamente su nombre de variable.
k=4 es un buen valor predeterminado. Si el valor es demasiado pequeño, pierdes contexto relevante; si es demasiado grande, ahogas al LLM en ruido y sobrepasas la ventana de contexto. Para preguntas muy precisas, k=2 es suficiente. Para preguntas transversales, sube a 6.
#5. Bucle de chat con citas
Ahora lo ensamblamos todo: buscamos los chunks pertinentes, construimos un prompt con el contexto, lo enviamos a Qwen 3.5 a través de Ollama y pedimos al modelo que cite sus fuentes.
El contexto num_ctx=8192 debe contener los chunks, la pregunta, las instrucciones y la respuesta; reduce el número de pasajes si falta memoria. El prompt solicita citas y una respuesta basada en los documentos, pero no garantiza la ausencia de alucinaciones: abre las páginas citadas y verifica las afirmaciones.
#6. Ejemplo concreto: chatbot jurídico sobre contratos
Imaginemos un despacho que quiere consultar 200 contratos de prestación de servicios en PDF. Con la pila anterior, en menos de una hora tenemos un asistente que responde a preguntas del tipo:
- Pregunta típica
- «¿Qué contratos incluyen una cláusula de no competencia tras la finalización del contrato con una duración superior a 12 meses?»
- Lo que ocurre
- El embedding de la pregunta encuentra los chunks que contienen palabras clave semánticamente cercanas (no competencia, tras la ruptura, duración). Qwen 3.5 lee estos 4 pasajes y responde con los nombres de los archivos correspondientes.
- Garantía de confidencialidad
- Ningún dato sale del equipo. Sin clave de API. Sin telemetría. Esto es lo que distingue un RAG local de un wrapper de OpenAI.
#Solución de problemas
- ChromaDB lento durante la ingestión
- Mide por separado el tiempo de extracción del PDF, de división, de embedding y de escritura. Comprueba la ubicación del modelo con ollama ps. Esta guía no establece ningún rendimiento universal de 50 o 500 chunks por segundo.
- « model not found »
- Ollama no encuentra nomic-embed-text. Vuelve a ejecutar ollama pull nomic-embed-text y compruébalo con ollama list.
- Respuestas que inventan fuentes
- Un modelo 9B todavía alucina a veces. Pasa a mistral-small (24B, ~14 GB, muy bueno en francés) o a qwen3.8:27b si tienes suficiente VRAM. O añade un reranker (cross-encoder) después de ChromaDB para filtrar los falsos positivos.
- Embeddings de mala calidad en francés
- Evalúa los pasajes recuperados con preguntas en francés cuyas respuestas conozcas. BGE-M3 está disponible directamente con ollama pull bge-m3. Si cambias de modelo, vuelve a indexar en una colección distinta; los prefijos de nomic no deben reutilizarse automáticamente para todos los modelos.
- ChromaDB crece sin límite
- El script actualizado elimina los chunks del archivo antes de volver a ingerirlo y utiliza IDs estables con upsert. Esto también elimina las páginas antiguas de un PDF acortado. Sigue siendo un ejemplo local sencillo: conserva los documentos originales y una copia de seguridad de la base de datos.
#Fuentes y verificación del 14 de octubre de 2026
Revisión del 14 de octubre de 2026: código verificado con un índice ChromaDB real para la clasificación coseno y un PDF de prueba para la reinyección. Las llamadas de embeddings de esta prueba utilizan un servidor de simulación local; la calidad semántica y la velocidad de un modelo Ollama aún deben medirse en su corpus.
- ChromaDB: distancia coseno y configuración
- Nomic v1.5: prefijos de búsqueda
- Ollama: API Embed
- BGE-M3 disponible en Ollama
#Para ir más allá
Tienes un RAG funcional. Estas son las líneas de trabajo que puedes seguir para llevarlo más lejos:
- Comparar los modelos de embeddings FR
- Nuestra guía «Los mejores modelos de embeddings FR» compara BGE, E5, Solon y nomic en contenido francófono.
- Mejorar el chunking
- «Estrategias de chunking» detalla el chunking semántico, por títulos de Markdown o por párrafos: a menudo es lo que más mejora la precisión.
- Añadir un reranker
- «Añadir un reranker a su pipeline»: +15% de relevancia al colocar un cross-encoder después de Chroma. El siguiente paso lógico.
- Búsqueda híbrida
- «Búsqueda híbrida BM25 + vectorial» combina la búsqueda léxica y la semántica, y resulta indispensable cuando hay mucha jerga o nombres propios.
¿Un comentario, un error, una precisión? Avísanos, eso mejora la guía para todos.