RAG con Qdrant: qué revisar cuando la búsqueda semántica falla

Preguntas a tu asistente por el límite de viáticos y responde citando un correo archivado de un departamento distinto. La colección de Qdrant aparece en verde, la indexación terminó sin errores y cada consulta vuelve en milisegundos. El problema no está en la respuesta de Qdrant, sino en las decisiones tomadas antes de enviarle la consulta: qué se indexó, con qué modelo y bajo qué filtros. Revisar esos cinco puntos ayuda a localizar el fallo antes de cambiar parámetros de la base de datos.

El modelo de embeddings decide qué puedes encontrar

La similitud solo significa algo dentro de un mismo espacio vectorial. Indexar los documentos con un modelo y formular las consultas con otro impide comparar vectores de forma válida: si las dimensiones coinciden, el coseno devuelve vecinos formalmente cercanos pero semánticamente irrelevantes; si no, Qdrant rechaza la consulta. Una alerta de latencia puede pasar por alto este fallo, porque la base puede responder rápido y con aspecto de resultado razonable.

El modelo elegido también condiciona el idioma y la calidad de la recuperación. all-MiniLM-L6-v2 produce vectores de 384 dimensiones y se entrenó principalmente en inglés; para comparar con un modelo multilingüe, multilingual-e5-large produce vectores de 1.024 dimensiones y exige los prefijos query: y passage: para consultas y passages en tareas de retrieval. El leaderboard MTEB de Hugging Face permite comparar candidatos por tarea de retrieval y por idioma antes de elegir uno.

Si un servicio intermedio regenera los embeddings con otro modelo, la colección queda mezclada en silencio. FastEmbed, del equipo de Qdrant, permite centralizar el modelo y trabajar con opciones orientadas a retrieval. Corregir esa divergencia antes de optimizar la búsqueda evita medir cambios que no tienen relación con la consulta.

Haz una comprobación rápida: ejecuta el mismo texto de prueba con ambos scripts, aplica el mismo prefijo y compara la dimensión y los primeros valores del vector. Si no coinciden, has localizado una causa frecuente de recuperación incorrecta; después podrás revisar la métrica de distancia sin arrastrar ese error.

La métrica de distancia se elige al crear la colección

Qdrant ofrece coseno, producto punto y distancia euclídea, y la métrica queda fijada al crear la colección. Cambiarla después obliga a recrear la colección y reindexar los datos, así que conviene decidirla junto con el modelo y no durante una incidencia. La equivalencia entre métricas depende de cómo normalice el modelo sus vectores.

Los modelos de embeddings de OpenAI normalizan sus vectores, de modo que el coseno y el producto punto producen el mismo orden. Esa equivalencia no se extiende a todos los modelos; los modelos de sentence-transformers se suelen usar con coseno.

from qdrant_client import QdrantClient, models

client = QdrantClient("http://localhost:6333")
client.create_collection(
    collection_name="docs",
    vectors_config=models.VectorParams(
        size=1536,  # Ajusta el valor a la dimensión de tu modelo
        distance=models.Distance.COSINE,
    ),
)

El puerto 6333 expone la API REST de Qdrant, así que puedes consultar la configuración directamente. Salvo que lo cambies al crear la colección, Qdrant inicializa HNSW con m=16 y ef_construct=100; HNSW es la estructura de búsqueda basada en grafos introducida por Malkov y Yashunin.

Para una puesta en marcha desde cero, el artículo RAG y búsqueda semántica con Qdrant: de la teoría a tu primera colección cubre ese proceso completo.

Consulta GET /collections/docs, contrasta el campo distance con la ficha del modelo y corrige cualquier incompatibilidad antes de reindexar. Con el modelo y la métrica alineados, el siguiente paso es decidir cómo separar los documentos en fragmentos.

El chunking decide si un embedding significa algo

El tamaño y los límites de cada fragmento determinan qué puede recuperar el embedding. Un bloque que concatena la introducción con el anexo representa ambos documentos sin identificar ninguno; uno demasiado corto pierde el contexto necesario para responder. El vector resultante se parece a la mezcla, no a una unidad recuperable.

Un punto de partida habitual son varios cientos de tokens por fragmento y un solapamiento controlado, aunque no existe una regla universal. Cuando el documento tiene estructura de cabeceras, tablas o listas, cortar por ella conserva unidades completas y deja la sección disponible para el payload. Para ver el diseño completo del recorrido, desde la ingesta hasta la respuesta, el artículo RAG y búsqueda semántica con Qdrant: el pipeline que encuentra ideas, no palabras lo desglosa con detalle.

Toma diez preguntas reales de tu buscador y recupera los chunks que deberían responderlas. Revisa si alguna frase quedó partida por un límite arbitrario o si una regla aparece separada de su contexto. Si el corte oculta la respuesta, cambia el tamaño o la delimitación; después podrás separar versiones mediante filtros de payload.

Los filtros de payload seleccionan la versión correcta

La búsqueda vectorial encuentra texto parecido, no texto vigente. Sin filtros, un RAG puede devolver la versión anterior de una política interna porque su redacción se parece más a la consulta que la del documento actual. Qdrant guarda los metadatos en el payload y permite filtrar por ellos dentro de la misma consulta.

El filtro de HNSW de Qdrant evalúa las condiciones durante el recorrido del grafo, en vez de traer candidatos y descartarlos después en la aplicación. Una condición como departamento = "finanzas" AND vigente = true reduce el conjunto elegible antes de devolver resultados. Crea payload indexes para los campos usados con frecuencia en filtros de coincidencia o rango.

Enumera tres campos que ahora tendrías que descartar a mano y conviértelos en filtros; añade sus payload indexes cuando corresponda. Guarda también el título y la sección en el payload para poder citar la fuente de cada respuesta. Una vez controlada la vigencia, el siguiente problema son los literales que la búsqueda densa no recupera de forma fiable.

La búsqueda híbrida mejora la recuperación de literales

Los embeddings densos capturan el significado de una frase, pero suelen ser poco fiables para literales como códigos de error, referencias de producto o números de expediente. ERR_40921 debe coincidir como cadena exacta; la similitud por sí sola no garantiza esa coincidencia. La búsqueda híbrida añade una vía explícita para esos casos.

Qdrant admite vectores densos y dispersos en la misma colección mediante vectores con nombre, y su Query API fusiona ambas listas con RRF o DBSF. El propio equipo de Qdrant mantiene BM42, un modelo disperso diseñado para este escenario híbrido.

Si tu interfaz recibe identificadores enviados mediante el buscador, enruta esas consultas por la vía híbrida y compara el recall antes y después con el mismo conjunto de preguntas. El ajuste debe recuperar los casos literales sin degradar los que ya resolvía la búsqueda densa. Para comprobar ambas cosas sin mezclar efectos, necesitas una evaluación con casos conocidos.

Mide con veinte preguntas antes de tocar nada

Sin un conjunto de evaluación, cada cambio del RAG es una moneda al aire. La versión mínima cabe en un CSV: veinte o treinta preguntas reales junto al chunk que debería recuperar cada una. Después de cada cambio, cuenta cuántos aciertos aparecen entre los cinco primeros resultados; ese ratio es tu recall@5 para esa lista.

El cálculo no requiere un servicio externo: basta con consultas contra la colección y una comparación de identificadores en un script. Cuando la latencia lo permita, subir hnsw_ef durante la búsqueda puede aumentar el recall a costa de más espera. Hazlo solo sobre una base estable; si la recuperación falla por datos, segmentación o filtros, el parámetro no resolverá la causa.

Cambia una sola variable por experimento —modelo, tamaño de chunk o parámetros de búsqueda— y vuelve a ejecutar la misma lista de preguntas. La comparación solo significa algo con el resto de variables congeladas.

El coste de recrear una colección depende del volumen indexado y de la configuración, así que no conviene asumir que siempre será barato. Reserva una hora esta semana, vuelca veinte preguntas reales en un CSV y anota el recall@5 de la colección tal como está. A partir de esa cifra, repite un solo ajuste y compara el resultado con la misma lista.