Qdrant

1. Visión General

El componente Qdrant (qdrant) conecta el flujo a una base de datos vectorial Qdrant, usada para almacenar y buscar embeddings (vectores numéricos generados a partir de texto, imágenes, etc.). Es la pieza que guarda y consulta los vectores generados, por ejemplo, por el componente Embedding.

Úsalo cuando el flujo necesita grabar vectores para búsqueda semántica (RAG, recomendación, similitud) o consultar vectores ya almacenados. Solo funciona como acción de salida.

2. Prerrequisitos

• Un servidor Qdrant accesible (host y puerto gRPC).
• Una colección ya creada (o el propio flujo puede crearla con la operación CREATE_COLLECTION).

3. Autenticación y Conexión

Campo	Obligatorio	Tipo	Descripción	Ejemplo
host	Sí	Texto	Dirección del servidor Qdrant.	"qdrant.ejemplo.com"
port	Sí	Número	Puerto gRPC del servidor Qdrant.	6334
apiKey	No	Texto	Clave de API de Qdrant, si el servidor la exige.	Una clave de API
useTls	No	Texto ("true"/"false")	Habilita la conexión cifrada. Valor por defecto: "false".	"true"

4. Configuración / Operaciones Soportadas

Campo	Obligatorio	Tipo	Descripción	Ejemplo
operation	Sí	Texto	Una de las operaciones: CREATE_COLLECTION, DELETE_COLLECTION, LIST_COLLECTIONS, GET_COLLECTION, UPSERT, UPDATE_PAYLOAD, DELETE_POINTS, SEARCH, SCROLL, QUERY, GET_POINT.	"UPSERT"
collectionName	Sí, excepto en LIST_COLLECTIONS	Texto	Nombre de la colección en Qdrant.	"documentos"

CREATE_COLLECTION

Campo	Obligatorio	Tipo	Descripción
vectorSize	Sí, si no se usa vectorsConfig	Número	Dimensión de los vectores almacenados en la colección.
distance	No	Texto	Métrica de distancia. Valor por defecto: "Cosine".
vectorsConfig	No	Texto (JSON)	Configuración avanzada para múltiples vectores con nombre en la misma colección.

UPSERT — grabar/actualizar un punto (vector + datos)

Campo	Obligatorio	Tipo	Descripción
pointId	Sí	Texto (UUID)	Identificador único del punto.
denseVector	Uno de los tres	Texto (JSON, lista de números)	El vector numérico del punto.
sparseVector	Uno de los tres	Texto (JSON)	Vector disperso (índices + valores).
namedVectors	Uno de los tres	Texto (JSON)	Mapa de múltiples vectores con nombre.
payload	No	Texto (JSON)	Datos adicionales asociados al punto (ej.: el texto original, metadatos).

SEARCH — buscar puntos similares a un vector

Campo	Obligatorio	Tipo	Descripción
vector	Sí, si no se usa searchRequest	Texto (JSON, lista de números)	Vector de referencia para la búsqueda.
limit	No	Número	Cantidad máxima de resultados. Valor por defecto: 10.
filter	No	Texto (JSON)	Filtro adicional sobre los metadatos de los puntos.

Demás operaciones

• DELETE_COLLECTION, GET_COLLECTION: solo collectionName.
• UPDATE_PAYLOAD: pointId (obligatorio), payload (obligatorio).
• DELETE_POINTS, GET_POINT: pointId (obligatorio).
• SCROLL: limit (opcional), filter (opcional), offset (opcional).
• QUERY: queryRequest (obligatorio, JSON con reglas avanzadas de consulta).

5. Ejemplos Prácticos

Ejemplo simple: grabar el embedding de un documento en la colección, junto con el texto original.

Entrada (embedding generado por un paso anterior, con el componente Embedding):

{
  "documentoId": "doc-123",
  "embedding": [0.012, -0.045, 0.078],
  "textoOriginal": "Manual de instalación del producto X"
}

Configuración del componente:

{
  "componentName": "qdrant",
  "configurations": {
    "host": "qdrant.ejemplo.com",
    "port": "6334",
    "apiKey": "{$.secrets.qdrantApiKey}",
    "operation": "UPSERT",
    "collectionName": "documentos",
    "pointId": "{$.body.documentoId}",
    "denseVector": "{$.body.embedding}",
    "payload": "{\"texto\": \"{$.body.textoOriginal}\"}"
  }
}

Respuesta:

{
  "status": "completed",
  "pointId": "doc-123"
}

Ejemplo avanzado: buscar los 5 documentos más parecidos a un vector de consulta.

Configuración del componente:

{
  "componentName": "qdrant",
  "configurations": {
    "host": "qdrant.ejemplo.com",
    "port": "6334",
    "apiKey": "{$.secrets.qdrantApiKey}",
    "operation": "SEARCH",
    "collectionName": "documentos",
    "vector": "{$.body.embeddingConsulta}",
    "limit": "5"
  }
}

Respuesta:

{
  "results": [
    { "id": "doc-123", "score": 0.94, "payload": { "texto": "Manual de instalación del producto X" } },
    { "id": "doc-456", "score": 0.87, "payload": { "texto": "Guía rápida del producto X" } }
  ],
  "count": 2
}

6. Errores Comunes y Troubleshooting

Error / Síntoma	Causa probable	Cómo resolverlo
"host is required" / "port is required" / "operation is required"	Campos básicos de conexión u operación no completados.	Completar host, port y operation.
"collectionName is required for [operación]"	El campo collectionName no fue completado para una operación que lo exige.	Completar collectionName con el nombre de la colección.
"vectorSize or vectorsConfig is required for CREATE_COLLECTION"	No se informó ninguno de los dos campos de configuración de vector al crear la colección.	Informar vectorSize (uso simple) o vectorsConfig (múltiples vectores).
"At least one vector is required: 'denseVector', 'sparseVector', or 'namedVectors'"	Se usó la operación UPSERT sin ningún vector.	Completar al menos uno de los tres campos de vector.
"vector or searchRequest is required for SEARCH"	Se usó la operación SEARCH sin vector de referencia.	Completar vector (uso simple) o searchRequest (búsqueda avanzada).
"Point not found: [id]"	El punto consultado no existe en la colección.	Confirmar que el pointId sea correcto y que el punto ya haya sido grabado.
"Failed to parse ... JSON: ..."	Algún campo JSON (vector, filtro, payload) está malformado.	Revisar la sintaxis JSON del campo indicado en el error.