Qdrant : définition, fonctionnement et exemple Python

Qdrant (prononcé « quadrant ») est une base de données spécialisée dans le vecteur. Dans une application d'IA générative, chaque document, paragraphe ou image est converti en embedding, une liste de nombres qui encode son sens. Retrouver les contenus pertinents pour une question revient alors à chercher les vecteurs les plus proches de celui de la question, c'est ce que fait Qdrant, y compris sur de gros volumes.

Le moteur est écrit en Rust et publié sous licence Apache 2.0. Il est développé par la société Qdrant, basée à Berlin, qui propose aussi un service managé, Qdrant Cloud. L'essor des LLM et du RAG en a fait l'une des bases vectorielles open source les plus utilisées, aux côtés de Weaviate et de l'extension pgvector.

Son positionnement : une base libre que l'on déploie où l'on veut, avec des filtres sur métadonnées particulièrement soignés. C'est ce qui la distingue de Pinecone, proposée uniquement en service managé.

À retenir : Qdrant ne génère pas de texte et ne comprend pas les documents. Il stocke des vecteurs produits par un modèle d'embedding et retrouve rapidement les plus proches, en respectant des filtres.

Qdrant organise les données sur trois niveaux, à concevoir avant d'écrire le premier vecteur.

• Collection : l'ensemble de points de même nature, défini par la taille des vecteurs et la distance. Une collection peut contenir plusieurs vecteurs nommés par point, par exemple un vecteur dense et un vecteur creux.
• Point : l'unité de stockage, composée d'un identifiant, d'un ou plusieurs vecteurs et d'un payload.
• Payload : un document JSON attaché au point. Il sert à filtrer la recherche (par date, source, droit d'accès) et à restituer le contenu. Les champs filtrés fréquemment gagnent à être indexés.

Filtrage, quantification et mode distribué

Le filtrage combine des conditions de type must, should et must_not sur des mots-clés, des plages numériques, du texte ou des coordonnées géographiques. La quantification compresse les vecteurs pour réduire la mémoire vive utilisée, avec une perte de précision que l'on compense en réévaluant les meilleurs candidats. Enfin, le mode distribué répartit une collection en shards et en réplicas sur plusieurs nœuds, pour monter en charge et tolérer les pannes.

La recherche hybride

La recherche vectorielle seule rate parfois des correspondances exactes : un code produit, un nom propre, un acronyme interne. Qdrant prend en charge les vecteurs creux, qui encodent la présence et le poids des termes, et propose des requêtes à étages (prefetch) dont les listes sont fusionnées par Reciprocal Rank Fusion (RRF) ou par une fusion basée sur la distribution des scores (DBSF).

Une plateforme de support veut retrouver les réponses de sa FAQ les plus proches d'une question, en combinant sens et termes exacts. Le code suivant utilise le client officiel (paquet qdrant-client) face à un serveur local lancé avec docker run -p 6333:6333 qdrant/qdrant. Les vecteurs sont ici fictifs : en pratique, ils proviennent d'un modèle d'embedding.

from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://localhost:6333")

# 1. Collection avec un vecteur dense (3 dimensions pour l'exemple) et un vecteur creux
client.create_collection(
    collection_name="support-faq",
    vectors_config={"dense": models.VectorParams(size=3, distance=models.Distance.COSINE)},
    sparse_vectors_config={"sparse": models.SparseVectorParams()},
)

# 2. Upsert : identifiant, vecteurs et payload
client.upsert(
    collection_name="support-faq",
    points=[
        models.PointStruct(
            id=1,
            vector={
                "dense": [0.01, 0.45, 0.67],
                "sparse": models.SparseVector(indices=[1, 42], values=[0.22, 0.8]),
            },
            payload={"text": "Le remboursement intervient sous 14 jours.", "produit": "boutique", "annee": 2026},
        ),
    ],
)

# 3. Requête hybride : deux recherches fusionnées par RRF, filtrées sur le payload
filtre = models.Filter(must=[models.FieldCondition(key="produit", match=models.MatchValue(value="boutique"))])
resultats = client.query_points(
    collection_name="support-faq",
    prefetch=[
        models.Prefetch(query=[0.01, 0.45, 0.67], using="dense", limit=20, filter=filtre),
        models.Prefetch(
            query=models.SparseVector(indices=[1, 42], values=[0.22, 0.8]),
            using="sparse",
            limit=20,
            filter=filtre,
        ),
    ],
    query=models.FusionQuery(fusion=models.Fusion.RRF),
    limit=3,
)
for point in resultats.points:
    print(point.id, round(point.score, 3), point.payload["text"])

La taille du vecteur dense doit correspondre exactement à celle du modèle d'embedding, et la question doit être vectorisée avec ce même modèle. Chaque Prefetch exécute sa propre recherche, puis la fusion RRF produit un classement unique. Le texte d'origine est conservé dans le payload pour l'afficher ou le transmettre au LLM sans seconde requête. Dans un RAG, ces résultats sont ensuite injectés dans le prompt, souvent par LangChain ou LlamaIndex, qui disposent d'intégrations.

Le choix d'une base vectorielle se joue moins sur la qualité de la recherche, comparable d'une solution à l'autre, que sur le modèle d'exploitation. Voici comment Qdrant se situe face à Pinecone, Weaviate et pgvector.

Une démarche fréquente consiste à prototyper avec pgvector ou un Qdrant local, puis à choisir la base de production selon les contraintes : souveraineté des données et réversibilité orientent vers Qdrant ou Weaviate, absence d'équipe d'exploitation vers Pinecone. Notre article Pinecone : la base de données vectorielle managée détaille le fonctionnement des bases vectorielles côté managé.

Ce n'est pas un choix binaire. Si vos données sont des vecteurs bien séparés de leur texte source, changer de base reste possible : conservez toujours les documents et le pipeline de vectorisation.

Les agents IA ont besoin de retrouver des faits issus de conversations ou d'actions passées. Une collection Qdrant sert de mémoire à long terme : chaque souvenir est un point, filtrable par utilisateur, session ou date. Les articles Mémoire des agents IA et Gérer l'état des agents IA détaillent ces stratégies, que le métier d'AI Engineer met en pratique au quotidien.