Connecter Qdrant à n8n : le guide complet du vector store dédié

Qdrant est probablement la base vectorielle dédiée la plus naturelle à brancher sur n8n : open source, un node natif, un conteneur Docker qui tourne à côté de votre instance, et une offre cloud managée pour ceux qui ne veulent rien opérer. Si vous hésitez encore entre Qdrant et pgvector, notre comparatif Qdrant vs pgvector détaille les critères de choix ; ce guide-ci prend la décision comme acquise et déroule le concret : lancer Qdrant, créer la credential, insérer des documents, interroger la collection depuis un AI Agent, et filtrer sur les métadonnées. De zéro au premier retrieval réussi.

Pourquoi Qdrant pour un RAG n8n

Trois arguments reviennent systématiquement chez ceux qui choisissent Qdrant :

• Open source et self-hostable. Le moteur (écrit en Rust) se lance en un conteneur Docker sur le même serveur que n8n. Vos vecteurs restent chez vous, sans dépendance cloud obligatoire — contrairement à Pinecone, entièrement managé.
• Le filtrage de payload intégré à l'index. Chaque point Qdrant porte un payload de métadonnées librement structuré, et les filtres (must/should/must_not, plages, correspondances exactes) sont appliqués pendant le parcours de l'index HNSW, pas après coup sur les résultats. Pour un RAG multi-tenant ou fortement filtré, c'est l'argument décisif.
• Une performance de moteur dédié. Qdrant repose sur l'algorithme HNSW décrit par Malkov et Yashunin dans Efficient and Robust Approximate Nearest Neighbor Search Using Hierarchical Navigable Small World Graphs (IEEE Transactions on Pattern Analysis and Machine Intelligence, 2020, voir sur Google Scholar) : un graphe hiérarchique multi-couches qui offre une complexité de recherche logarithmique, ce qui explique que la latence reste basse même quand la collection grossit sérieusement.

Étape 1 : lancer Qdrant

En Docker, à côté de n8n

Le plus simple est d'ajouter le service au docker-compose.yml qui héberge déjà votre n8n :

services:
  qdrant:
    image: qdrant/qdrant:latest
    restart: unless-stopped
    ports:
      - "6333:6333"
    environment:
      - QDRANT__SERVICE__API_KEY=change-me-long-random-string
    volumes:
      - qdrant_storage:/qdrant/storage

volumes:
  qdrant_storage:

Trois points à ne pas rater :

1. Le volume persistant : sans lui, vos collections disparaissent à chaque recréation du conteneur.
2. La clé API via QDRANT__SERVICE__API_KEY : Qdrant démarre sans authentification par défaut, ce qui est acceptable sur un réseau Docker interne mais jamais si le port 6333 est exposé publiquement.
3. Le dashboard : une fois lancé, http://votre-serveur:6333/dashboard donne une interface web pour inspecter les collections et les points — précieux pour déboguer une ingestion.

Sur Qdrant Cloud

Si vous préférez ne rien héberger, Qdrant Cloud fournit un cluster managé (avec un niveau gratuit suffisant pour prototyper). Après création du cluster, récupérez deux informations : l'URL du cluster (de la forme https://xxx-xxx.region.cloud.qdrant.io:6333) et une clé API, générée depuis l'onglet API Keys du cluster. Ce sont exactement les deux champs que n8n vous demandera.

Étape 2 : créer la credential Qdrant dans n8n

Dans n8n, créez une credential Qdrant API avec deux champs :

• Qdrant URL : l'adresse de votre instance. Attention au cas Docker : si n8n tourne lui aussi en conteneur sur le même réseau, l'hôte est le nom du service (http://qdrant:6333), pas localhost — localhost désignerait le conteneur n8n lui-même.
• API Key : la clé définie dans l'environnement Docker ou générée sur Qdrant Cloud. Le champ peut rester vide pour une instance locale non authentifiée, mais autant prendre la bonne habitude tout de suite.

Le test de connexion intégré valide immédiatement la paire URL + clé. Cette credential servira ensuite dans tous les modes du node, insertion comme recherche.

Étape 3 : insérer des documents (mode Insert)

Le node Qdrant Vector Store en mode Insert Documents constitue la destination du pipeline d'ingestion. Il se configure avec la credential créée ci-dessus et un nom de collection — si elle n'existe pas, le node la crée avec la dimension du premier embedding reçu. Deux sous-nodes s'y branchent :

1. Un node Embeddings (OpenAI, Mistral, Ollama…) qui vectorise chaque fragment — le choix du modèle d'embeddings conditionne la dimension de la collection et ne pourra plus changer sans réingestion.
2. Un Default Data Loader (avec son Text Splitter) qui charge le document source, le découpe en chunks — taille et recouvrement sont traités dans notre guide du chunking — et attache les métadonnées.

Les métadonnées définies dans le Data Loader (source, client, date, type de document) atterrissent dans le payload de chaque point Qdrant, sous la clé metadata, le texte du chunk étant stocké sous content. C'est ce payload qui rendra possible le filtrage de l'étape 5.

Étape 4 : interroger la collection

Le même node bascule en mode recherche, avec trois variantes :

Mode	Usage
Retrieve Documents (As Tool for AI Agent)	Exposer la collection comme outil d'un AI Agent, qui décide lui-même quand chercher — le cœur d'un RAG agentique
Retrieve Documents (As Vector Store for Chain/Tool)	Alimenter une chaîne de question-réponse structurée, sans autonomie de l'agent
Get Many	Récupérer directement les N chunks les plus proches d'une requête, pour un traitement en aval

Pour un assistant documentaire, le mode « As Tool for AI Agent » est le standard : donnez à l'outil un nom et une description explicites (« recherche dans la documentation produit interne »), car c'est sur cette description que le modèle décide d'appeler ou non l'outil. Le node Embeddings branché côté recherche doit être strictement le même modèle que celui de l'ingestion — une requête vectorisée dans un autre espace renverrait des résultats aléatoires. Ce principe séparation ingestion/retrieval est le même que dans notre guide RAG avec Supabase ; c'est d'ailleurs tout l'intérêt de l'architecture posée par Lewis et al. dans Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks (NeurIPS 2020, voir sur Google Scholar) : la qualité de la réponse finale dépend d'abord de la pertinence des passages retrouvés.

Étape 5 : filtrer sur le payload

C'est la spécialité de Qdrant. Dans les options du node en mode retrieval, le champ Search Filter accepte un filtre JSON au format natif Qdrant :

{
  "must": [
    { "key": "metadata.client_id", "match": { "value": "acme" } },
    { "key": "metadata.doc_type", "match": { "value": "contrat" } }
  ]
}

Les clés pointent vers le payload avec le préfixe metadata. (là où le Data Loader a rangé vos champs). Le filtre étant évalué pendant le parcours de l'index, la recherche reste rapide même très sélective — le comportement attendu pour du multi-tenant. Les valeurs peuvent être dynamiques via une expression n8n ({{ $json.client_id }}), ce qui permet un seul workflow pour tous les clients. Pour la stratégie d'ensemble (quelles métadonnées attacher, comment les structurer), voir notre article sur le filtrage de métadonnées en RAG.

Bonnes pratiques en production

• Nommez les collections explicitement : docs_produit_openai_small_v2 dit le corpus, le modèle d'embeddings et la version — indispensable le jour où plusieurs collections coexistent.
• Verrouillez la dimension : une collection = un modèle d'embeddings. Changer de modèle = nouvelle collection + réingestion complète, jamais un mélange.
• Planifiez les snapshots : contrairement à pgvector couvert par pg_dump, Qdrant a son propre mécanisme de sauvegarde. Un appel POST /collections/{nom}/snapshots (déclenchable depuis un workflow n8n planifié, avec un node HTTP Request) crée un snapshot restaurable ; stockez-le hors du serveur.
• Surveillez la cohérence corpus/index : documents supprimés à la source, versions obsolètes — notre guide sur la mise à jour d'un index RAG couvre les stratégies d'upsert et de purge.

Quand préférer pgvector

Restons honnêtes : si votre stack tourne déjà sur Postgres ou Supabase, que votre corpus se compte en dizaines ou centaines de milliers de vecteurs et que vos filtres restent simples, pgvector fait le même travail sans service supplémentaire à opérer ni mécanisme de sauvegarde dédié. Qdrant prend l'avantage sur les gros volumes, les filtres de payload riches et systématiques, et les architectures où la recherche vectorielle est un service à part entière. Le comparatif complet Qdrant vs pgvector déroule ces critères un par un.

En résumé

Connecter Qdrant à n8n tient en quatre gestes : un conteneur Docker (ou un cluster Qdrant Cloud), une credential URL + clé API, le node Qdrant Vector Store en mode Insert branché sur un Data Loader et un modèle d'embeddings, puis le même node en mode Retrieve comme outil d'un AI Agent — avec, en bonus, les filtres de payload qui font la réputation du moteur. Le pipeline complet (ingestion, découpage, agent de réponse avec citations) est exactement l'architecture livrée par le Pack Assistant RAG (119 €) : ses workflows utilisent Supabase pgvector par défaut, et passer sur Qdrant se résume à remplacer le node de stockage et recréer la credential — le reste du pipeline ne bouge pas.