# Bien démarrer avec Qdrant !

# 1\. Qu’est-ce qu’une base de données vectorielle ?

Traditionnellement, les bases de données relationnelles (SQL) ou NoSQL gèrent des données structurées ou semi-structurées. Cependant, avec l’avènement des modèles de langage (LLM) et de l’IA, nous avons besoin de **stocker et de rechercher** des données sous forme de **vecteurs** (embeddings). Les bases de données vectorielles (ou *vector stores*) sont conçues pour :

* Enregistrer des **vecteurs** de grande dimension (ex. 768, 1536, 2048 dimensions…).
    
* Offrir une **recherche de similarité** efficace (e.g. similarité cosinus, distance Euclidienne, etc.).
    
* Permettre une **mise à l’échelle** pour gérer des millions (voire des milliards) de vecteurs.
    

Qdrant est l’une de ces bases de données vectorielles, libre et open source, qui se distingue par sa simplicité d’utilisation et ses performances.

---

# 2\. Présentation de Qdrant

**Qdrant** est un moteur de recherche vectorielle et de recommandation. Ses points forts :

* **Open Source** (Licence Apache 2.0).
    
* **Performant** pour des recherches de similarité (ANN: Approximate Nearest Neighbor).
    
* **API REST** et **client officiel** (en Python, Go, JavaScript, etc.) simples à utiliser.
    
* **Scalabilité** : Qdrant propose une version Cloud managée, ou vous pouvez héberger vous-même (docker, etc.).
    

**Terminologie** :

1. **Collection** : c’est l’équivalent d’une “table” dans Qdrant. Chaque collection stocke des points (ou documents vectorisés) ayant la même **dimension** pour les vecteurs.
    
2. **Points** (ou documents) : chaque point possède :
    
    * Un **id** unique,
        
    * Un **vecteur** (la représentation numérique de votre texte / image / etc.),
        
    * Un **payload** (métadonnées libres au format JSON).
        
3. **Distance** : la métrique de comparaison entre vecteurs (COSINE, Euclidean, Dot, etc.).
    

---

# 3\. Installation et prise en main

Il existe plusieurs manières d’utiliser Qdrant :

1. **Localement** : via Docker ou un binaire à installer.
    
2. **Qdrant Cloud** : solution managée (vous créez un compte, vous obtenez une URL et une clé API).
    

## 3.1. Démarrer Qdrant en local (avec Docker)

```plaintext
bashCopierModifierdocker run -p 6333:6333 \
    -v $(pwd)/qdrant_storage:/qdrant/storage \
    qdrant/qdrant
```

* Le serveur Qdrant écoute alors par défaut sur le port `6333`.
    
* Les données sont persistées dans le dossier `qdrant_storage`.
    
* Vous pouvez maintenant appeler l’API REST sur `http://localhost:6333`.
    

## 3.2. Accéder à l’API REST

Pour vérifier que ça fonctionne, lancez un :

```plaintext
bashCopierModifiercurl http://localhost:6333/collections
```

Vous devriez recevoir quelque chose comme :

```plaintext
jsonCopierModifier{
  "status": "ok",
  "result": {
    "collections": []
  }
}
```

Cela signifie que vous n’avez aucune collection pour le moment, ce qui est normal.

---

# 4\. Créer et gérer une collection

Pour travailler avec Qdrant, il y a deux moyens courants :

1. **API REST** (via requêtes HTTP).
    
2. **Clients officiels** (Python, Go, Node.js, etc.).
    

Dans ce cours d’initiation, on va surtout montrer la **version Python** (car c’est souvent le langage privilégié dans les projets IA), mais le principe est le même avec l’API REST ou un autre client.

## 4.1. Installation du client Python

```plaintext
bashCopierModifierpip install qdrant-client
```

## 4.2. Se connecter à Qdrant (Python)

```plaintext
pythonCopierModifierfrom qdrant_client import QdrantClient

# Si Qdrant tourne en local :
qdrant_client = QdrantClient(url="http://localhost:6333")

# Si vous avez un compte Qdrant Cloud :
# qdrant_client = QdrantClient(url="https://<CLUSTER_ID>.cloud.qdrant.io", api_key="VOTRE_CLE_API")
```

## 4.3. Créer une collection

Imaginons que nous travaillons avec des embeddings de dimension 1536 (comme ceux produits par le modèle OpenAI text-embedding-ada-002). On crée une collection nommée `"my_collection"` :

```plaintext
pythonCopierModifierfrom qdrant_client.models import VectorParams, Distance

qdrant_client.recreate_collection(
    collection_name="my_collection",
    vectors_config=VectorParams(size=1536, distance=Distance.COSINE)
)
```

* `size=1536` : la dimension du vecteur.
    
* `distance=Distance.COSINE` : la métrique de similarité (distance cosinus).
    

*Remarque :* `recreate_collection` supprime la collection si elle existe déjà et la recrée. Vous pouvez utiliser `create_collection` si vous ne voulez pas la recréer à chaque fois.

---

# 5\. Insérer des vecteurs (points) dans la collection

Pour alimenter Qdrant, on stocke des “points”, c’est-à-dire :

* **id** : un identifiant unique (entier ou chaîne de caractères).
    
* **vector** : la liste (un tableau) de dimensions = 1536 (dans notre exemple).
    
* **payload** : un dictionnaire JSON contenant des métadonnées arbitraires.
    

## 5.1. Exemple de données à insérer

Imaginons que vous avez déjà généré un embedding pour une phrase :

* Embedding (1536 floats)
    
* Métadonnées : `{ "text": "Ceci est un texte", "source": "wiki" }`
    

On peut faire un upsert :

```plaintext
pythonCopierModifierpoints = [
    {
        "id": 1,
        "vector": [0.1, 0.2, 0.3, ..., 0.0005],  # 1536 valeurs
        "payload": {
            "text": "Ceci est un texte",
            "source": "wiki"
        }
    },
    {
        "id": 2,
        "vector": [0.07, 0.22, 0.31, ..., 0.0012],  # 1536 valeurs
        "payload": {
            "text": "Un autre exemple de phrase",
            "source": "blog"
        }
    }
]

qdrant_client.upsert(
    collection_name="my_collection",
    points=points
)
```

Le paramètre `upsert` signifie : *“insérer ou mettre à jour”*. Si l’id existe déjà, il sera mis à jour.

---

# 6\. Rechercher des points par similarité

La fonctionnalité clé de Qdrant est la **recherche de similarité**. On lui fournit un vecteur de requête, et il renvoie les points (documents) les plus proches selon la métrique définie.

**Principe** :

1. Vous générez l’embedding de votre requête (ou d’un nouveau texte).
    
2. Vous appelez la fonction `search` en passant le vecteur.
    
3. Qdrant renvoie un classement (score) des points les plus similaires.
    

### 6.1. Exemple en Python

```plaintext
pythonCopierModifierquery_vector = [0.12, 0.29, 0.05, ..., 0.00009]  # 1536 valeurs
search_results = qdrant_client.search(
    collection_name="my_collection",
    query_vector=query_vector,
    limit=3  # récupérer les 3 plus proches
)

for result in search_results:
    print("ID:", result.id)
    print("Score:", result.score)
    print("Payload:", result.payload)
    print("------")
```

* **result.score** représente la distance ou la similarité (selon la métrique choisie).
    
* **result.payload** contient vos métadonnées (`text`, `source`, etc.).
    

---

# 7\. Gestion avancée

### 7.1. Filtres sur le payload

Vous pouvez filtrer les points selon leurs métadonnées. Par exemple, récupérer uniquement les points dont `source = "wiki"` :

```plaintext
pythonCopierModifierfrom qdrant_client.models import Filter, FieldCondition, MatchValue

search_results = qdrant_client.search(
    collection_name="my_collection",
    query_vector=query_vector,
    limit=3,
    query_filter=Filter(
        must=[
            FieldCondition(
                key="source",
                match=MatchValue(value="wiki")
            )
        ]
    )
)
```

### 7.2. Mise à jour / suppression d’un point

* **Mise à jour** : On utilise à nouveau `upsert` pour réécrire un point avec le même id.
    
* **Suppression** :
    
    ```plaintext
    pythonCopierModifierqdrant_client.delete(
        collection_name="my_collection",
        points_selector=[1, 2]  # liste des ids à supprimer
    )
    ```
    

### 7.3. Import massif

Pour importer des milliers (ou millions) de points, il est préférable de faire du **batch** (par paquets) au lieu de one-by-one. Qdrant gère aussi l’**import via CSV** ou un **dump** complet, mais dans de nombreux scénarios, on utilise un script Python en batch.

---

# 8\. Hébergement et production

### 8.1. Qdrant Cloud

Si vous ne voulez pas gérer l’infrastructure vous-même, vous pouvez vous inscrire sur **Qdrant Cloud**. Vous obtiendrez :

* Une URL de type `https://<cluster_id>.cloud.qdrant.io`
    
* Une clé API associée
    

Cela permet d’utiliser la même **API** et le même **client Python**, avec du SSL/TLS et une gestion scalable.

### 8.2. Sécurité et authentification

* En local, Qdrant ne nécessite pas d’authentification (par défaut).
    
* En production, vous devriez le **protéger** derrière un proxy ou un pare-feu, ou activer l’authentification.
    
* Dans Qdrant Cloud, il faut un **api\_key** pour chaque requête.
    

---

# 9\. Intégration avec l’IA (use case typique)

1. **Embeddings** : vous générez les embeddings de textes, d’articles, de documents, en utilisant par exemple OpenAI, Hugging Face, etc.
    
2. **Stockage** : vous insérez ces embeddings dans Qdrant (chaque embedding dans une collection, payload = contenu original ou métadonnées).
    
3. **Recherche de similarité** : quand un utilisateur pose une question, vous générez l’embedding de la question, vous interrogez Qdrant pour obtenir les chunks les plus similaires, puis vous donnez ces informations à un modèle de langage (LLM) pour formuler une réponse enrichie.
    

C’est la base des “**chatbots** connectés à une base documentaire” ou de la “**recherche sémantique**” dans des documents.

---

# 10\. Synthèse

**Qdrant** est une solution pratique et performante pour :

1. Gérer des données sous forme de **vecteurs**.
    
2. Effectuer des **recherches de similarité** (ANN) rapides.
    
3. Gérer l’évolutivité grâce à son mode Cloud ou en local (conteneur Docker).
    

Le **flux de travail** type :

1. **Préparer** vos données (textes, images, etc.) et **générer** les embeddings.
    
2. **Créer** une collection dans Qdrant (choisir la bonne dimension et la métrique).
    
3. **Upsert** (insérer) vos vecteurs avec un ID et des métadonnées (payload).
    
4. **Rechercher** par similarité à l’aide de `search`.
    
5. (Optionnel) Gérer des **filtres**, la **mise à jour** et la **suppression** de points.
    

---

## Ressources supplémentaires

* **Site officiel** : [qdrant.tech](https://qdrant.tech)
    
* **Documentation** : Qdrant Documentation
    
* **Exemples en Python** : [Qdrant GitHub](https://github.com/qdrant/qdrant)
    
* **Blog / Tutoriels** : Qdrant Blog
    
* **Qdrant + LangChain** : des intégrations existent pour gérer le stockage vectoriel et la recherche dans LangChain (VectorStore).
    

Vous avez maintenant les bases pour commencer à utiliser Qdrant. Bon apprentissage !