> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-fr/rag-et-bases-de-donnees-vectorielles/chromadb.md).

# ChromaDB

Déployez ChromaDB, la base de données vectorielle open source pour les applications d’IA, sur les GPU de Clore.ai

ChromaDB est la **base de données vectorielle open source de premier plan** conçue spécialement pour les applications d'IA. Elle fournit une API simple et intuitive pour stocker, interroger et gérer des embeddings de haute dimension — l'épine dorsale des systèmes RAG modernes, de la recherche sémantique, des moteurs de recommandation et de la mémoire des LLM.

ChromaDB abstrait la complexité de la recherche de similarité vectorielle, vous permettant de vous concentrer sur la création d'applications d'IA. Il prend en charge à la fois le mode en mémoire pour le développement et un mode serveur persistant pour les déploiements en production, avec prise en charge de Docker pour un déploiement facile sur les serveurs GPU de Clore.ai.

Fonctionnalités clés :

* 🚀 **API Python/JavaScript simple** — démarrage en quelques minutes
* 💾 **Stockage persistant** — les données survivent aux redémarrages du conteneur
* 🔍 **Plusieurs métriques de distance** — cosinus, L2, produit scalaire
* 📦 **Embeddings intégrés** — prise en charge intégrée d'OpenAI, Cohere, sentence-transformers
* 🏗️ **Multi-locataire** — collections pour organiser différents jeux de données
* 🔌 **API REST** — interface HTTP indépendante du langage
* ⚡ **Rapide** — index HNSW pour la recherche approximative des plus proches voisins
* 🔗 **Natif pour LangChain/LlamaIndex** — intégration de premier ordre

{% hint style="success" %}
Tous les exemples peuvent être exécutés sur des serveurs GPU loués via [la place de marché CLORE.AI](https://clore.ai/marketplace).
{% endhint %}

***

## Exigences du serveur

| Paramètre              | Minimum                                | Recommandé                                    |
| ---------------------- | -------------------------------------- | --------------------------------------------- |
| GPU                    | N'importe quel GPU NVIDIA (facultatif) | NVIDIA RTX 3080+ (pour les embeddings)        |
| VRAM                   | Non requis pour ChromaDB               | 8–16 Go (pour les modèles d'embedding locaux) |
| RAM                    | 4 Go                                   | 16–32 Go                                      |
| CPU                    | 2 cœurs                                | 8 cœurs                                       |
| Disque                 | 10 Go                                  | 50–200 Go (pour les grands jeux de données)   |
| Système d'exploitation | Ubuntu 20.04+                          | Ubuntu 22.04                                  |
| Docker                 | Requis                                 | Docker + Docker Compose                       |
| Ports                  | 22, 8000                               | 22, 8000                                      |

{% hint style="info" %}
ChromaDB lui-même ne nécessite pas de GPU — il s'exécute efficacement sur CPU. Cependant, **la génération d'embeddings** (conversion du texte en vecteurs) bénéficie grandement de l'accélération GPU. Si vous prévoyez d'utiliser des modèles d'embeddings locaux (sentence-transformers, etc.), choisissez un serveur avec GPU.
{% endhint %}

***

## Déploiement rapide sur CLORE.AI

### 1. Trouvez un serveur adapté

Accédez à [la place de marché CLORE.AI](https://clore.ai/marketplace) et choisissez :

* **CPU uniquement** pour le serveur ChromaDB + API (stockez des embeddings pré-calculés)
* **Serveur GPU** si vous souhaitez également générer des embeddings localement

### 2. Configurez votre déploiement

**Image Docker :**

```
chromadb/chroma:latest
```

**Mappages de ports :**

```
22 → accès SSH
8000 → API HTTP de ChromaDB
```

**Variables d'environnement :**

```
IS_PERSISTENT=TRUE
ANONYMIZED_TELEMETRY=FALSE
CHROMA_SERVER_AUTH_CREDENTIALS_FILE=/chroma/auth.txt
```

**Commande de démarrage :**

```bash
uvicorn chromadb.app:app --host 0.0.0.0 --port 8000
```

### 3. Tester le déploiement

```bash
curl http://<server-ip>:8000/api/v1/heartbeat
# Attendu : {"nanosecond heartbeat": <horodatage>}
```

***

## Configuration étape par étape

### Étape 1 : connectez-vous en SSH à votre serveur

```bash
ssh root@<your-clore-server-ip> -p <ssh-port>
```

### Étape 2 : créer le répertoire de données

```bash
mkdir -p /workspace/chromadb/data
mkdir -p /workspace/chromadb/config
```

### Étape 3 : exécuter le conteneur ChromaDB

```bash
docker run -d \
  --name chromadb \\
  -p 8000:8000 \
  -v /workspace/chromadb/data:/chroma/chroma \\
  -e IS_PERSISTENT=TRUE \\
  -e ANONYMIZED_TELEMETRY=FALSE \\
  -e CHROMA_SERVER_LOG_LEVEL=INFO \\
  chromadb/chroma:latest
```

### Étape 4 : vérifier qu'il s'exécute

```bash
# Vérifier l'état
curl http://localhost:8000/api/v1/heartbeat

# Vérifier la version
curl http://localhost:8000/api/v1/version

# Lister les collections
curl http://localhost:8000/api/v1/collections
```

### Étape 5 : installer le client Python

```bash
pip install chromadb
pip install sentence-transformers  # Pour les embeddings GPU locaux
pip install openai                  # Pour les embeddings OpenAI
```

### Étape 6 : tester la connectivité depuis Python

```python
import chromadb

client = chromadb.HttpClient(host="<server-ip>", port=8000)
print(f"Version de ChromaDB : {client.get_version()}")
print(f"Heartbeat : {client.heartbeat()}")
```

### Étape 7 : (facultatif) activer l'authentification

```bash
# Créer les identifiants d'authentification
echo "admin:$2y$12$$(openssl rand -hex 16)" > /workspace/chromadb/auth.txt

# Exécuter avec l'authentification activée
docker run -d \
  --name chromadb-auth \\
  -p 8000:8000 \
  -v /workspace/chromadb/data:/chroma/chroma \\
  -v /workspace/chromadb/auth.txt:/chroma/auth.txt \\
  -e IS_PERSISTENT=TRUE \\
  -e CHROMA_SERVER_AUTH_CREDENTIALS_FILE=/chroma/auth.txt \\
  -e CHROMA_SERVER_AUTH_CREDENTIALS_PROVIDER=chromadb.auth.providers.HtpasswdFileServerAuthCredentialsProvider \\
  -e CHROMA_SERVER_AUTH_PROVIDER=chromadb.auth.basic.BasicAuthServerProvider \\
  chromadb/chroma:latest
```

***

## Exemples d'utilisation

### Exemple 1 : opérations de base sur le stockage vectoriel

```python
import chromadb
from chromadb.utils import embedding_functions

# Se connecter à ChromaDB sur le serveur Clore.ai
client = chromadb.HttpClient(
    host="<your-clore-server-ip>",
    port=8000
)

# Utiliser sentence-transformers pour les embeddings (s'exécute sur GPU si disponible)
embedding_fn = embedding_functions.SentenceTransformerEmbeddingFunction(
    model_name="all-MiniLM-L6-v2"
)

# Créer une collection
collection = client.get_or_create_collection(
    name="clore_ai_docs",
    embedding_function=embedding_fn,
    metadata={"hnsw:space": "cosine"}  # Métrique de distance
)

# Ajouter des documents
documents = [
    "Clore.ai est une place de marché cloud GPU décentralisée pour les charges de travail d'IA.",
    "Vous pouvez louer des GPU NVIDIA RTX 4090, A100 et H100 sur Clore.ai.",
    "Clore.ai prend en charge les déploiements basés sur Docker pour n'importe quel framework d'IA.",
    "Les tarifs sur Clore.ai sont compétitifs par rapport à AWS et GCP.",
    "La place de marché Clore.ai compte des milliers de serveurs GPU dans le monde entier.",
    "Vous pouvez déployer PyTorch, TensorFlow, JAX et d'autres frameworks de ML.",
    "Clore.ai propose une tarification spot pour un calcul GPU économique.",
]

ids = [f"doc_{i}" for i in range(len(documents))]

collection.add(
    documents=documents,
    ids=ids,
    metadatas=[{"source": "docs", "index": i} for i in range(len(documents))]
)

print(f"Ajout de {len(documents)} documents à la collection")
print(f"Taille de la collection : {collection.count()} documents")
```

***

### Exemple 2 : recherche sémantique

```python
import chromadb
from chromadb.utils import embedding_functions

client = chromadb.HttpClient(host="<server-ip>", port=8000)
embedding_fn = embedding_functions.SentenceTransformerEmbeddingFunction(
    model_name="all-MiniLM-L6-v2"
)

collection = client.get_collection(
    name="clore_ai_docs",
    embedding_function=embedding_fn
)

# Requêtes de recherche sémantique
queries = [
    "Combien coûte la location d'un GPU ?",
    "Quels outils d'apprentissage automatique sont disponibles ?",
    "Parle-moi des options matérielles GPU",
]

for query in queries:
    results = collection.query(
        query_texts=[query],
        n_results=3,
        include=["documents", "distances", "metadatas"]
    )

    print(f"\n🔍 Requête : {query}")
    for i, (doc, dist) in enumerate(zip(
        results["documents"][0],
        results["distances"][0]
    )):
        similarity = 1 - dist  # Convertir la distance en similarité
        print(f"  {i+1}. [{similarity:.3f}] {doc[:100]}...")
```

***

### Exemple 3 : pipeline RAG avec ChromaDB + OpenAI

```python
import chromadb
from chromadb.utils import embedding_functions
from openai import OpenAI

# Initialiser les clients
chroma_client = chromadb.HttpClient(host="<server-ip>", port=8000)
openai_client = OpenAI(api_key="your-openai-api-key")

# Utiliser les embeddings OpenAI
openai_ef = embedding_functions.OpenAIEmbeddingFunction(
    api_key="your-openai-api-key",
    model_name="text-embedding-3-small"
)

# Obtenir la collection
collection = chroma_client.get_or_create_collection(
    name="knowledge_base",
    embedding_function=openai_ef
)

def add_to_knowledge_base(texts, ids=None, metadatas=None):
    """Ajouter des documents à la base de connaissances ChromaDB."""
    if ids is None:
        ids = [f"doc_{i}" for i in range(len(texts))]
    collection.add(documents=texts, ids=ids, metadatas=metadatas or [{}]*len(texts))
    print(f"✓ {len(texts)} documents ajoutés. Total : {collection.count()}")

def rag_query(question, n_context=5):
    """Récupérer le contexte pertinent et générer une réponse avec GPT-4."""
    # 1. Récupérer les documents pertinents
    results = collection.query(
        query_texts=[question],
        n_results=n_context,
        include=["documents", "distances"]
    )

    context_docs = results["documents"][0]
    distances = results["distances"][0]

    # 2. Construire la chaîne de contexte
    context = "\n\n".join([
        f"[Source {i+1} (pertinence : {1-d:.2f})] : {doc}"
        for i, (doc, d) in enumerate(zip(context_docs, distances))
    ])

    # 3. Générer une réponse avec le LLM
    messages = [
        {
            "role": "system",
            "content": "Vous êtes un assistant utile. Répondez aux questions en vous basant sur le contexte fourni. Si la réponse ne figure pas dans le contexte, dites-le."
        },
        {
            "role": "user",
            "content": f"Contexte :\n{context}\n\nQuestion : {question}"
        }
    ]

    response = openai_client.chat.completions.create(
        model="gpt-4-turbo",
        messages=messages,
        temperature=0.1
    )

    answer = response.choices[0].message.content

    return {
        "question": question,
        "answer": answer,
        "sources": context_docs,
        "relevance_scores": [1 - d for d in distances]
    }

# Exemple d'utilisation
knowledge = [
    "Clore.ai est une place de marché cloud GPU avec plus de 45 000 utilisateurs.",
    "Clore.ai prend en charge le déploiement de charges de travail basées sur Docker.",
    "Les serveurs GPU sur Clore.ai vont de GTX 1080 à H100.",
    "Vous pouvez déployer des applications d'IA avec un accès SSH et des ports personnalisés.",
]
add_to_knowledge_base(knowledge)

result = rag_query("Combien d'utilisateurs Clore.ai compte-t-il ?")
print(f"Q : {result['question']}")
print(f"R : {result['answer']}")
```

***

### Exemple 4 : gestion de documents multi-collections

```python
import chromadb
from chromadb.utils import embedding_functions

client = chromadb.HttpClient(host="<server-ip>", port=8000)
embedding_fn = embedding_functions.SentenceTransformerEmbeddingFunction(
    model_name="all-mpnet-base-v2"  # Embeddings de meilleure qualité
)

# Créer des collections distinctes pour différents types de documents
collections = {
    "technical_docs": client.get_or_create_collection("technical_docs", embedding_function=embedding_fn),
    "faq": client.get_or_create_collection("faq", embedding_function=embedding_fn),
    "blog_posts": client.get_or_create_collection("blog_posts", embedding_function=embedding_fn),
}

# Ajouter des documents aux collections respectives
collections["technical_docs"].add(
    documents=["Guide de déploiement Docker pour Clore.ai", "Configuration SSH pour les serveurs GPU"],
    ids=["tech_001", "tech_002"],
    metadatas=[{"type": "guide", "version": "v2"}, {"type": "config"}]
)

collections["faq"].add(
    documents=["Q : Comment payer ? R : En cryptomonnaie.", "Q : Quels GPU ? R : De RTX à H100."],
    ids=["faq_001", "faq_002"],
    metadatas=[{"category": "payment"}, {"category": "hardware"}]
)

# Rechercher dans toutes les collections
def search_all_collections(query, n_results=2):
    all_results = []
    for name, col in collections.items():
        results = col.query(query_texts=[query], n_results=n_results)
        for doc, dist in zip(results["documents"][0], results["distances"][0]):
            all_results.append({
                "collection": name,
                "document": doc,
                "similarity": 1 - dist
            })

    # Trier par pertinence
    all_results.sort(key=lambda x: x["similarity"], reverse=True)
    return all_results[:n_results * 2]

results = search_all_collections("Comment déployer avec Docker ?")
for r in results:
    print(f"[{r['collection']}] ({r['similarity']:.3f}) {r['document'][:80]}...")
```

***

### Exemple 5 : filtrage et requêtes de métadonnées

```python
import chromadb

client = chromadb.HttpClient(host="<server-ip>", port=8000)
collection = client.get_collection("technical_docs")

# Ajouter des documents avec des métadonnées riches
collection.add(
    documents=[
        "Guide : exécuter PyTorch sur des clusters GPU NVIDIA A100",
        "Guide : entraînement distribué TensorFlow sur RTX 4090",
        "Tutoriel : réglage fin de LLM avec LoRA sur GPU",
        "Référence : matrice de compatibilité CUDA 12.1",
        "Guide : réseau Docker pour les configurations multi-GPU",
    ],
    ids=["d1", "d2", "d3", "d4", "d5"],
    metadatas=[
        {"type": "guide", "gpu": "A100", "framework": "pytorch", "year": 2024},
        {"type": "guide", "gpu": "RTX4090", "framework": "tensorflow", "year": 2024},
        {"type": "tutorial", "gpu": "any", "framework": "transformers", "year": 2024},
        {"type": "reference", "gpu": "any", "framework": "cuda", "year": 2023},
        {"type": "guide", "gpu": "multi", "framework": "docker", "year": 2024},
    ]
)

# Interroger avec un filtre de métadonnées
results = collection.query(
    query_texts=["Guide d'entraînement GPU"],
    n_results=3,
    where={"type": "guide"},  # Ne renvoyer que les guides
    include=["documents", "metadatas", "distances"]
)

print("Résultats filtrés (type=guide) :")
for doc, meta, dist in zip(
    results["documents"][0],
    results["metadatas"][0],
    results["distances"][0]
):
    print(f"  [{1-dist:.3f}] {doc}")
    print(f"    Métadonnées : {meta}")
```

***

## Configuration

### Docker Compose (production)

```yaml
version: '3.8'

services:
  chromadb:
    image: chromadb/chroma:latest
    container_name: chromadb
    ports:
      - "8000:8000"
    volumes:
      - chromadb_data:/chroma/chroma
    environment :
      - IS_PERSISTENT=TRUE
      - ANONYMIZED_TELEMETRY=FALSE
      - CHROMA_SERVER_LOG_LEVEL=INFO
      - ALLOW_RESET=FALSE
      - CHROMA_SEGMENT_CACHE_POLICY=LRU
      - CHROMA_MEMORY_LIMIT_BYTES=2147483648  # 2 Go de cache
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/api/v1/heartbeat"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  chromadb_data:
    driver: local
```

### Référence des variables d'environnement

| Variable                      | Par défaut | Description                                                   |
| ----------------------------- | ---------- | ------------------------------------------------------------- |
| `IS_PERSISTENT`               | `FALSE`    | Activer le stockage persistant                                |
| `ANONYMIZED_TELEMETRY`        | `TRUE`     | Désactiver le suivi d'utilisation                             |
| `CHROMA_SERVER_LOG_LEVEL`     | `INFO`     | Verbosité des journaux                                        |
| `CHROMA_MEMORY_LIMIT_BYTES`   | Aucune     | Mémoire maximale pour le cache de segment                     |
| `ALLOW_RESET`                 | `FALSE`    | Autoriser la réinitialisation de toutes les données via l'API |
| `CHROMA_SERVER_AUTH_PROVIDER` | Aucune     | Classe du fournisseur d'authentification                      |

***

## Conseils de performance

### 1. Choisir le bon modèle d'embedding

| Modèle                   | Dimensions | Vitesse | Qualité   | GPU requis     |
| ------------------------ | ---------- | ------- | --------- | -------------- |
| `all-MiniLM-L6-v2`       | 384        | Rapide  | Bon       | Non            |
| `all-mpnet-base-v2`      | 768        | Moyen   | Meilleur  | Facultatif     |
| `text-embedding-3-small` | 1536       | Rapide  | Excellent | API uniquement |
| `BAAI/bge-large-en-v1.5` | 1024       | Moyen   | Meilleur  | Oui            |

### 2. Upserts par lots pour plus de rapidité

```python
# Ajouter par lots de 100 à 1000 pour de meilleures performances
BATCH_SIZE = 500

for i in range(0, len(all_documents), BATCH_SIZE):
    batch = all_documents[i:i+BATCH_SIZE]
    collection.add(
        documents=[d["text"] for d in batch],
        ids=[d["id"] for d in batch],
        metadatas=[d["meta"] for d in batch]
    )
    print(f"Lot {i//BATCH_SIZE + 1} terminé")
```

### 3. Réglage de l'index HNSW

```python
collection = client.create_collection(
    name="optimized",
    metadata={
        "hnsw:space": "cosine",
        "hnsw:construction_ef": 200,  # Plus élevé = meilleure qualité d'index (construction plus lente)
        "hnsw:search_ef": 100,        # Plus élevé = meilleur rappel (recherche plus lente)
        "hnsw:M": 32,                 # Plus élevé = meilleur rappel (plus de mémoire)
    }
)
```

### 4. Client persistant pour utilisation locale

```python
# Pour le développement directement sur le serveur Clore.ai
import chromadb

client = chromadb.PersistentClient(path="/workspace/chromadb/data")
# Pas besoin de serveur, plus rapide pour une utilisation en processus unique
```

***

## Dépannage

### Problème : impossible de se connecter à ChromaDB

```bash
# Vérifier que le conteneur est en cours d'exécution
docker ps | grep chromadb

# Vérifier les journaux
docker logs chromadb --tail 20

# Tester depuis l'intérieur du conteneur
docker exec chromadb curl http://localhost:8000/api/v1/heartbeat
```

### Problème : données perdues au redémarrage du conteneur

```bash
# S'assurer que le volume est monté
docker inspect chromadb | grep Mounts -A 10

# Relancer avec un volume explicite
docker run -d -p 8000:8000 \\
  -v /workspace/chromadb/data:/chroma/chroma \\
  -e IS_PERSISTENT=TRUE \\
  chromadb/chroma:latest
```

### Problème : erreurs de manque de mémoire

```bash
# Limiter le cache mémoire
docker run -d -p 8000:8000 \\
  -e CHROMA_MEMORY_LIMIT_BYTES=1073741824 \\
  -v /workspace/chromadb/data:/chroma/chroma \\
  chromadb/chroma:latest
```

### Problème : génération d'embeddings lente

```bash
# Vérifier que le GPU est utilisé pour les embeddings
python3 -c "
import torch
from sentence_transformers import SentenceTransformer
model = SentenceTransformer('all-MiniLM-L6-v2', device='cuda')
print(f'Embedding model on: {model.device}')
"
```

### Problème : collection introuvable après le redémarrage

```bash
# Vérifier que la persistance est activée
curl http://localhost:8000/api/v1/collections
# Si c'est vide, IS_PERSISTENT n'a pas été défini ou le volume n'a pas été monté
```

***

## Liens

* **GitHub**: <https://github.com/chroma-core/chroma>
* **Documentation officielle**: <https://docs.trychroma.com>
* **Docker Hub**: <https://hub.docker.com/r/chromadb/chroma>
* **PyPI**: <https://pypi.org/project/chromadb>
* **Discord**: <https://discord.gg/MMeYNTmh3x>
* **la place de marché CLORE.AI**: <https://clore.ai/marketplace>

***

## Recommandations GPU Clore.ai

| Cas d’utilisation       | GPU recommandé   | Coût estimé sur Clore.ai |
| ----------------------- | ---------------- | ------------------------ |
| Développement/Test      | RTX 3090 (24 Go) | 0,07–0,21 $/gpu/h        |
| RAG de production       | RTX 3090 (24 Go) | 0,07–0,21 $/gpu/h        |
| Embeddings à haut débit | RTX 4090 (24 Go) | 0,14–0,42 $/gpu/h        |

> 💡 Tous les exemples de ce guide peuvent être déployés sur [Clore.ai](https://clore.ai/marketplace) des serveurs GPU. Parcourez les GPU disponibles et louez à l'heure — sans engagement, accès root complet.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-fr/rag-et-bases-de-donnees-vectorielles/chromadb.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.