Qdrant: un motor vectorial dedicado

Cuando la recuperación empieza a doler, el síntoma rara vez es solo "la búsqueda va lenta". Es una consulta filtrada que antes tomaba milisegundos y ahora escanea, un corpus que ya no entra cómodo en la misma base que tu tráfico OLTP, o una factura de memoria que sube más rápido que el valor de los resultados. Qdrant responde a una forma muy concreta de ese dolor: un motor vectorial dedicado que puedes auto-hospedar, escrito en Rust, que mantiene la búsqueda filtrada rápida a escala y te deja cambiar recall por memoria de forma deliberada. Vas a terminar sabiendo exactamente cuándo justifica el segundo servicio que te cuesta, cómo levantarlo y consultarlo, y las dos o tres trampas de recall que, sin avisar, dejan tus resultados incorrectos en lugar de solo lentos.

01 · Qué es

Qdrant es una base de datos vectorial hecha para una sola tarea: guardar vectores de alta dimensión y encontrar rápido los vecinos más cercanos de un vector de consulta, con filtrado. No es una extensión de Postgres ni una base de datos de propósito general. Corre como un solo contenedor, expone una API REST en el puerto 6333 y una API gRPC en el 6334, y guarda sus datos en un volumen que tú montas.

Tres conceptos cubren casi todo lo que vas a hacer:

• Colecciones, la unidad de almacenamiento, como una tabla. Una colección fija de entrada la dimensión del vector y la métrica de distancia (Cosine, Dot o Euclid).
• Puntos, un punto es un registro: un id, el vector en sí y un payload (metadatos JSON arbitrarios: tenant, estado, idioma, timestamps, lo que sea por lo que filtres).
• Filtros, condiciones booleanas sobre el payload («must», «should», «must_not») que se aplican durante el recorrido del índice, no después.

Ese último punto es la razón de fondo para elegir Qdrant en vez de una columna vectorial añadida a la fuerza. El filtrado vive dentro de la ruta de búsqueda, no alrededor de ella.

02 · Por qué importan los payloads filtrables

La forma ingenua de hacer "documentos similares, pero solo los publicados y en español" es un post-filtro: le pides al índice los top-k vectores más cercanos y luego descartas los que no cumplen. Eso sirve hasta que el filtro es selectivo. Si solo el 2% de tu corpus está publicado y en español, esos top-k más cercanos podrían tener cero coincidencias, así que pides más, y más, y la consulta se degrada hasta quedar muy cerca de un escaneo. El recall se desploma o la latencia se dispara: elige uno.

Qdrant mete el filtro dentro del recorrido HNSW. A medida que recorre el grafo, solo considera puntos cuyo payload cumple el filtro, y mantiene índices de payload para que esas comprobaciones salgan baratas. El resultado es que una consulta muy filtrada se mantiene rápida y correcta, que es justo el caso donde el post-filtrado del lado de Postgres se cae a pedazos.

Esta es la función que debería guiar la decisión. Si tu recuperación es mayormente "busca similares, sin filtro", muchos motores sirven y pgvector es el más barato. Si tu recuperación es "busca similares dentro de este subconjunto", y ese subconjunto es selectivo, filtrar durante el recorrido bien vale un servicio dedicado.

# Un contenedor, REST en 6333, gRPC en 6334. Monta un volumen o pierdes los datos.
docker run -p 6333:6333 -p 6334:6334 \
  -v "$HOME/qdrant_storage:/qdrant/storage" \
  qdrant/qdrant

03 · Quickstart: una colección que sí usarías en serio

Crea una colección con la dimensión y la métrica correctas, agrega un índice de payload sobre el campo por el que filtras y luego haz upsert de los puntos. El índice de payload es la parte que la gente se salta: sin él, tu filtro es correcto pero lento.

import { QdrantClient } from "@qdrant/js-client-rest"

const client = new QdrantClient({
  url: "http://localhost:6333",
  apiKey: process.env.QDRANT_API_KEY, // pon una. ver sección 05.
})

// 1) colección: vectores de 1536 dims, distancia coseno
await client.createCollection("docs", {
  vectors: { size: 1536, distance: "Cosine" },
})

// 2) índice de payload para que los filtros sean rápidos, no solo correctos
await client.createPayloadIndex("docs", {
  field_name: "lang",
  field_schema: "keyword",
})

// 3) upsert de puntos (id + vector + payload)
await client.upsert("docs", {
  points: [
    { id: 1, vector: docVec, payload: { lang: "es", status: "published" } },
  ],
})

// 4) búsqueda filtrada: docs similares que estén publicados Y en español
const hits = await client.search("docs", {
  vector: queryVec,
  filter: {
    must: [
      { key: "lang", match: { value: "es" } },
      { key: "status", match: { value: "published" } },
    ],
  },
  limit: 5,
})

Algunos hábitos que conviene agarrar desde temprano:

1. Crea índices de payload para cada campo por el que filtres. Un filtro sin índice de payload igual devuelve la respuesta correcta, solo que lento, y lo lento es el modo de falla que se esconde hasta que crece el tráfico.
2. Agrupa tus upserts en lotes. Insertar los puntos de uno en uno, un request por cada uno, es la razón más común de que un backfill tarde horas en vez de minutos.
3. Prefiere gRPC para las rutas de lectura con QPS alto. REST sirve para el setup y la administración; gRPC baja notablemente el overhead por request bajo carga.

04 · Cuantización: recuperar memoria

HNSW mantiene los vectores en memoria para ir rápido, y los vectores en precisión completa salen caros. Un millón de vectores float32 de 1536 dims son unos 6 GB solo en los vectores crudos, antes de contar el grafo. En un solo VPS eso se acumula rápido. La cuantización es la palanca de Qdrant para esto:

• Cuantización escalar guarda cada dimensión como un int8 en lugar de un float32: ocupa unas 4x menos, con una pérdida de recall pequeña y por lo general aceptable.
• Cuantización binaria guarda cada dimensión como un solo bit: hasta ~32x menos y muchísimo más rápida, pero con un costo de recall real que depende muchísimo de tu modelo de embeddings y de tus datos.

Lo que vuelve usable la cuantización binaria es el rescoring: Qdrant usa los vectores comprimidos para armar rápido un conjunto generoso de candidatos y luego los re-ordena contra los vectores en precisión completa (que guarda en disco) para recuperar exactitud. Con rescoring activado y un factor de oversampling, la cuantización binaria puede sostener el recall sorprendentemente bien, pero "sorprendentemente bien" no es "siempre", y la única forma de saberlo es medirlo con tus propios datos.

await client.createCollection("docs_bq", {
  vectors: { size: 1536, distance: "Cosine" },
  quantization_config: {
    binary: { always_ram: true },
  },
})

// en la consulta: oversample y luego rescoring contra los vectores completos
const hits = await client.search("docs_bq", {
  vector: queryVec,
  limit: 10,
  params: {
    quantization: { rescore: true, oversampling: 2.0 },
  },
})

05 · Cuándo recurrir a él (y cuándo no)

Elige Qdrant cuando al menos una de estas sea cierta y la hayas medido:

• Escala. Pasaste lo que Postgres indexa con comodidad: decenas de millones de vectores y subiendo.
• Latencia bajo carga. Necesitas ANN filtrado con QPS alto y metas de p99 exigentes, y la búsqueda vectorial le pelea recursos al OLTP en el mismo Postgres.
• Recuperación con muchos filtros. Los filtros de payload selectivos son el centro de tus consultas, y el post-filtrado te está arruinando el recall o la latencia.
• Presión de memoria. Necesitas cuantización con rescoring para que un corpus grande quepa en la RAM que de verdad tienes.

Quédate con pgvector cuando andes por debajo de unos pocos millones de vectores y ya uses Postgres. Una sola base, un solo backup, un solo conjunto de transacciones, filtros y foreign keys y row-level security todo en la misma consulta: eso es mucha simplicidad operativa para regalarla. Elige la opción aburrida hasta que un benchmark con datos reales diga que ya no da abasto.

06 · Concesiones, sin rodeos

Qdrant es excelente en lo que hace, y lo que hace es bien acotado. No es tu base de datos principal: no hay joins, no hay transacciones entre colecciones, no hay integridad relacional. Los embeddings viven en Qdrant; las filas que describen siguen viviendo en Postgres, lo que significa que ahora cargas con la consistencia entre ambos: una ruta de sincronización, un plan de reindexado para cuando cambies de modelo de embeddings y otro para los borrados. Ese acoplamiento es el costo real de un motor dedicado, y por eso el argumento de tenerlo todo junto en pgvector pesa tanto por debajo de cierta escala.

La otra nota honesta es la gravedad operativa. "Un contenedor" es cierto el día uno. Para el mes tres ya tienes snapshots que programar, memoria que vigilar, upgrades de versión que probar y una config de cuantización que afinaste para un corpus que desde entonces se movió. Nada de esto es difícil, pero ahora es tuyo, y es trabajo que la opción aburrida nunca te pidió. Adopta Qdrant cuando la ganancia medida supere ese impuesto continuo, y ni un día antes.

Si estás chocando contra escala real, filtrado pesado o muros de memoria, Qdrant es una de las respuestas auto-hospedables más limpias que hay, y su núcleo en Rust hace que se mantenga rápido y predecible bajo carga. Pero es un salto que te ganas, no un default. Pásate a él cuando tengas evidencia de que la opción aburrida ya no da abasto; entonces mide el recall con tus propios datos antes de confiar en la cuantización, asegura la API y programa los snapshots desde el día uno.