Qdrant Patterns

Patterns canoniques pour utiliser Qdrant — particulièrement pour self-hosting, performance maximale et cost control.

1. Setup

Self-hosted via Docker

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

Qdrant Cloud (managed)

from qdrant_client import QdrantClient

client = QdrantClient(
    url="https://your-cluster.qdrant.tech",
    api_key=os.environ["QDRANT_API_KEY"],
)

2. Create collection

from qdrant_client.models import Distance, VectorParams, HnswConfigDiff

client.create_collection(
    collection_name="documents",
    vectors_config=VectorParams(
        size=1536,
        distance=Distance.COSINE,
    ),
    hnsw_config=HnswConfigDiff(
        m=16,
        ef_construct=200,
    ),
    on_disk_payload=True,  # payloads sur disque vs RAM
)

3. Insert points

from qdrant_client.models import PointStruct

client.upsert(
    collection_name="documents",
    points=[
        PointStruct(
            id=1,
            vector=embedding_1,
            payload={
                "text": "Comment configurer Postgres",
                "source": "guide.pdf",
                "page": 12,
                "category": "tutorial",
                "language": "fr",
                "published_at": "2026-04-08",
            },
        ),
        # ... more points
    ],
)

4. Search avec filters

from qdrant_client.models import Filter, FieldCondition, MatchValue

results = client.search(
    collection_name="documents",
    query_vector=query_embedding,
    query_filter=Filter(
        must=[
            FieldCondition(key="category", match=MatchValue(value="tutorial")),
            FieldCondition(key="language", match=MatchValue(value="fr")),
        ],
    ),
    limit=10,
    with_payload=True,
)

for hit in results:
    print(f"{hit.score:.3f} - {hit.payload['source']}")

5. Payload indexing (filters rapides)

from qdrant_client.models import PayloadSchemaType

# Index keyword pour filters exacts
client.create_payload_index(
    collection_name="documents",
    field_name="category",
    field_schema=PayloadSchemaType.KEYWORD,
)

# Index full-text pour recherche dans le payload text
client.create_payload_index(
    collection_name="documents",
    field_name="text",
    field_schema=PayloadSchemaType.TEXT,
)

# Index datetime pour range queries
client.create_payload_index(
    collection_name="documents",
    field_name="published_at",
    field_schema=PayloadSchemaType.DATETIME,
)

Sans index payload, les filters sont O(N) — lents sur grosse collection. Avec index, O(log N).

6. Quantization (4-32x storage reduction)

from qdrant_client.models import ScalarQuantization, ScalarQuantizationConfig, ScalarType

# Scalar quantization: int8, ~4x storage reduction, ~5% perte qualité
client.update_collection(
    collection_name="documents",
    quantization_config=ScalarQuantization(
        scalar=ScalarQuantizationConfig(
            type=ScalarType.INT8,
            always_ram=True,  # garde en RAM pour perf
        ),
    ),
)

Quantization	Storage reduction	Quality loss
Scalar (int8)	4x	~5%
Product (PQ)	4-64x	~10-30% selon paramètres
Binary (BQ)	32x	~15-30%

Règle : Scalar int8 par défaut, suffisamment précis pour 95% des cas.

7. Hybrid search (sparse + dense)

from qdrant_client.models import SparseVectorParams, NamedVector, NamedSparseVector, SparseVector

# Schema avec sparse + dense
client.recreate_collection(
    collection_name="hybrid_docs",
    vectors_config={
        "dense": VectorParams(size=1536, distance=Distance.COSINE),
    },
    sparse_vectors_config={
        "bm25": SparseVectorParams(),
    },
)

# Insert
client.upsert(
    collection_name="hybrid_docs",
    points=[{
        "id": 1,
        "vector": {
            "dense": dense_emb,
            "bm25": SparseVector(indices=[10, 45, 234], values=[0.5, 0.8, 0.3]),
        },
        "payload": {"text": "..."},
    }],
)

# Query avec fusion RRF
results = client.query_points(
    collection_name="hybrid_docs",
    prefetch=[
        {"query": dense_query, "using": "dense", "limit": 20},
        {"query": SparseVector(indices=qids, values=qvalues), "using": "bm25", "limit": 20},
    ],
    query={"fusion": "rrf"},  # Reciprocal Rank Fusion natif
    limit=10,
)

8. Multi-tenancy

Option A : Payload-based (1 collection partagée)

client.upsert(
    collection_name="multi_tenant_docs",
    points=[PointStruct(
        id=1,
        vector=embedding,
        payload={"tenant_id": "acme-corp", "text": "..."},
    )],
)

# Query avec filter strict
results = client.search(
    collection_name="multi_tenant_docs",
    query_vector=query_embedding,
    query_filter=Filter(must=[FieldCondition(key="tenant_id", match=MatchValue(value="acme-corp"))]),
    limit=10,
)

Option B : Collection-per-tenant (isolation forte)

client.create_collection(collection_name=f"docs_{tenant_id}", ...)

Plus sûr mais coût overhead par collection.

9. Snapshots (backup)

# Créer snapshot
snapshot_info = client.create_snapshot(collection_name="documents")
print(snapshot_info.name)

# Restore depuis snapshot
client.recover_snapshot(
    collection_name="documents",
    location="https://my-bucket.s3.amazonaws.com/snapshots/documents-2026-04-08.snapshot",
)

10. Anti-patterns

1. Pas d'API key en prod — accès anonyme
2. Pas de payload index sur les fields filtrés — slow filters
3. on_disk_payload=False sur grosse collection — RAM saturée
4. Pas de quantization sur grosse collection — storage cost excessif
5. exact=True par défaut — slow (utiliser HNSW approximate)
6. HNSW m trop bas (<8) — recall faible
7. HNSW m trop haut (>32) — RAM excessive
8. ef runtime trop bas (<32) — recall faible
9. Pas de snapshots automatiques — backup oublié
10. Single node en prod — pas de HA, replication factor=1
11. Pas de monitoring Prometheus + Grafana — perf invisible

Checklist

• API key activée
• Distance metric correcte (Cosine pour embeddings normalisés)
• HNSW m=16 ef_construct=200 (defaults raisonnables)
• Payload indexes sur les fields filtrés
• Quantization activée si > 1M vectors
• Multi-tenancy via payload ou collection
• Snapshots automatiques (cron quotidien)
• Replication factor ≥ 2 en prod
• Monitoring Prometheus
• Sharding si > 100M vectors

Quand déléguer

• Architecture RAG → agent rag-architect (ce plugin)
• Pinecone managed → skill pinecone-patterns (ce plugin)
• Weaviate hybrid natif → skill weaviate-patterns (ce plugin)
• pgvector → skill supabase-patterns (atum-stack-backend)

Ressources

• https://qdrant.tech/documentation/
• https://github.com/qdrant/qdrant
• https://qdrant.tech/articles/quantization/