Qdrant

Qdrant guarda documentos en una colección de tu servidor Qdrant y busca en ella por significado, con filtros por los datos de cada documento. Si la colección no existe, la crea.

Una base de datos vectorial guarda textos de forma que se pueden buscar por su significado, no solo por palabras exactas. Así, un agente puede encontrar el párrafo de un manual que responde a una pregunta aunque esté escrito con otras palabras.

Cuándo usarlo

• Ya tienes un servidor Qdrant o una cuenta de Qdrant Cloud.
• Quieres filtrar las búsquedas por los datos de los documentos.
• Quieres empezar a guardar sin crear antes la colección.

Configuración

El campo Operation decide qué hace el componente, y según lo que elijas cambian los campos y las salidas:

• Add (por defecto): guarda en la base los documentos que recibe en Ingest Data.
• Search: busca los documentos más parecidos al texto de Search Query.
• Retriever: ofrece la base como buscador para que la use otro componente, por ejemplo un agente o una cadena de preguntas y respuestas.

Necesitas una credencial Qdrant API con la clave de tu Qdrant. Consulta Credenciales.

Campo	Qué hace
Credential (obligatorio)	La credencial Qdrant API con los datos de conexión.
Operation	Qué hace el componente: Add, Search o Retriever.
Ingest Data (obligatorio)	Con Add. Los documentos que se guardan, normalmente los que salen de un divisor de textos o de un cargador de archivos.
Search Query	Con Search. El texto que se busca. Si lo dejas vacío no se devuelve nada.
Embedding	El conector donde enchufas el componente que convierte los textos en números para compararlos por significado, como OpenAI Embeddings. Usa siempre el mismo para guardar y para buscar.
Collection Name (obligatorio)	La colección de Qdrant.
URL (obligatorio)	La dirección de tu servidor Qdrant.

Opciones avanzadas

Campo	Qué hace
Number of Results	Cuántos documentos devuelve cada búsqueda. Por defecto, 4.
Port	Puerto del servidor. Por defecto, 6333.
Timeout	Segundos de espera máxima por respuesta.
Distance Function	Cómo se mide el parecido: Cosine (por defecto), Euclidean o Dot Product.
Search Type	Cómo se busca: Similarity, Similarity with score threshold, MMR (Max Marginal Relevance). Similarity devuelve los más parecidos; con umbral, solo los que superan Search Score Threshold; MMR busca resultados parecidos pero variados entre sí.
Search Score Threshold	Puntuación mínima de parecido, solo con la búsqueda por umbral. Por defecto, 0.0.
Filter by Metadata	Busca solo entre los documentos cuyos datos cumplen unas condiciones, por ejemplo marca igual a Vellani. Funciona con Search, Retriever y en modo herramienta. Ver Filtrar por metadatos.

Filtrar por metadatos

Cada documento guarda, además de su texto, unos datos (sus metadatos): la marca, el tipo de documento, el mes… El filtro hace que la búsqueda mire solo los documentos cuyos datos cumplen unas condiciones. Se aplica igual a Results, a Retriever y cuando un agente usa el componente como herramienta.

Activa Filter by Metadata (en las opciones avanzadas) y elige Filter Mode:

• Manual: escribes las condiciones en el nodo. En Number of Conditions eliges cuántas filas quieres, y cada fila tiene:

  • Field: el dato que se mira, por ejemplo marca.
  • Operator: Equal (igual), NotEqual (distinto), GreaterThan, GreaterThanEqual, LessThan, LessThanEqual (mayor, mayor o igual, menor, menor o igual), In (uno de una lista separada por comas, como Q90, S80), NotIn (ninguno de la lista) y Contains (el texto o la lista contiene el valor).
  • Type: Text, Int (número entero), Number (con decimales) o Boolean (true o false).
  • Value: el valor con el que se compara. Si se deja vacío, esa fila no filtra.

  Combine Conditions decide si se tienen que cumplir todas (AND) o basta con una (OR).

• Dynamic: las condiciones llegan como JSON en Metadata Filter (JSON), desde otro componente o escritas por un agente:

  • {"marca": "Vellani"}: valor exacto.
  • {"modelo": ["Q90", "S80"]}: cualquiera de la lista.
  • {"año": {">=": 2024}, "estado": {"!=": "archivado"}}: con operadores =, !=, >, >=, <, <=, in, not in y contains.

  Si pones varios campos, se tienen que cumplir todos. Vacío, no filtra. Un JSON mal escrito da un error en lugar de buscar sin filtro.

Que lo rellene el agente. Con el componente en modo herramienta, activa el modo herramienta de Value (con Field y Operator fijos, por ejemplo modelo y Equal) o el de Metadata Filter (JSON). El agente escribe el valor cuando la pregunta lo pide («solo la máquina Q90») y lo deja vacío cuando no. Cuéntale en la descripción de la herramienta qué campos y valores hay.

Listas. Si un dato es una lista, como las etiquetas que escribe Metadata Tagger, Equal e In aciertan cuando alguno de sus elementos coincide, y Contains busca dentro de ellos.

En Qdrant los mayores y menores solo comparan números. En modo Dynamic, un texto suelto ({"ciudad": "Barcelona"}) encuentra los documentos cuyo dato contiene ese texto, como hasta ahora; para el valor exacto, escribe {"ciudad": {"=": "Barcelona"}}. Si Qdrant pide un índice para un campo, el componente lo crea solo. El antiguo operador Like sigue funcionando como Contains.

Ejemplo: solo los manuales de una marca

1. Al guardar, cada fragmento lleva sus datos, por ejemplo tipo: manual y marca: Vellani (los pone el cargador de archivos o Metadata Tagger).
2. En el nodo con Operation en Search, activa Filter by Metadata, deja Filter Mode en Manual y rellena la fila: Field marca, Operator Equal, Type Text, Value Vellani.
3. Busca «qué significa el error E07»: solo salen fragmentos de documentos de Vellani.

El mismo filtro en modo Dynamic es {"marca": "Vellani"}. Los nodos guardados antes conservan sus filtros; los nombres nuevos de los campos aparecen al actualizar el nodo.

En vídeo

Este vídeo muestra cómo un filtro por marca deja fuera los fragmentos de otras marcas, primero con una condición fija y después con un agente que rellena el valor.

Lo que ves en el vídeo:

1. Sin filtro, «¿Qué significa el error E07?» devuelve fragmentos de marcas distintas: el mismo código significa cosas diferentes en cada una.
2. Con una fila en modo Manual (Field marca, Operator Equal, Value Vellani), todos los resultados son de Vellani.
3. La lista de operadores, con In y Contains para las etiquetas de códigos, y cómo se combinan varias condiciones.
4. Un Agent con la base como herramienta, donde Condition 1: Value lo rellena la IA: en la llamada a la herramienta se ve filter_1_value: "Vellani" y la respuesta es el E07 de Vellani (caudalímetro bloqueado, pieza VL-1180).
5. El filtro funciona igual en FAISS, Chroma DB, PGVector, Neo4j y Elasticsearch.

Resultado

Las salidas dependen de Operation:

• Results: con Add y Search. Con Search, la lista de documentos encontrados, que puedes pasar a un prompt o a un agente.
• Vector Store: con Add. La base de datos, para conectarla a componentes que trabajan con una base vectorial.
• Retriever: con Retriever. El buscador, para conectarlo a componentes que piden un buscador.

En modo herramienta, un agente puede usar el componente para buscar por sí mismo. Consulta Tool Mode.

Ejemplo

Una cadena de hoteles guarda las reseñas de sus clientes en Qdrant.

1. Añade Qdrant con Operation en Search, la URL y la colección resenas.
2. Conecta el componente de embeddings con que se guardaron.
3. Activa Filter by Metadata para buscar solo reseñas de un hotel.

Componentes relacionados

• Recursive Character Text Splitter: corta los documentos en trozos antes de guardarlos.
• OpenAI Embeddings: convierte los textos para buscarlos por significado.
• FastEmbed Embeddings (Local): convierte los textos dentro de NappAI, sin clave ni coste por uso.

Ver también

• Bases vectoriales: en qué se diferencian FAISS, Chroma, Qdrant, PGVector y Neo4j, y cuál elegir.