Qdrant

1. Visão Geral

O componente Qdrant (qdrant) conecta o fluxo a um banco de dados vetorial Qdrant, usado para armazenar e buscar embeddings (vetores numéricos gerados a partir de texto, imagens, etc.). É a peça que guarda e consulta os vetores gerados, por exemplo, pelo componente Embedding.

Use quando o fluxo precisa gravar vetores para busca semântica (RAG, recomendação, similaridade) ou consultar vetores já armazenados. Só funciona como ação de saída.

2. Pré-requisitos

• Um servidor Qdrant acessível (host e porta gRPC).
• Uma coleção já criada (ou o próprio fluxo pode criá-la com a operação CREATE_COLLECTION).

3. Autenticação e Conexão

Campo	Obrigatório	Tipo	Descrição	Exemplo
host	Sim	Texto	Endereço do servidor Qdrant.	"qdrant.exemplo.com"
port	Sim	Número	Porta gRPC do servidor Qdrant.	6334
apiKey	Não	Texto	Chave de API do Qdrant, se exigida pelo servidor.	Uma chave de API
useTls	Não	Texto ("true"/"false")	Habilita conexão criptografada. Valor padrão: "false".	"true"

4. Configuração / Operações Suportadas

Campo	Obrigatório	Tipo	Descrição	Exemplo
operation	Sim	Texto	Uma das operações: CREATE_COLLECTION, DELETE_COLLECTION, LIST_COLLECTIONS, GET_COLLECTION, UPSERT, UPDATE_PAYLOAD, DELETE_POINTS, SEARCH, SCROLL, QUERY, GET_POINT.	"UPSERT"
collectionName	Sim, exceto em LIST_COLLECTIONS	Texto	Nome da coleção no Qdrant.	"documentos"

CREATE_COLLECTION

Campo	Obrigatório	Tipo	Descrição
vectorSize	Sim, se vectorsConfig não for usado	Número	Dimensão dos vetores armazenados na coleção.
distance	Não	Texto	Métrica de distância. Valor padrão: "Cosine".
vectorsConfig	Não	Texto (JSON)	Configuração avançada para múltiplos vetores nomeados na mesma coleção.

UPSERT — gravar/atualizar um ponto (vetor + dados)

Campo	Obrigatório	Tipo	Descrição
pointId	Sim	Texto (UUID)	Identificador único do ponto.
denseVector	Um dos três	Texto (JSON, lista de números)	O vetor numérico do ponto.
sparseVector	Um dos três	Texto (JSON)	Vetor esparso (índices + valores).
namedVectors	Um dos três	Texto (JSON)	Mapa de múltiplos vetores nomeados.
payload	Não	Texto (JSON)	Dados adicionais associados ao ponto (ex.: o texto original, metadados).

SEARCH — buscar pontos semelhantes a um vetor

Campo	Obrigatório	Tipo	Descrição
vector	Sim, se searchRequest não for usado	Texto (JSON, lista de números)	Vetor de referência para a busca.
limit	Não	Número	Quantidade máxima de resultados. Valor padrão: 10.
filter	Não	Texto (JSON)	Filtro adicional sobre os metadados dos pontos.

Demais operações

• DELETE_COLLECTION, GET_COLLECTION: apenas collectionName.
• UPDATE_PAYLOAD: pointId (obrigatório), payload (obrigatório).
• DELETE_POINTS, GET_POINT: pointId (obrigatório).
• SCROLL: limit (opcional), filter (opcional), offset (opcional).
• QUERY: queryRequest (obrigatório, JSON com regras avançadas de consulta).

5. Exemplos Práticos

Exemplo simples: gravar o embedding de um documento na coleção, junto com o texto original.

Entrada (embedding gerado por um passo anterior, com o componente Embedding):

{
  "documentoId": "doc-123",
  "embedding": [0.012, -0.045, 0.078],
  "textoOriginal": "Manual de instalação do produto X"
}

Configuração do componente:

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

Resposta:

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

Exemplo avançado: buscar os 5 documentos mais parecidos com um vetor de consulta.

Configuração do componente:

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

Resposta:

{
  "results": [
    { "id": "doc-123", "score": 0.94, "payload": { "texto": "Manual de instalação do produto X" } },
    { "id": "doc-456", "score": 0.87, "payload": { "texto": "Guia rápido do produto X" } }
  ],
  "count": 2
}

6. Erros Comuns e Troubleshooting

Erro / Sintoma	Causa provável	Como resolver
"host is required" / "port is required" / "operation is required"	Campos básicos de conexão ou operação não preenchidos.	Preencher host, port e operation.
"collectionName is required for [operação]"	O campo collectionName não foi preenchido para uma operação que exige.	Preencher collectionName com o nome da coleção.
"vectorSize or vectorsConfig is required for CREATE_COLLECTION"	Nenhum dos dois campos de configuração de vetor foi informado ao criar a coleção.	Informar vectorSize (uso simples) ou vectorsConfig (múltiplos vetores).
"At least one vector is required: 'denseVector', 'sparseVector', or 'namedVectors'"	A operação UPSERT foi usada sem nenhum vetor.	Preencher pelo menos um dos três campos de vetor.
"vector or searchRequest is required for SEARCH"	A operação SEARCH foi usada sem vetor de referência.	Preencher vector (uso simples) ou searchRequest (busca avançada).
"Point not found: [id]"	O ponto consultado não existe na coleção.	Confirmar se o pointId está correto e se o ponto já foi gravado.
"Failed to parse ... JSON: ..."	Algum campo JSON (vetor, filtro, payload) está malformado.	Revisar a sintaxe JSON do campo indicado no erro.