Pular para o conteúdo
LabS Atlas
Agentic AI
Entrar

Qdrant

Ir para notas que citam esta
atualizado há 25 diasEntre para perguntar ao Labinho sobre esta notaO Labinho é o assistente que responde com as notas e as sessões do LabS e mostra de onde tirou cada resposta.

Qdrant é um banco de dados vetorial que guarda os embeddings dos chunks de texto, junto com metadados, e responde buscas por proximidade semântica entre vetores.

É uma das implementações possíveis de banco vetorial e a base de conhecimento de protótipos de RAG feitos tanto em N8N quanto em código Python. Roda localmente via Docker, inclusive no mesmo docker compose que sobe o N8N e o Postgres, e tem um dashboard web próprio. Em Python, o acesso é pelo pacote qdrant-client; numa instalação local, o cliente precisa só da URL do serviço, lida de variável de ambiente, sem chave de API.

Coleções, pontos e payload

A coleção (collection) é o equivalente a uma tabela e precisa existir antes de qualquer inserção. Ela é criada com dois parâmetros: o tamanho do vetor e a métrica de distância. O tamanho tem de coincidir com o modelo de embedding: 3072 dimensões para o text-embedding-3-large da OpenAI, 1536 para o modelo menor da mesma família. O mesmo modelo usado para popular a coleção precisa ser usado nas consultas, senão a busca falha.

Um padrão útil é uma função que verifica se a coleção existe e, se não existir, a cria, chamada antes de qualquer extração. Sem ela, a primeira execução num container vazio falha ao tentar gravar.

A unidade de armazenamento é o ponto (point), formado por um id, um vetor e um payload. O id pode ser um UUID gerado na hora. O payload é livre e costuma guardar o nome do documento de origem e o texto do chunk. O motivo: o vetor serve para o Qdrant aproximar a pergunta dos trechos, mas um LLM não entende uma lista de números. O que vai para o modelo como contexto é o texto, e o nome do arquivo permite filtrar depois só os pontos de um documento. Os pontos são gravados por upsert, que insere ou atualiza.

Similaridade e leitura no dashboard

A métrica usual para texto é o cosseno, detalhada em Similaridade de Cosseno. No dashboard, cada ponto mostra o payload, o vetor e os vizinhos mais próximos com seu grau de similaridade: quanto mais perto de 1, mais parecidos os textos.

O painel exibe poucos vizinhos, como cinco, mas praticamente todos os pontos têm algum grau de proximidade com qualquer outro. Por isso toda consulta precisa de um limite de resultados relevantes, definido na etapa de recuperação.

Reprocessamento e dados duplicados

Rodar a ingestão duas vezes duplica a base

Carregar o mesmo PDF de novo numa coleção que não foi limpa insere os mesmos trechos outra vez. No dashboard, isso aparece como vizinhos com exatamente o mesmo texto do ponto consultado, e a busca passa a devolver cópias em vez de trechos complementares, o problema de Duplicação de Embeddings e Chunks.

Há algumas formas de evitar isso, da mais simples à mais robusta:

  • limpar a coleção antes de repetir testes com o mesmo documento;
  • usar o nome do arquivo como id, para que um novo upload substitua o anterior em vez de somar, o que um id aleatório não faz;
  • calcular um hash SHA-256 do conteúdo de cada PDF, registrar numa tabela os arquivos já processados e pular os que não mudaram;
  • num protótipo, desativar a chamada de carga depois da primeira execução.

O problema inverso também existe: um documento atualizado na pasta de origem só aparece no banco depois que a ingestão roda de novo.