Skip to content

artubss/SKILLS-CLAUDE-CODE / skills/skills/ai-research/rag-qdrant

qdrant-vector-search

Verified

Mecanismo de busca de similaridade vetorial de alto desempenho para RAG e busca semântica. Use ao construir sistemas RAG em produção que exigem busca de vizinhos mais próximos rápida, busca híbrida com filtragem ou armazenamento vetorial escalável com desempenho impulsionado por Rust.

Qdrant - Mecanismo de Busca de Similaridade Vetorial

Banco de dados vetorial de alto desempenho escrito em Rust para RAG em produção e busca semântica.

Quando usar Qdrant

Use Qdrant quando:

  • Construir sistemas RAG em produção que exigem baixa latência
  • Precisar de busca híbrida (vetores + filtragem de metadados)
  • Exigir dimensionamento horizontal com sharding/replicação
  • Quiser deploy on-premise com controle total de dados
  • Precisar armazenar múltiplos vetores por registro (denso + esparso)
  • Construir sistemas de recomendação em tempo real

Recursos principais:

  • Impulsionado por Rust: Segurança de memória, alto desempenho
  • Filtragem avançada: Filtrar por qualquer campo de payload durante a busca
  • Múltiplos vetores: Denso, esparso, multi-denso por ponto
  • Quantização: Escalar, produto, binária para eficiência de memória
  • Distribuído: Consenso Raft, sharding, replicação
  • REST + gRPC: Ambas as APIs com paridade completa de recursos

Use alternativas:

  • Chroma: Configuração mais simples, casos de uso incorporados
  • FAISS: Velocidade máxima em bruto, pesquisa/processamento em lote
  • Pinecone: Totalmente gerenciado, sem operações preferidas
  • Weaviate: Preferência por GraphQL, vetorizadores integrados

Início rápido

Instalação

# Cliente Python
pip install qdrant-client

# Docker (recomendado para desenvolvimento)
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

# Docker com armazenamento persistente
docker run -p 6333:6333 -p 6334:6334 \
    -v $(pwd)/qdrant_storage:/qdrant/storage \
    qdrant/qdrant

Uso básico

from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams, PointStruct

# Conectar ao Qdrant
client = QdrantClient(host="localhost", port=6333)

# Criar coleção
client.create_collection(
    collection_name="documents",
    vectors_config=VectorParams(size=384, distance=Distance.COSINE)
)

# Inserir vetores com payload
client.upsert(
    collection_name="documents",
    points=[
        PointStruct(
            id=1,
            vector=[0.1, 0.2, ...],  # vetor de 384 dimensões
            payload={"title": "Doc 1", "category": "tech"}
        ),
        PointStruct(
            id=2,
            vector=[0.3, 0.4, ...],
            payload={"title": "Doc 2", "category": "science"}
        )
    ]
)

# Buscar com filtragem
results = client.search(
    collection_name="documents",
    query_vector=[0.15, 0.25, ...],
    query_filter={
        "must": [{"key": "category", "match": {"value": "tech"}}]
    },
    limit=10
)

for point in results:
    print(f"ID: {point.id}, Score: {point.score}, Payload: {point.payload}")

Conceitos fundamentais

Points - Unidade básica de dados

from qdrant_client.models import PointStruct

# Point = ID + Vector(s) + Payload
point = PointStruct(
    id=123,                              # Integer ou string UUID
    vector=[0.1, 0.2, 0.3, ...],        # Vetor denso
    payload={                            # Metadados JSON arbitrários
        "title": "Document title",
        "category": "tech",
        "timestamp": 1699900000,
        "tags": ["python", "ml"]
    }
)

# Upsert em lote (recomendado)
client.upsert(
    collection_name="documents",
    points=[point1, point2, point3],
    wait=True  # Aguardar indexação
)

Collections - Contêineres de vetores

from qdrant_client.models import VectorParams, Distance, HnswConfigDiff

# Criar com configuração HNSW
client.create_collection(
    collection_name="documents",
    vectors_config=VectorParams(
        size=384,                        # Dimensões do vetor
        distance=Distance.COSINE         # COSINE, EUCLID, DOT, MANHATTAN
    ),
    hnsw_config=HnswConfigDiff(
        m=16,                            # Conexões por nó (padrão 16)
        ef_construct=100,                # Precisão em tempo de construção (padrão 100)
        full_scan_threshold=10000        # Mudar para força bruta abaixo disso
    ),
    on_disk_payload=True                 # Armazenar payload em disco
)

# Informações de coleção
info = client.get_collection("documents")
print(f"Points: {info.points_count}, Vectors: {info.vectors_count}")

Métricas de distância

MétricaCaso de UsoIntervalo
COSINEEmbeddings de texto, vetores normalizados0 a 2
EUCLIDDados espaciais, recursos de imagem0 a ∞
DOTRecomendações, não normalizadas-∞ a ∞
MANHATTANRecursos esparsos, dados discretos0 a ∞

Operações de busca

Busca básica

# Busca simples do vizinho mais próximo
results = client.search(
    collection_name="documents",
    query_vector=[0.1, 0.2, ...],
    limit=10,
    with_payload=True,
    with_vectors=False  # Não retornar vetores (mais rápido)
)

Busca com filtragem

from qdrant_client.models import Filter, FieldCondition, MatchValue, Range

# Filtragem complexa
results = client.search(
    collection_name="documents",
    query_vector=query_embedding,
    query_filter=Filter(
        must=[
            FieldCondition(key="category", match=MatchValue(value="tech")),
            FieldCondition(key="timestamp", range=Range(gte=1699000000))
        ],
        must_not=[
            FieldCondition(key="status", match=MatchValue(value="archived"))
        ]
    ),
    limit=10
)

# Sintaxe abreviada de filtro
results = client.search(
    collection_name="documents",
    query_vector=query_embedding,
    query_filter={
        "must": [
            {"key": "category", "match": {"value": "tech"}},
            {"key": "price", "range": {"gte": 10, "lte": 100}}
        ]
    },
    limit=10
)

Busca em lote

from qdrant_client.models import SearchRequest

# Múltiplas consultas em uma única requisição
results = client.search_batch(
    collection_name="documents",
    requests=[
        SearchRequest(vector=[0.1, ...], limit=5),
        SearchRequest(vector=[0.2, ...], limit=5, filter={"must": [...]}),
        SearchRequest(vector=[0.3, ...], limit=10)
    ]
)

Integração com RAG

Com sentence-transformers

from sentence_transformers import SentenceTransformer
from qdrant_client import QdrantClient
from qdrant_client.models import VectorParams, Distance, PointStruct

# Inicializar
encoder = SentenceTransformer("all-MiniLM-L6-v2")
client = QdrantClient(host="localhost", port=6333)

# Criar coleção
client.create_collection(
    collection_name="knowledge_base",
    vectors_config=VectorParams(size=384, distance=Distance.COSINE)
)

# Indexar documentos
documents = [
    {"id": 1, "text": "Python is a programming language", "source": "wiki"},
    {"id": 2, "text": "Machine learning uses algorithms", "source": "textbook"},
]

points = [
    PointStruct(
        id=doc["id"],
        vector=encoder.encode(doc["text"]).tolist(),
        payload={"text": doc["text"], "source": doc["source"]}
    )
    for doc in documents
]
client.upsert(collection_name="knowledge_base", points=points)

# Recuperação para RAG
def retrieve(query: str, top_k: int = 5) -> list[dict]:
    query_vector = encoder.encode(query).tolist()
    results = client.search(
        collection_name="knowledge_base",
        query_vector=query_vector,
        limit=top_k
    )
    return [{"text": r.payload["text"], "score": r.score} for r in results]

# Usar em pipeline RAG
context = retrieve("What is Python?")
prompt = f"Context: {context}\n\nQuestion: What is Python?"

Com LangChain

from langchain_community.vectorstores import Qdrant
from langchain_community.embeddings import HuggingFaceEmbeddings

embeddings = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")
vectorstore = Qdrant.from_documents(documents, embeddings, url="http://localhost:6333", collection_name="docs")
retriever = vectorstore.as_retriever(search_kwargs={"k": 5})

Com LlamaIndex

from llama_index.vector_stores.qdrant import QdrantVectorStore
from llama_index.core import VectorStoreIndex, StorageContext

vector_store = QdrantVectorStore(client=client, collection_name="llama_docs")
storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)
query_engine = index.as_query_engine()

Suporte multi-vetor

Vetores nomeados (modelos de embedding diferentes)

from qdrant_client.models import VectorParams, Distance

# Coleção com múltiplos tipos de vetores
client.create_collection(
    collection_name="hybrid_search",
    vectors_config={
        "dense": VectorParams(size=384, distance=Distance.COSINE),
        "sparse": VectorParams(size=30000, distance=Distance.DOT)
    }
)

# Inserir com vetores nomeados
client.upsert(
    collection_name="hybrid_search",
    points=[
        PointStruct(
            id=1,
            vector={
                "dense": dense_embedding,
                "sparse": sparse_embedding
            },
            payload={"text": "document text"}
        )
    ]
)

# Buscar vetor específico
results = client.search(
    collection_name="hybrid_search",
    query_vector=("dense", query_dense),  # Especificar qual vetor
    limit=10
)

Vetores esparsos (BM25, SPLADE)

from qdrant_client.models import SparseVectorParams, SparseIndexParams, SparseVector

# Coleção com vetores esparsos
client.create_collection(
    collection_name="sparse_search",
    vectors_config={},
    sparse_vectors_config={"text": SparseVectorParams(index=SparseIndexParams(on_disk=False))}
)

# Inserir vetor esparso
client.upsert(
    collection_name="sparse_search",
    points=[PointStruct(id=1, vector={"text": SparseVector(indices=[1, 5, 100], values=[0.5, 0.8, 0.2])}, payload={"text": "document"})]
)

Quantização (otimização de memória)

from qdrant_client.models import ScalarQuantization, ScalarQuantizationConfig, ScalarType

# Quantização escalar (redução de 4x de memória)
client.create_collection(
    collection_name="quantized",
    vectors_config=VectorParams(size=384, distance=Distance.COSINE),
    quantization_config=ScalarQuantization(
        scalar=ScalarQuantizationConfig(
            type=ScalarType.INT8,
            quantile=0.99,        # Recortar outliers
            always_ram=True      # Manter quantizado em RAM
        )
    )
)

# Buscar com rescore
results = client.search(
    collection_name="quantized",
    query_vector=query,
    search_params={"quantization": {"rescore": True}},  # Rescore dos top resultados
    limit=10
)

Indexação de payload

from qdrant_client.models import PayloadSchemaType

# Criar índice de payload para filtragem mais rápida
client.create_payload_index(
    collection_name="documents",
    field_name="category",
    field_schema=PayloadSchemaType.KEYWORD
)

client.create_payload_index(
    collection_name="documents",
    field_name="timestamp",
    field_schema=PayloadSchemaType.INTEGER
)

# Tipos de índice: KEYWORD, INTEGER, FLOAT, GEO, TEXT (full-text), BOOL

Deploy em produção

Qdrant Cloud

from qdrant_client import QdrantClient

# Conectar ao Qdrant Cloud
client = QdrantClient(
    url="https://your-cluster.cloud.qdrant.io",
    api_key="your-api-key"
)

Otimização de desempenho

# Otimizar para velocidade de busca (maior recall)
client.update_collection(
    collection_name="documents",
    hnsw_config=HnswConfigDiff(ef_construct=200, m=32)
)

# Otimizar para velocidade de indexação (cargas em massa)
client.update_collection(
    collection_name="documents",
    optimizer_config={"indexing_threshold": 20000}
)

Boas práticas

  1. Operações em lote - Use upsert/search em lote para eficiência
  2. Indexação de payload - Indexar campos usados em filtros
  3. Quantização - Habilitar para coleções grandes (>1M vetores)
  4. Sharding - Usar para coleções >10M vetores
  5. Armazenamento em disco - Habilitar on_disk_payload para payloads grandes
  6. Pool de conexões - Reutilizar instâncias de cliente

Problemas comuns

Busca lenta com filtros:

# Criar índice de payload para campos filtrados
client.create_payload_index(
    collection_name="docs",
    field_name="category",
    field_schema=PayloadSchemaType.KEYWORD
)

Falta de memória:

# Habilitar quantização e armazenamento em disco
client.create_collection(
    collection_name="large_collection",
    vectors_config=VectorParams(size=384, distance=Distance.COSINE),
    quantization_config=ScalarQuantization(...),
    on_disk_payload=True
)

Problemas de conexão:

# Usar timeout e retry
client = QdrantClient(
    host="localhost",
    port=6333,
    timeout=30,
    prefer_grpc=True  # gRPC para melhor desempenho
)

Referências

Recursos

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 193kUpdated Claude CodeCodexVerifiedInstall