Qdrant: a base vetorial de um RAG local

#Para que serve uma base vetorial

Um modelo de embedding converte um texto em uma lista de números — um vetor — de forma que dois textos com significados próximos gerem dois vetores próximos. Encontrar as passagens relevantes para uma pergunta equivale, então, a buscar os vetores mais próximos do vetor da pergunta. Para mil passagens, um simples cálculo sobre o conjunto inteiro é suficiente. Para um milhão, é necessária uma estrutura de índice, e esse é o trabalho de uma base vetorial: construir e manter essa estrutura, responder em alguns milissegundos em vez de comparar cada vetor um por um e continuar funcionando corretamente enquanto o corpus continua recebendo novos documentos.

Esta etapa determina todo o resto: um modelo excelente que recebe os trechos errados responde mal, e nenhuma instrução no prompt compensa uma recuperação falha. Por isso, a escolha do banco de dados vetorial, por muito tempo tratada como um detalhe de infraestrutura intercambiável, merece o mesmo cuidado que a escolha do próprio modelo de linguagem.

#O que o Qdrant oferece

O projeto se descreve como um mecanismo de busca e um banco de dados vetorial de “alto desempenho, em grande escala”, projetado para filtragem ampla — o que o diferencia das bibliotecas que apenas buscam o vizinho mais próximo sem condições. É escrito em Rust, o que seus autores apresentam como a razão de sua velocidade e confiabilidade sob carga elevada. No que diz respeito à robustez operacional, o projeto também documenta um registro antecipado de escrita (write-ahead logging) que garante a persistência dos dados com confirmação de atualização, mesmo em caso de queda de energia, além de métricas, telemetria e logs de auditoria para monitorar e depurar uma implantação em produção.

Um servidor autônomo

Um contêiner, uma API HTTP e gRPC, clientes oficiais em Python, Go, Rust, JavaScript/TypeScript, .NET e Java. Ele funciona independentemente da sua aplicação, que pode ser reiniciada sem nunca perder o índice construído.

Filtragem por payload

Cada vetor contém metadados — autor, data, serviço, tipo de documento — usados para filtrar durante a busca com cláusulas should, must e must_not, e não depois. É a diferença entre uma busca utilizável em uma empresa e uma demonstração.

Quantização dos vetores

Comprimir os vetores para reduzir o consumo de memória por um fator significativo (4× na quantização escalar, até 32× na binária), ao custo de uma perda de precisão controlada e compensável.

Vetores esparsos e multivetores

Além dos vetores densos clássicos, o Qdrant suporta vetores esparsos para busca de texto completo e objetos com múltiplos embeddings, úteis para modelos de interação tardia como ColBERT.

A pesquisa híbrida

Combinar vários vetores em uma mesma consulta para aproveitar ao mesmo tempo a compreensão semântica e a precisão por palavra-chave, com um resultado combinado por estratégias configuráveis, como a fusão de classificações recíprocas (RRF) ou a fusão de pontuações por distribuição (DBSF).

Instantâneos e recuperação

Salvar uma coleção e restaurá-la em outro lugar, o que importa no dia em que reindexar custaria horas de GPU.

Implantação distribuída

Distribuir uma coleção entre vários nós por sharding e replicação, com redimensionamento sem interrupção do serviço — relevante para além do uso estritamente local, mas bom saber caso o projeto cresça, para não precisar reconstruir tudo do zero no dia em que uma única máquina deixar de ser suficiente.

#Iniciar localmente

O caminho mais curto é usar o contêiner oficial, com um volume para que os dados sejam preservados após o reinício. Uma interface web integrada, descrita pelo projeto como “um meio visual de interagir com seus dados e monitorar a saúde da sua implantação”, permite então explorar as coleções, gerenciar os dados e consultar a API REST sem escrever uma linha de código — é a melhor ferramenta de diagnóstico quando uma resposta é ruim: você verifica o que realmente foi recuperado, em vez de tentar adivinhar relendo o código de recuperação.

docker run -p 6333:6333 -p 6334:6334 \
  -v "$(pwd)/qdrant_storage:/qdrant/storage" \
  qdrant/qdrant

O cliente Python também pode funcionar sem nenhum servidor: QdrantClient(":memory:") para um teste descartável, ou QdrantClient(path="chemin/vers/db") para armazenamento local persistente. Isso é valioso para um protótipo ou testes automatizados, pois o mesmo código pode depois usar o servidor com a alteração de uma única linha de conexão. Desde 2026, o projeto documenta uma segunda via de integração, Qdrant Edge: uma versão leve concebida para dispositivos com recursos limitados, que é executada diretamente no processo da aplicação, em vez de usar uma arquitetura cliente-servidor, com possibilidade de sincronização com um servidor Qdrant completo.

#Mínimo em Python

1. 01
   Conectar-se

   from qdrant_client import QdrantClient; depois, client = QdrantClient(url="http://localhost:6333") aponta para o contêiner iniciado acima.
2. 02
   Criar uma coleção

   client.create_collection(collection_name="docs", vectors_config=VectorParams(size=1024, distance=Distance.COSINE)) — o tamanho deve corresponder exatamente à dimensão do seu modelo de embedding.
3. 03
   Inserir pontos

   client.upsert(collection_name="docs", points=[PointStruct(id=1, vector=[...], payload={"service": "support"})]) associa a cada vetor um identificador e metadados filtráveis.
4. 04
   Consultar

   client.query_points(collection_name="docs", query=vecteur_question, limit=5).points retorna os cinco trechos mais próximos, com seus scores e seu payload.

#Filtragem por metadados, a função que lamentamos ter ignorado

Na prática, uma pergunta quase nunca é feita sobre todo o corpus. A busca é feita nos documentos de um serviço, posteriores a uma data, de um tipo específico ou acessíveis ao usuário que faz a pergunta. O Qdrant aplica essas condições durante a busca vetorial, com um conjunto rico de filtros — correspondência de palavra-chave, busca de texto completo, intervalos numéricos, geolocalização — combinados por cláusulas lógicas should, must e must_not. Isso sempre fornece a quantidade correta de resultados relevantes, enquanto uma filtragem feita depois pode eliminar todos os resultados.

O controle de acesso merece uma menção especial: se várias pessoas consultam o mesmo índice, o filtro de permissões é o que impede que um modelo cite a alguém um documento que essa pessoa não tem direito de ler. Nenhuma instrução de prompt substitui esse filtro, e implementá-lo no nível do banco de dados, em vez de no código da aplicação, evita que um novo ponto de acesso à mesma coleção esqueça de reaplicá-lo.

#Caber na memória: a quantização dos vetores

A prática documentada consiste em buscar nos vetores comprimidos e depois reordenar (rescoring) os melhores candidatos com os vetores originais — o Qdrant oferece um parâmetro de superamostragem (oversampling) para ajustar esse equilíbrio: com o parâmetro em 2,4 e um limite de 100 resultados, 240 candidatos são pré-selecionados no índice quantizado antes da reordenação final. Preserva-se a maior parte da precisão dividindo o uso de memória por quatro ou mais, o que, em uma máquina que também hospeda um modelo, não é um luxo. A documentação oficial também afirma que a quantização binária pode proporcionar uma aceleração de até 40 vezes em comparação com os vetores originais, um número a verificar no seu próprio conjunto de dados em vez de tomá-lo como garantido. O projeto resume todas essas opções de compressão, combinadas com o armazenamento em disco, anunciando uma redução do uso de memória que pode chegar a 97% — uma ordem de grandeza que explica por que a quantização é apresentada como uma funcionalidade central, e não como um ajuste marginal.

#Qdrant ou outra

A pergunta a se fazer não é “qual é o melhor banco de dados vetorial”, mas “o que meu projeto exige hoje”. Um script de teste não precisa de nada além de uma biblioteca em memória. Uma aplicação empresarial que já consulta o PostgreSQL se beneficia de adicionar uma extensão vetorial a ele, em vez de acrescentar mais um serviço. O Qdrant se torna a escolha certa precisamente quando várias dessas necessidades se somam ao mesmo tempo: um serviço compartilhado por várias aplicações, filtragem detalhada por metadados, um corpus que continua crescendo e a vontade de não reescrever por conta própria a persistência ou os snapshots. Reavaliar regularmente essa escolha, em vez de fixá-la no primeiro protótipo, evita tanto criar uma arquitetura excessivamente complexa para um projeto modesto quanto subdimensionar um projeto que acabou crescendo.

• Um RAG local completo, desde a ingestão até a resposta
• Escolher um modelo de embedding para o francês
• Adicionar um reranker para melhorar a relevância
• pgvector: quando o PostgreSQL é suficiente
• O kit RAG local QuelLLM
• Fonte: repositório oficial Qdrant no GitHub
• Fonte: documentação oficial de quantização
• Fonte: início rápido com Qdrant em Python

#FAQ