Ver todos los artículos
RAGQdrantEmbeddingsOllamaBenchmarks

RAG local con Ollama, Qdrant y bge-m3: guía completa

JG
Jacobo González Jaspe
|

Revisado:

Ilustración abstracta: dos caminos de luz que se separan; uno tenue y blanco, otro ámbar. Desde la spark
Ilustración generada con IA en nuestra máquina.
Este artículo también está en inglés:Local RAG with Ollama, Qdrant and bge-m3: Complete Guide

Al terminar esta guía tendrás un RAG que cabe en un solo archivo de Python. Qdrant guarda los vectores, bge-m3 convierte el texto en vectores y un modelo local pequeño responde y cita los fragmentos que usó. También sabrás qué ajustes merece la pena tocar, porque los medimos. Debería caber en un portátil de 16 GB, aunque no lo medimos en uno; nuestros números salen de dos DGX Spark.

Qué necesitas

  • Docker, para Qdrant.
  • Ollama con dos modelos: ollama pull bge-m3 y ollama pull qwen2.5:7b-instruct.
  • Python 3 con requests. Sin framework y sin clave de API.
  • Una carpeta de archivos Markdown o de texto. Los PDF y los Word hay que pasarlos antes a texto; no probamos ningún conversor.

Cómo encajan las piezas

  1. Trocear: cortas cada documento en fragmentos cortos.
  2. Vectorizar: bge-m3 convierte cada fragmento en 1.024 números.
  3. Guardar: Qdrant conserva cada vector con su texto y su archivo.
  4. Recuperar: la pregunta se vectoriza igual y Qdrant devuelve los fragmentos más cercanos.
  5. Responder: un modelo de chat los lee y los cita por número.

Paso 1: arranca Qdrant

bash
docker run -d --name qdrant -p 127.0.0.1:6333:6333 \
  -v qdrant_data:/qdrant/storage qdrant/qdrant:v1.18.2
curl -s localhost:6333/collections
# {"result":{"collections":[]},"status":"ok","time":0.00001912}

Fijamos la versión que probamos (1.18.2; la última publicada el 15-11-2026 era la 1.20.1). Publicamos el puerto solo en 127.0.0.1, porque la guía de inicio de Qdrant avisa de que arranca sin cifrado y sin autenticación. Si el puerto está ocupado, usa otro y define QDRANT al lanzar el script.

Paso 2: comprueba qué devuelve el modelo de embeddings

bash
curl -s localhost:11434/api/embed -d '{"model": "bge-m3", "truncate": false,
  "input": ["Las vacaciones se piden con quince días de antelación.", "¿Cuántos días de vacaciones tengo?"]}' \
  | python3 -c "import sys,json; e=json.load(sys.stdin)['embeddings']; print(len(e), len(e[0]))"
# 2 1024

Dos frases, dos vectores de 1.024 números. En nuestra prueba cada vector tenía longitud 1,0 y las dos frases dieron un coseno de 0,69. Los campos que importan, según la referencia de embed de Ollama (leída el 15-11-2026):

CampoQué hace
inputUna cadena o una lista. La lista vuelve en el mismo orden.
truncatePor defecto true: recorta sin error el texto que no cabe en el contexto. Con false devuelve un error.
keep_aliveCuánto tiempo sigue el modelo en memoria tras la llamada.
optionsAjustes de ejecución, como num_ctx.

bge-m3 no necesita prefijo en las preguntas: su ficha dice que ya no hace falta añadir instrucciones a la consulta. Otros modelos sí.

Paso 3: crea la colección

El script lo hace por ti. Esta es la petición que envía:

bash
curl -s -X PUT localhost:6333/collections/docs -H 'content-type: application/json' \
  -d '{"vectors": {"size": 1024, "distance": "Cosine"}}'
# {"result":true,"status":"ok",...}
  • size tiene que ser la dimensión del modelo: 1.024 en bge-m3.
  • distance: Cosine es lo que recomienda la guía de embeddings de Ollama para búsqueda semántica. Qdrant acepta también Dot, Euclid y Manhattan.
  • Ninguno de los dos se puede cambiar después. La página de colecciones de Qdrant da el tamaño y la distancia por fijos una vez creado el vector. Modelo de embeddings nuevo, colección nueva.

Paso 4: todo el pipeline en un archivo

Guárdalo como rag_local.py.

Python
import os, sys, uuid, pathlib, requests

OLLAMA = os.environ.get("OLLAMA", "http://localhost:11434")
QDRANT = os.environ.get("QDRANT", "http://localhost:6333")
LLM = os.environ.get("LLM", "qwen2.5:7b-instruct")
KEEP = os.environ.get("KEEP_ALIVE", "5m")
EMBED, DIM = "bge-m3", 1024                # el tamaño del vector de la colección es el del modelo
COLL, SIZE, OVERLAP, TOP_K, NUM_CTX = "docs", 1000, 150, 5, 4096
SYSTEM = ("Responde solo con el contexto y cita entre corchetes el número del fragmento que usas. "
          "Si la respuesta no está en el contexto, di: No lo sé.")

def chunks(text, size=SIZE, overlap=OVERLAP):
    words, out, i = text.split(), [], 0
    while i < len(words):
        start, cur, n = i, [], 0
        while i < len(words) and (not cur or n + len(words[i]) < size):
            cur.append(words[i]); n += len(words[i]) + 1; i += 1
        out.append(" ".join(cur))
        if i >= len(words): break
        back = 0
        while back < overlap and i > start + 1:
            i -= 1; back += len(words[i]) + 1
    return out

def embed(texts):
    r = requests.post(f"{OLLAMA}/api/embed", json={"model": EMBED, "input": texts, "truncate": False, "keep_alive": KEEP})
    r.raise_for_status()
    return r.json()["embeddings"]

def qdrant(method, path, body=None):
    r = requests.request(method, f"{QDRANT}{path}", json=body)
    r.raise_for_status()
    return r.json()["result"]

def ingest(folder):
    if not qdrant("GET", f"/collections/{COLL}/exists")["exists"]:
        qdrant("PUT", f"/collections/{COLL}", {"vectors": {"size": DIM, "distance": "Cosine"}})
        qdrant("PUT", f"/collections/{COLL}/index", {"field_name": "doc", "field_schema": "keyword"})
    for f in sorted(pathlib.Path(folder).glob("*.md")):
        parts = chunks(f.read_text(encoding="utf-8"))
        pts = [{"id": str(uuid.uuid5(uuid.NAMESPACE_URL, f"{f.stem}#{i}")), "vector": vec,
                "payload": {"doc": f.stem, "n": i, "text": part}}
               for i, (vec, part) in enumerate(zip(embed(parts), parts))]
        same_doc = {"filter": {"must": [{"key": "doc", "match": {"value": f.stem}}]}}
        qdrant("POST", f"/collections/{COLL}/points/delete?wait=true", same_doc)   # borra la versión anterior
        qdrant("PUT", f"/collections/{COLL}/points?wait=true", {"points": pts})
        print(f.stem, len(pts))

def ask(question, k=TOP_K):
    hits = qdrant("POST", f"/collections/{COLL}/points/query",
                  {"query": embed([question])[0], "limit": k, "with_payload": True})["points"]
    ctx = "\n\n".join(f"[{i}] ({h['payload']['doc']}) {h['payload']['text']}" for i, h in enumerate(hits, 1))
    msgs = [{"role": "system", "content": SYSTEM},
            {"role": "user", "content": f"Contexto:\n{ctx}\n\nPregunta: {question}"}]
    r = requests.post(f"{OLLAMA}/api/chat", json={"model": LLM, "messages": msgs, "stream": False,
                      "keep_alive": KEEP, "options": {"temperature": 0, "num_ctx": NUM_CTX}})
    r.raise_for_status()
    print(r.json()["message"]["content"], "\n")
    for i, h in enumerate(hits, 1):
        print(f"[{i}] {h['payload']['doc']}#{h['payload']['n']}  score {h['score']:.3f}")

if __name__ == "__main__":
    ingest(sys.argv[2]) if sys.argv[1] == "ingest" else ask(sys.argv[2])

Qué hace cada parte y por qué:

  • chunks corta por palabras en trozos de unos 1.000 caracteres que comparten 150 con el anterior. El solape hace que una frase partida por un corte quede entera en al menos un fragmento.
  • embed envía truncate: false. Si un fragmento sale demasiado largo, recibes un error y no un vector recortado sin aviso.
  • El id de cada punto sale del nombre del archivo y del número de fragmento (Qdrant admite enteros sin signo o UUID). Indexar dos veces el mismo archivo sobrescribe; no duplica.
  • El borrado por filtro quita los fragmentos antiguos de un archivo antes de escribir los nuevos. Sin él, un archivo que se acorta dejaría fragmentos caducados. El índice de tipo keyword sobre doc mantiene rápido ese filtro cuando la colección crece.
  • ask usa la Query API de Qdrant, disponible desde la v1.10, y /api/chat de Ollama con stream: false. num_ctx va en cada petición: cinco fragmentos de 1.000 caracteres ocuparon una mediana de 1.637 tokens de prompt en la medición de abajo, así que 4.096 deja margen. Con fragmentos de 2.000, súbelo a 8.192.

Si un archivo da cientos de fragmentos, envíalos a /api/embed por lotes (nuestro benchmark usó 32).

Paso 5: indexa y pregunta

bash
python3 rag_local.py ingest ./mis-documentos
# copias-seguridad 1
# gastos 1
# impresora 1
# ...
python3 rag_local.py ask "¿Cuánto me pagan por kilómetro si voy con mi coche?"
# [1] 0,26 euros por kilómetro.
#
# [1] gastos#0  score 0.648
# [2] vacaciones#0  score 0.382
# [3] teletrabajo#0  score 0.371
# ...
python3 rag_local.py ask "¿Cuál es el horario del comedor?"
# No lo sé.
#
# [1] teletrabajo#0  score 0.447
# [2] gastos#0  score 0.438

Es salida real del 15-11-2026: seis documentos cortos de oficina que escribimos para la prueba, un contenedor desechable de Qdrant 1.18.2, y bge-m3 y llama3.1:8b en Ollama 0.34.0, en nuestra segunda DGX Spark. Las peticiones, las respuestas y los seis documentos están en rag-qdrant-walkthrough-2026-11-15.json.

En los documentos nadie habla de un comedor, el modelo lo dijo, y aun así Qdrant devolvió cinco fragmentos, el mejor con 0,447. La búsqueda vectorial siempre devuelve sus vecinos más cercanos. Si responden a la pregunta lo deciden el prompt y tu evaluación.

Paso 6: mantén el índice al día

  • Cambió un archivo: vuelve a lanzar ingest. La segunda pasada sobre nuestros seis archivos dejó seis puntos, no doce.
  • Se borró un archivo: quita sus fragmentos con un filtro.
bash
curl -s -X POST 'localhost:6333/collections/docs/points/delete?wait=true' -H 'content-type: application/json' \
  -d '{"filter": {"must": [{"key": "doc", "match": {"value": "impresora"}}]}}'
# {"result":{"operation_id":27,"status":"completed"},"status":"ok",...}
  • Cambias el modelo de embeddings o el tamaño del fragmento: construye una segunda colección, pruébala y después mueve un alias. Qdrant aplica los cambios de alias de forma atómica, así que nadie consulta un índice a medias. Haz que el script consulte el alias (COLL = "docs_live").
bash
curl -s -X POST localhost:6333/collections/aliases -H 'content-type: application/json' -d '{"actions": [
  {"delete_alias": {"alias_name": "docs_live"}},
  {"create_alias": {"collection_name": "docs_v2", "alias_name": "docs_live"}}]}'
# {"result":true,"status":"ok",...}
  • No es de nadie: un RAG se queda viejo sin hacer ruido. Programa la ingesta y nombra a un responsable.

Paso 7: mídelo antes de fiarte

Escribe preguntas como las haría tu equipo y, para cada una, anota qué documento o fragmento la responde. Después puntúa el recuperador por separado:

  • hit@k: preguntas cuyo fragmento correcto está entre los k primeros resultados.
  • MRR: la media de 1 / (posición del primer resultado correcto). La posición 1 vale 1, la 2 vale 0,5 y un fallo vale 0.

El método completo, con el código y la prueba que separa una mejora del ruido, está en Evalúa tu RAG con 54 preguntas. Para practicar, prueba el ejercicio de recuperación top-k.

Qué medimos

Prueba 1, tamaño del fragmento (2-11-2026). 50 artículos nuestros en español (501.917 caracteres) y 60 preguntas escritas a mano con su documento correcto, congeladas en rag-embeddings-es-questions-2026-11-02.json. bge-m3 en Ollama 0.34.0, en nuestra segunda DGX Spark (GB10, 128 GB); Qdrant 1.18.2 y el reranker (BAAI/bge-reranker-v2-m3) en la primera. Respuestas: Qwen2.5-7B-Instruct en BF16 sobre vLLM, temperatura 0, los cinco mejores fragmentos. El script del paso 4 usa la versión de 4 bits de Ollama; estas tablas no se midieron con ella. Los fragmentos se solapan un 15 %. Archivo bruto: rag-embeddings-es-2026-11-02.json.

Tamaño del fragmentoFragmentoshit@1hit@5MRRhit@5 + rerankerMRR + reranker
500 caracteres1.22981,7 %96,7 %0,885100 %0,908
1.000 caracteres61078,3 %96,7 %0,862100 %0,928
2.000 caracteres31083,3 %100 %0,895100 %0,947

Cada documento cuenta una vez, en su mejor fragmento; el reranker vuelve a puntuar los 40 primeros fragmentos. Lo que le costó al modelo de 7B (medianas de 60 respuestas, tras el reranker):

Tamaño del fragmentoTokens del promptTiempo de respuestaAnclaje”No lo sé”
500 caracteres8393,6 s0,874 de 60
1.000 caracteres1.6374,0 s0,933 de 60
2.000 caracteres3.1785,2 s0,942 de 60

El anclaje es la parte de las frases de la respuesta que el reranker puntúa con 0,35 o más frente a los cinco fragmentos. Es una comprobación automática, no humana.

Prueba 2, búsqueda híbrida y reranker (15-11-2026). Un conjunto más difícil: el texto en español del Reglamento de IA en 761 fragmentos y 54 preguntas escritas a mano, cada una ligada a su pasaje exacto. bge-m3 en Ollama 0.30.10 y el mismo reranker sobre vLLM 0.19.0, en nuestra primera Spark. Archivo bruto: reranker-es-legal-2026-11-15.json; con la GPU libre: reranker-es-legal-idle-gpu-2026-11-16.json.

MétodoPrimer puestoEntre 5Entre 10MRR@10
Solo embeddings (bge-m3)41 de 5447480,81
Solo BM25 (palabras clave)23 de 5431370,49
Híbrida: ambos fundidos con RRF34 de 5444480,72
Embeddings, 25 primeros con reranker44 de 5450510,86
Híbrida, 50 primeros con reranker44 de 5450500,86

Las decisiones que importan

Tamaño del fragmento y solape. En la prueba 1 los tres tamaños se separan por una o dos preguntas, y el margen del 95 % sobre un hit@5 del 96,7 % es de unos ±4,5 puntos. La recuperación no elige ganador. La factura del modelo, sí: pasar de 1.000 a 2.000 caracteres casi duplicó el prompt (de 1.637 a 3.178 tokens) y sumó unos 1,3 segundos por respuesta. En una máquina pequeña con una ventana de contexto corta, eso decide. El solape fue siempre del 15 %; no lo variamos.

Top-k. Más fragmentos son más oportunidades y un prompt más largo. En la prueba 2, los embeddings solos tenían el pasaje correcto entre los 5 primeros en 47 preguntas y entre los 10 primeros en 48. Duplicar k compró una pregunta de 54.

Búsqueda híbrida. Suma una búsqueda por palabras clave (BM25, sobre vectores dispersos) a la vectorial y funde las dos listas. En la prueba 2 perjudicó: frente a los embeddings solos, la fusión subió el pasaje correcto en 3 preguntas y lo bajó en 15 (prueba de signos, p = 0,0075). BM25 puso primero 14 de las 18 preguntas literales, pero solo 2 de las 18 escritas con palabras de la calle. Nuestro BM25 era sencillo, sin lematizar y sin lista de palabras vacías, y el texto legal es un tipo de corpus. Donde las palabras clave se ganan el sitio es en códigos de producto, números de factura y apellidos: en la prueba guiada, la pregunta por el error “E-204” sacó 0,36 con embeddings y fue la única coincidencia de BM25.

Un reranker. Un cross-encoder lee juntos la pregunta y un fragmento y devuelve una puntuación de relevancia. En la prueba 2 llevó el primer puesto de 41 a 44 de 54: ganó 6 preguntas y perdió 3, y la prueba de signos da p = 0,51, que a este tamaño es ruido. En la prueba 1 dependió del tamaño del fragmento. Con 1.000 caracteres, el documento correcto subió en 12 preguntas y bajó en 2 (p = 0,013); con 500 fueron 6 arriba y 5 abajo. Costó una mediana de 87 ms para 25 fragmentos con la GPU libre (217 ms ocupada).

Añade búsqueda híbrida o un reranker

Los dos son opcionales. Cada petición se ejecutó el 15-11-2026 y está en el archivo de la prueba guiada.

Híbrida dentro de Qdrant. Crea la colección con un vector denso con nombre y uno disperso:

JSON
{"vectors": {"dense": {"size": 1024, "distance": "Cosine"}},
 "sparse_vectors": {"bm25": {"modifier": "idf"}}}

Guarda cada fragmento con los dos nombres. Qdrant construye el vector BM25 a partir del texto (en su documentación está en Inference; funcionó en nuestro 1.18.2 autoalojado):

JSON
{"id": 1, "payload": {"doc": "gastos"},
 "vector": {"dense": [0.01, 0.02],
            "bm25": {"text": "<texto del fragmento>", "model": "qdrant/bm25", "options": {"language": "spanish"}}}}

Después consulta los dos y fúndelos, como en la página de consultas híbridas de Qdrant:

JSON
{"prefetch": [{"query": [0.01, 0.02], "using": "dense", "limit": 20},
              {"query": {"text": "<pregunta>", "model": "qdrant/bm25", "options": {"language": "spanish"}},
               "using": "bm25", "limit": 20}],
 "query": {"rrf": {"k": 60}}, "limit": 5, "with_payload": true}

Los vectores densos están abreviados; los tuyos tienen 1.024 valores. Indica el idioma: con "spanish", la consulta “vacación” encontró el documento de “vacaciones”; con "english" no encontró nada. bge-m3 también sabe producir vectores dispersos propios, pero el /api/embed de Ollama solo devuelve los densos.

Un reranker. La referencia de la API de Ollama no tiene ningún endpoint de rerank (comprobado el 15-11-2026), así que hace falta otro servidor. El nuestro es BAAI/bge-reranker-v2-m3 (Apache 2.0, multilingüe) sobre vLLM, que implementa las API de rerank de Jina y Cohere:

bash
curl -s localhost:8201/v1/rerank -H 'content-type: application/json' -d '{"model": "reranker", "top_n": 3,
  "query": "¿Cuánto me pagan por kilómetro si voy con mi coche?",
  "documents": ["Cada persona de la oficina tiene 23 días laborables de vacaciones al año.",
                "El kilometraje con coche propio se paga a 0,26 euros por kilómetro.",
                "Los martes son presenciales para todo el mundo."]}'
# "results":[{"index":1,...,"relevance_score":0.992},{"index":2,...,"relevance_score":0.0000164}, ...]

Pide 25 fragmentos a Qdrant, reordénalos y pasa los cinco mejores al prompt. El servidor de vLLM ya estaba funcionando; no lo montamos en esta guía.

Los fallos que te vas a encontrar

Todos estos mensajes los reprodujimos el 15-11-2026.

  • Wrong input: Vector dimension error: expected dim: 1024, got 768 (Qdrant, HTTP 400). Cambiaste a un modelo de 768 dimensiones y conservaste la colección. Crea una nueva.
  • Not found: Collection `nope` doesn't exist! (404). Preguntaste antes de indexar, o el nombre tiene una errata.
  • Wrong input: Collection `docs` already exists! (409). Una segunda llamada de creación. El script consulta antes /exists.
  • model "no-such-model" not found, try pulling it first (Ollama, 404). Lanza ollama pull con ese nombre.
  • the input length exceeds the context length (Ollama, 400, solo con truncate: false). Un fragmento es demasiado largo. Con las opciones por defecto, bge-m3 en nuestro Ollama 0.34.0 aceptó 2.048 tokens y rechazó 2.049, aunque el modelo declara 8.192. Enviar solo num_ctx no cambió nada; con "options": {"num_ctx": 8192, "num_batch": 8192} pasó una entrada de 3.002 tokens. No investigamos la causa.
  • Ningún error. Sin truncate: false, una entrada de 12.000 palabras volvió como un vector normal, hecho con sus primeros 2.048 tokens.

Lo que no te dice la ficha técnica

  • Acertar el documento no es responder. Incluso con el documento correcto entre los cinco primeros, el 7B dijo “No lo sé” de dos a cuatro veces de 60. El modelo lee cinco fragmentos, no cinco documentos.
  • Lo que está en una tabla cuesta encontrarlo. Una de las dos preguntas que más fallaron en las 11 ejecuciones de la prueba 1 (6 de 11 la dejaron fuera de los cinco primeros) fue “¿qué equipo me compro con 1.000 euros?”: la respuesta está en una fila de una tabla de hardware.
  • La comprobación de anclaje tiene puntos ciegos. Una respuesta que citaba su fuente casi palabra por palabra sacó 0.
  • La primera etapa pone el techo. En la prueba 2, el pasaje correcto estaba entre los 50 primeros candidatos en 52 de las 54 preguntas. Ningún reranker puede subir un pasaje que no llega a ver.
  • Nuestros conjuntos son más fáciles que tu carpeta. Texto limpio y preguntas de quien lo leyó. Mide la tuya.

Veredicto

  • Empieza con 1.000 a 2.000 caracteres, un 15 % de solape, los 5 primeros y solo búsqueda vectorial.
  • Escribe de 20 a 50 preguntas antes de ajustar nada. Sin ellas, cada cambio es una apuesta.
  • Añade un reranker o BM25 solo si tus preguntas enseñan una mejora. Las nuestras enseñaron una pequeña con el reranker y una pérdida con la búsqueda híbrida sobre texto legal.

Cuándo no hacerlo

Si tus documentos caben en el contexto del modelo (un puñado de políticas, un manual), sáltate la recuperación y pégalos. Si otras personas van a editar el flujo, la versión con n8n se entrega mejor. Si la respuesta exige sumar todas las filas de una hoja de cálculo, el RAG no es la herramienta: recupera pasajes, no calcula sobre todos.

Preguntas frecuentes

¿Necesito una GPU? Solo medimos en GPU. bge-m3 ocupó 0,66 GB cargado, así que la parte de embeddings pesa poco; la memoria la marca el modelo de chat. No tenemos tiempos en CPU que darte.

¿Hace falta una base de datos vectorial? A pequeña escala, no. La prueba 2 guardó sus 761 vectores en una matriz de numpy y cada búsqueda tardó una mediana de 7,9 ms. Qdrant se gana el sitio cuando quieres filtros, persistencia, actualizaciones y varios lectores.

¿El modelo puede inventar igualmente? Sí. El prompt le pide citar y el script imprime las fuentes para que compruebes. Eso baja el riesgo sin eliminarlo.

¿Mis datos salen de la máquina? Con este montaje, no: Ollama y Qdrant escuchan en localhost. No abras el puerto de Qdrant a la red sin ponerle una clave de API.

Próximos pasos

Trabaja con nosotros

Podemos hacer este análisis con tus documentos reales antes de recomendar hardware. Una llamada gratuita de 15 minutos basta para saber si tiene sentido en tu caso: reserva la llamada o mira cómo trabajamos en consultoría.

Diagrama
Compartir: LinkedIn X
Veredicto semanal

Recibe las guías nuevas antes que nadie

Suscríbete y te avisamos cuando publiquemos guías, plantillas y workflows nuevos. Un correo a la semana, sin spam.

Ya publicados: 101 guías y 25 plantillas. Todo gratis y sin registro.

Bonus: el kit de inicio de IA local en PDF al suscribirte
1x por semana Sin spam Cancela cuando quieras

Ver qué recibes