Intermedio 22 minRAG

RAG local con ChromaDB y Ollama: tutorial Python

RAG en local con ChromaDB y Ollama: tutorial en 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 Mohamed Meguedmi·Actualización 2026-10-14·Probado en Windows, macOS y Linux

#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.
i
Lo que obtienes
Un script de Python de unas 150 líneas que ingiere los PDF de una carpeta, los divide en fragmentos, los indexa en ChromaDB y responde a preguntas en francés con citas. Todo en local, sin ninguna solicitud saliente.

#Prerrequisitos

El kit completo para crear tu propio copiloto de IA.

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.

Entorno de Python
python -m venv .venv
source .venv/bin/activate  # sous Windows : .venv\Scripts\activate
pip install chromadb ollama pypdf

Tres paquetes: chromadb para el almacén vectorial, ollama para el cliente oficial de Python y pypdf para leer PDF. Eso es todo.

Modelos Ollama
ollama pull nomic-embed-text:v1.5
ollama pull qwen3.5:9b

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.

→
Comprobar que Ollama responde
Un simple curl http://localhost:11434/api/tags debería mostrar una lista de tus modelos. Si no aparece nada, el daemon no está iniciado: ollama serve en otra terminal.

#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.

embed.py — prueba rápida
import ollama

resp = ollama.embed(
    model="nomic-embed-text:v1.5",
    input="search_document: Le contrat est résilié en cas de manquement grave.",
)
vec = resp["embeddings"][0]
print(f"Dimension du vecteur : {len(vec)}")
print(f"5 premières valeurs : {vec[:5]}")

Deberías ver «Dimension du vecteur: 768». Si falla con model not found, es que no se ha ejecutado ollama pull nomic-embed-text.

i
Prefijos y coherencia del índice
Nomic v1.5 requiere search_document: delante de cada chunk y search_query: delante de la pregunta. No mezcle vectores producidos con otros modelos, dimensiones o convenciones en una misma colección. La ficha del modelo no justifica una clasificación «top 5 en francés» para su corpus.

#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.

ingest.py
import os
import chromadb
import ollama
from pypdf import PdfReader

client = chromadb.PersistentClient(path="./chroma_db")
# Nouveau nom : un ancien index "docs" peut encore utiliser la distance L2.
collection = client.get_or_create_collection(
    name="docs_nomic_v15_cosine",
    configuration={"hnsw": {"space": "cosine"}},
)

def chunk_text(text, size=800, overlap=100):
    chunks = []
    start = 0
    while start < len(text):
        end = min(start + size, len(text))
        chunk = text[start:end].strip()
        if chunk:
            chunks.append(chunk)
        start += size - overlap
    return chunks

def ingest_pdf(path):
    reader = PdfReader(path)
    name = os.path.basename(path)
    # Ce dossier d'exemple suppose des noms de fichiers uniques.
    # Retire aussi les chunks devenus obsolètes si le PDF a été raccourci.
    collection.delete(where={"source": name})
    count = 0
    for page_num, page in enumerate(reader.pages):
        text = page.extract_text() or ""
        for i, chunk in enumerate(chunk_text(text)):
            emb = ollama.embed(
                model="nomic-embed-text:v1.5",
                input="search_document: " + chunk,
            )["embeddings"][0]
            collection.upsert(
                ids=[f"{name}-p{page_num}-c{i}"],
                embeddings=[emb],
                documents=[chunk],
                metadatas=[{"source": name, "page": page_num + 1}],
            )
            count += 1
    print(f"OK : {name} ({len(reader.pages)} pages, {count} chunks indexés)")

if __name__ == "__main__":
    for f in os.listdir("./pdfs"):
        if f.lower().endswith(".pdf"):
            ingest_pdf(f"./pdfs/{f}")

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.

→
El modo persistente de ChromaDB
PersistentClient conserva la base de datos en el disco. El nuevo nombre docs_nomic_v15_cosine evita reutilizar silenciosamente el índice L2 anterior. Si cambia el modelo, sus prefijos, la dimensión o la distancia, cree una nueva colección y vuelva a indexar los documentos. Haga una copia de seguridad de los PDF antes de volver a indexar: el script elimina primero los chunks antiguos del archivo.

Inicia la ingesta en una carpeta ./pdfs/ que contenga tus documentos:

Iniciar la ingesta
mkdir -p pdfs
# placez vos PDF dans ./pdfs/
python ingest.py
!
PDF escaneados = no hay texto
pypdf solo extrae el texto nativo. Si tus PDF son imágenes escaneadas, extract_text() devolverá un resultado vacío. En ese caso, hay que recurrir a un OCR (Tesseract, o un modelo de visión como Qwen 3.5 9B, multimodal, a través de Ollama) antes de la ingestión.

#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.

search.py
import chromadb
import ollama

client = chromadb.PersistentClient(path="./chroma_db")
collection = client.get_collection(name="docs_nomic_v15_cosine")

def search(question, k=4):
    count = collection.count()
    if count == 0:
        return []
    q_emb = ollama.embed(
        model="nomic-embed-text:v1.5",
        input="search_query: " + question,
    )["embeddings"][0]
    results = collection.query(
        query_embeddings=[q_emb],
        n_results=min(k, count),
    )
    chunks = results["documents"][0]
    metas = results["metadatas"][0]
    return list(zip(chunks, metas))

if __name__ == "__main__":
    hits = search("Quelles sont les conditions de résiliation ?")
    for chunk, meta in hits:
        print(f"[{meta['source']} p.{meta['page']}]")
        print(chunk[:200], "...\n")

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.

chat.py
import ollama
from search import search

SYSTEM = """Tu es un assistant qui répond uniquement à partir du CONTEXTE fourni.
Si la réponse n'est pas dans le contexte, dis-le clairement.
Cite tes sources entre crochets sous la forme [source.pdf p.X]."""

def ask(question):
    hits = search(question, k=4)
    if not hits:
        return "Aucun passage indexé disponible pour répondre."
    context = "\n\n".join(
        f"[{m['source']} p.{m['page']}]\n{c}" for c, m in hits
    )
    prompt = f"CONTEXTE :\n{context}\n\nQUESTION : {question}"
    resp = ollama.chat(
        model="qwen3.5:9b",
        messages=[
            {"role": "system", "content": SYSTEM},
            {"role": "user", "content": prompt},
        ],
        options={"temperature": 0.2, "num_ctx": 8192},
    )
    return resp["message"]["content"]

if __name__ == "__main__":
    while True:
        q = input("\nQuestion (vide pour quitter) > ").strip()
        if not q:
            break
        print("\n" + ask(q))

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.

→
Streaming para una mejor UX
Sustituye ollama.chat por ollama.chat(..., stream=True) e itera sobre la respuesta para mostrar los tokens a medida que llegan. Esto es crucial en cuanto integras este código en una interfaz real (FastAPI + WebSocket o Streamlit).

#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.
!
Limitaciones que debes conocer
Un RAG básico responde bien a preguntas concretas («cuál es la cláusula X»), pero mal a preguntas agregativas («cuántos contratos tienen X»). Para estas últimas, hace falta un agente que consulte la base en varias etapas o un GraphRAG. Es otra historia.

#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.

#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.
¿Esta guía te ha ayudado?

¿Un comentario, un error, una precisión? Avísanos, eso mejora la guía para todos.