Qdrant: la base vectorial de un RAG local

#¿Para qué sirve una base vectorial?

Un modelo de embedding convierte un texto en una lista de números —un vector— de manera que dos textos de significado similar generan dos vectores cercanos. Encontrar los pasajes pertinentes para una pregunta consiste entonces en buscar los vectores más cercanos al de la pregunta. Para mil pasajes, basta con un simple cálculo sobre todo el conjunto. Para un millón, se necesita una estructura de índice, y esa es la función de una base de datos vectorial: construir y mantener esa estructura, responder en unos pocos milisegundos en lugar de comparar cada vector uno por uno y seguir dando resultados correctos mientras el corpus continúa recibiendo nuevos documentos.

Este paso condiciona todo lo demás: un modelo excelente que recibe los pasajes equivocados responde mal, y ninguna instrucción en el prompt compensa una recuperación deficiente. Por esta razón, la elección de la base de datos vectorial, durante mucho tiempo tratada como un detalle de infraestructura intercambiable, merece el mismo cuidado que la elección del propio modelo de lenguaje.

#Lo que aporta Qdrant

El proyecto se describe a sí mismo como un motor de búsqueda y una base de datos vectorial «de alto rendimiento y a gran escala», diseñado para un filtrado amplio, lo que lo diferencia de las bibliotecas que se limitan a buscar el vecino más cercano sin condiciones. Está escrito en Rust, lo que sus autores presentan como la razón de su rapidez y fiabilidad bajo una carga elevada. En cuanto a la robustez operativa, el proyecto también documenta un registro de escritura anticipada (write-ahead logging) que garantiza la persistencia de los datos con confirmación de actualización, incluso en caso de corte del suministro eléctrico, así como métricas, telemetría y registros de auditoría para supervisar y depurar un despliegue en producción.

Un servidor autónomo

Un contenedor, una API HTTP y gRPC, clientes oficiales en Python, Go, Rust, JavaScript/TypeScript, .NET y Java. Funciona independientemente de tu aplicación, que puede reiniciarse sin perder nunca el índice construido.

Filtrado por payload

Cada vector lleva metadatos —autor, fecha, servicio, tipo de documento— que se usan para filtrar durante la búsqueda con cláusulas should, must y must_not, no después. Es la diferencia entre una búsqueda utilizable en una empresa y una demostración.

La cuantización de los vectores

Comprimir los vectores para reducir considerablemente la huella de memoria (4× con cuantización escalar, hasta 32× con cuantización binaria), a costa de una pérdida de precisión controlada y compensable.

Los vectores dispersos y los multivectores

Además de los vectores densos clásicos, Qdrant admite vectores dispersos para la búsqueda de texto completo y objetos con varios embeddings, útiles para modelos de interacción tardía como ColBERT.

Búsqueda híbrida

Combinar varios vectores en una misma consulta para aprovechar al mismo tiempo la comprensión semántica y la precisión por palabra clave, con un resultado fusionado mediante estrategias configurables como la fusión por rangos recíprocos (RRF) o la fusión de puntuaciones por distribución (DBSF).

Instantáneas y recuperación

Hacer una copia de seguridad de una colección y restaurarla en otro lugar, algo importante cuando reindexarla supondría horas de GPU.

Despliegue distribuido

Distribuir una colección entre varios nodos mediante sharding y replicación, con redimensionamiento sin interrupción del servicio — pertinente más allá de un uso estrictamente local, pero conviene conocer esta posibilidad si el proyecto crece, para no tener que reconstruirlo todo desde cero el día en que una sola máquina ya no sea suficiente.

#Arrancar localmente

La vía más rápida es el contenedor oficial, con un volumen para que los datos se conserven tras el reinicio. Una interfaz web integrada, descrita por el proyecto como «una forma visual de interactuar con tus datos y supervisar el estado de tu despliegue», permite después explorar las colecciones, gestionar los datos y consultar la API REST sin escribir una línea de código. Es la mejor herramienta de diagnóstico cuando una respuesta es incorrecta: se examina lo que realmente se ha recuperado, en lugar de intentar adivinarlo releyendo el código de recuperación.

docker run -p 6333:6333 -p 6334:6334 \
  -v "$(pwd)/qdrant_storage:/qdrant/storage" \
  qdrant/qdrant

El cliente de Python también puede funcionar sin ningún servidor: QdrantClient(":memory:") para una prueba desechable, o QdrantClient(path="chemin/vers/db") para un almacenamiento local persistente. Esto resulta muy útil para un prototipo o para pruebas automatizadas: el mismo código puede pasar después a usar el servidor cambiando una sola línea de conexión. Desde 2026, el proyecto documenta una segunda vía de integración, Qdrant Edge: una versión ligera diseñada para dispositivos con recursos limitados, que se ejecuta directamente en el proceso de la aplicación en lugar de utilizar una arquitectura cliente-servidor, con la posibilidad de sincronizarse con un servidor Qdrant completo.

#El mínimo en Python

1. 01
   Conectarse

   from qdrant_client import QdrantClient y, a continuación, client = QdrantClient(url="http://localhost:6333") para apuntar al contenedor iniciado anteriormente.
2. 02
   Crear una colección

   client.create_collection(collection_name="docs", vectors_config=VectorParams(size=1024, distance=Distance.COSINE)) — el tamaño debe coincidir exactamente con la dimensión de tu modelo de embedding.
3. 03
   Insertar puntos

   client.upsert(collection_name="docs", points=[PointStruct(id=1, vector=[...], payload={"service": "support"})]) asocia a cada vector un identificador y metadatos filtrables.
4. 04
   Consultar

   client.query_points(collection_name="docs", query=vecteur_question, limit=5).points devuelve los cinco pasajes más cercanos, con su puntuación y su payload.

#El filtrado por metadatos, la función que lamentamos haber descuidado.

En la práctica, una pregunta casi nunca se formula sobre todo el corpus. Se busca en los documentos de un servicio, posteriores a una fecha, de un tipo determinado o accesibles al usuario que plantea la pregunta. Qdrant aplica estas condiciones durante la búsqueda vectorial, con una amplia variedad de filtros —coincidencia de palabras clave, búsqueda de texto completo, intervalos numéricos y geolocalización— combinados mediante las cláusulas lógicas should, must y must_not. Así se obtiene siempre el número adecuado de resultados pertinentes, mientras que un filtrado posterior puede dejarte sin ninguno.

El control de acceso merece una mención aparte: si varias personas consultan el mismo índice, el filtro de permisos impide que un modelo cite a una persona un documento que esa persona no tiene derecho a leer. Ninguna instrucción del prompt sustituye a este filtro, e implementarlo en la base de datos en lugar de en el código de la aplicación evita que un nuevo punto de acceso a la misma colección olvide volver a aplicarlo.

#Caber en memoria: la cuantización de los vectores

La práctica documentada consiste en buscar en los vectores comprimidos y luego reordenar (rescoring) los mejores candidatos con los vectores originales. Qdrant ofrece un parámetro de sobremuestreo (oversampling) para ajustar este equilibrio: con un valor de 2,4 y un límite de 100 resultados, se preseleccionan 240 candidatos en el índice cuantizado antes del reordenamiento final. Se conserva la mayor parte de la precisión al reducir el uso de memoria a una cuarta parte o menos, lo que, en una máquina que también aloja un modelo, no es un lujo. La documentación oficial también señala una aceleración de hasta 40 veces con la cuantización binaria respecto a los vectores originales, una cifra que conviene verificar con tu propio conjunto de datos en lugar de darla por sentada. El proyecto resume todas estas opciones de compresión, combinadas con el almacenamiento en disco, anunciando una reducción del uso de memoria de hasta el 97 %: un orden de magnitud que explica por qué la cuantización se presenta como una funcionalidad central y no como un ajuste marginal.

#Qdrant u otra

La pregunta que debes plantearte no es «cuál es la mejor base de datos vectorial», sino «qué necesita mi proyecto hoy». Un script de prueba no necesita más que una biblioteca en memoria. A una aplicación empresarial que ya consulta PostgreSQL le conviene añadirle una extensión vectorial en lugar de otro servicio. Qdrant se convierte en la opción adecuada precisamente cuando coinciden varias de estas necesidades: un servicio compartido por varias aplicaciones, un filtrado preciso de los metadatos, un corpus que sigue creciendo y el deseo de no tener que reescribir por tu cuenta la persistencia o las instantáneas. Revisar periódicamente esta elección, en lugar de fijarla en el primer prototipo, evita tanto complicar en exceso la arquitectura de un proyecto modesto como dimensionar por debajo de sus necesidades uno que ha acabado creciendo.

• Un RAG local completo, desde la ingestión hasta la respuesta
• Elegir un modelo de embedding para el francés
• Añadir un reranker para mejorar la relevancia
• pgvector: cuando PostgreSQL basta
• El kit RAG local QuelLLM
• Fuente: repositorio oficial Qdrant en GitHub
• Fuente: documentación oficial de la cuantización
• Fuente: inicio rápido de Qdrant en Python

#FAQ