Héberger Qdrant sur un VPS

Pourquoi auto-héberger Qdrant sur un VPS

Pré-requis et ressources VPS recommandées

• RAM : minimum 1 Go pour tester, 2 Go pour quelques centaines de milliers de vecteurs, 4–8 Go au-delà du million de vecteurs en haute dimension (l'index HNSW vit en mémoire).
• Stockage : 20–50 Go de SSD NVMe pour persister les collections et les snapshots.
• CPU : 1–2 vCPU suffisent pour un trafic modéré ; ajoutez des cœurs si vous indexez en continu.
• Docker et Docker Compose installés sur le VPS.
• Port 6333 (REST) et 6334 (gRPC) accessibles depuis votre application ; 80/443 pour le reverse proxy public.
• Un enregistrement DNS A (ex. vectors.mondomaine.com) si vous exposez l'API en HTTPS.

Installer Qdrant avec Docker Compose

1. 01

   Créer le répertoire et le fichier compose.yml

   Sur le VPS, créez un dossier dédié : mkdir -p /opt/qdrant && cd /opt/qdrant. Créez le fichier compose.yml suivant :

   services:
     qdrant:
       image: qdrant/qdrant:latest
       restart: unless-stopped
       ports:
         - "127.0.0.1:6333:6333"
         - "127.0.0.1:6334:6334"
       volumes:
         - ./qdrant_storage:/qdrant/storage
       environment:
         - QDRANT__SERVICE__API_KEY=${QDRANT_API_KEY}

   Lier les ports à 127.0.0.1 empêche toute exposition directe sur Internet ; seul le reverse proxy y accède.

2. 02

   Générer la clé API et démarrer le conteneur

   Créez le fichier .env avec votre clé :

   echo "QDRANT_API_KEY=$(openssl rand -hex 32)" > .env

   Démarrez Qdrant :

   docker compose up -d

3. 03

   Vérifier la santé de l'instance

   Attendez quelques secondes puis vérifiez l'endpoint de santé :

   curl -s http://localhost:6333/healthz
   # Attendu : {"title":"qdrant - vector search engine","version":"..."}

4. 04

   Créer votre première collection

   Créez une collection de test avec des vecteurs de dimension 384 (format typique de all-MiniLM-L6-v2) :

   curl -s -X PUT http://localhost:6333/collections/test \
     -H 'Content-Type: application/json' \
     -H "api-key: $(grep QDRANT_API_KEY .env | cut -d= -f2)" \
     -d '{"vectors":{"size":384,"distance":"Cosine"}}'

Sécuriser l'accès : clé API et TLS

vectors.mondomaine.com {
    reverse_proxy localhost:6333
}

location / {
    proxy_pass http://127.0.0.1:6333;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Tester l'authentification et le reverse proxy

1. 05

   Vérifier que l'accès sans clé est refusé

   curl -s https://vectors.mondomaine.com/collections
   # Attendu : {"status":{"error":"Unauthorized",...}}

2. 06

   Appel authentifié avec la clé API

   curl -s https://vectors.mondomaine.com/collections \
     -H "api-key: VOTRE_CLE"
   # Attendu : {"result":{"collections":[]},"status":"ok",...}

3. 07

   Vérifier le certificat TLS

   curl -sv https://vectors.mondomaine.com/healthz 2>&1 | grep 'SSL connection\|issuer'
   # Attendu : lignes confirmant Let's Encrypt et TLS 1.3

Créer une collection et insérer des vecteurs avec le client Python v1

1. 08

   Installer le client officiel

   pip install qdrant-client>=1.7

2. 09

   Connexion avec clé API

   from qdrant_client import QdrantClient
   
   client = QdrantClient(
       url="https://vectors.mondomaine.com",
       api_key="VOTRE_CLE",
   )

3. 10

   Créer une collection avec VectorParams

   from qdrant_client.models import Distance, VectorParams
   
   client.recreate_collection(
       collection_name="documents",
       vectors_config=VectorParams(size=384, distance=Distance.COSINE),
   )

   size doit correspondre à la dimension des embeddings de votre modèle. Distance.COSINE convient pour la majorité des modèles de phrase (sentence transformers).

4. 11

   Insérer des points avec payload et interroger

   from qdrant_client.models import PointStruct
   
   # Insérer des vecteurs
   client.upsert(
       collection_name="documents",
       points=[
           PointStruct(
               id=1,
               vector=[0.1, 0.2, ...],  # vecteur de taille 384
               payload={"title": "Guide Qdrant", "lang": "fr"},
           ),
       ],
   )
   
   # Rechercher les 5 plus proches voisins
   results = client.search(
       collection_name="documents",
       query_vector=[0.1, 0.21, ...],
       limit=5,
       with_payload=True,
   )
   for r in results:
       print(r.score, r.payload)

Optimiser les performances : tuning HNSW

Paramètres HNSW clés

Faites défiler le tableau

Réduire l'empreinte mémoire : quantization scalaire et binaire

• Quantization scalaire (uint8) : compresse chaque coordonnée float32 (4 octets) en uint8 (1 octet), soit une réduction de RAM d'environ 4×. Légère perte de précision compensée par l'oversampling. Activez-la avec ScalarQuantizationConfig(type=ScalarType.INT8, quantile=0.99, always_ram=True).
• Quantization binaire : va jusqu'à 32× de réduction en binarisant chaque dimension. Idéale pour des modèles entraînés pour la quantization binaire (ex. Cohere embed-english-v3.0). Plus rapide mais recall plus faible sans oversampling.
• Paramètre on_disk : stockez les vecteurs originaux sur disque (on_disk=True) et ne gardez en RAM que l'index quantifié. Indispensable sur un VPS à mémoire contrainte.
• Oversampling : avec oversampling=2.0 à la requête, Qdrant récupère 2× plus de candidats depuis l'index quantifié puis les rerange avec les vecteurs originaux — recall proche du full-precision pour un coût modéré.

Sauvegarder et restaurer avec les snapshots Qdrant

1. 12

   Créer un snapshot d'une collection

   curl -s -X POST https://vectors.mondomaine.com/collections/documents/snapshots \
     -H "api-key: VOTRE_CLE"
   # Retourne le nom du snapshot : {"result":{"name":"documents-...-...","creation_time":"..."}}

2. 13

   Lister les snapshots disponibles

   curl -s https://vectors.mondomaine.com/collections/documents/snapshots \
     -H "api-key: VOTRE_CLE"

3. 14

   Télécharger le snapshot

   curl -O https://vectors.mondomaine.com/collections/documents/snapshots/NOM_DU_SNAPSHOT \
     -H "api-key: VOTRE_CLE"

   Copiez ensuite le fichier .snapshot vers un stockage objet (ex. Scaleway Object Storage, Backblaze B2) pour une sauvegarde hors site.

4. 15

   Restaurer depuis un snapshot

   curl -s -X PUT https://vectors.mondomaine.com/collections/documents/snapshots/upload \
     -H "api-key: VOTRE_CLE" \
     -H 'Content-Type: multipart/form-data' \
     -F [email protected]

   La collection est recréée à partir du snapshot avec toutes ses données et sa configuration HNSW d'origine.

Dépannage courant

• Connection refused sur le port 6333 : vérifiez que le conteneur tourne (docker compose ps) et que le port n'est pas bloqué par ufw — ufw allow from 127.0.0.1 to any port 6333. Si le port est lié à 0.0.0.0 au lieu de 127.0.0.1, corrigez le compose.yml et relancez.
• Erreur OOM (Out of Memory) / conteneur tué : réduisez ef_construct (ex. 100 → 64) ou activez la quantization scalaire pour diminuer l'empreinte RAM de l'index. Activez on_disk: true pour les vecteurs originaux. Vérifiez la consommation réelle avec docker stats qdrant.
• Lenteur au démarrage ou au premier chargement : l'index HNSW est chargé depuis le disque au premier accès. Utilisez un SSD NVMe (pas un disque rotatif) et préchauffez la collection après démarrage avec une requête de recherche vide.
• Unauthorized 403 : la clé API passée dans le header api-key ne correspond pas à QDRANT__SERVICE__API_KEY. Vérifiez l'absence d'espaces ou de sauts de ligne dans la variable d'environnement.
• Recall dégradé après activation de la quantization binaire : augmentez oversampling à 3.0 ou 4.0 et activez rescore=True pour reranker les candidats avec les vecteurs originaux.

Associer Qdrant à Ollama pour une stack RAG entièrement autonome