> 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 ChromaDB est le **principal base de données vectorielle open-source** conçue 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 masque la complexité de la recherche de similarité vectorielle, vous permettant de vous concentrer sur la création d'applications d'IA. Elle prend en charge à la fois un mode en mémoire pour le développement et un mode serveur persistant pour les déploiements en production, avec un support Docker pour un déploiement facile sur les serveurs GPU Clore.ai. Principales fonctionnalités : * 🚀 **API Python/JavaScript simple** — commencez 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 pour OpenAI, Cohere, sentence-transformers * 🏗️ **Multi-tenant** — collections pour organiser différents jeux de données * 🔌 **API REST** — interface HTTP agnostique au langage * ⚡ **Rapide** — index HNSW pour la recherche approximative du plus proche voisin * 🔗 **Intégration native LangChain/LlamaIndex** — intégration de première classe {% hint style="success" %} Tous les exemples peuvent être exécutés sur des serveurs GPU loués via [CLORE.AI Marketplace](https://clore.ai/marketplace). {% endhint %} *** ## Exigences serveur | Paramètre | Minimum | Recommandé | | --------- | ------------------------------------- | ---------------------------------------------- | | GPU | N'importe quel GPU NVIDIA (optionnel) | NVIDIA RTX 3080+ (pour les embeddings) | | VRAM | Non requis pour ChromaDB | 8–16 Go (pour les modèles d'embeddings 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) | | OS | 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 fonctionne 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 un GPU. {% endhint %} *** ## Déploiement rapide sur CLORE.AI ### 1. Trouvez un serveur adapté Aller à [CLORE.AI Marketplace](https://clore.ai/marketplace) et choisissez : * **CPU uniquement** pour le serveur ChromaDB + API (stocker 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 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://:8000/api/v1/heartbeat # Attendu : {"nanosecond heartbeat": } ``` *** ## Configuration étape par étape ### Étape 1 : Connectez-vous en SSH à votre serveur ```bash ssh root@ -p ``` ### É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 fonctionne ```bash # Vérifier la santé 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="", port=8000) print(f"Version de ChromaDB : {client.get_version()}") print(f"Heartbeat : {client.heartbeat()}") ``` ### Étape 7 : (Optionnel) Activer l'authentification ```bash # Créer les identifiants d'auth echo "admin:$2y$12$$(openssl rand -hex 16)" > /workspace/chromadb/auth.txt # Exécuter avec l'auth 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 magasin vectoriel ```python import chromadb from chromadb.utils import embedding_functions # Se connecter à ChromaDB sur un serveur Clore.ai client = chromadb.HttpClient( host="", 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é décentralisée de GPU pour les charges de travail 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 tout framework d'IA.", "Les tarifs sur Clore.ai sont compétitifs par rapport à AWS et GCP.", "La place de marché Clore.ai dispose de milliers de serveurs GPU dans le monde.", "Vous pouvez déployer PyTorch, TensorFlow, JAX et d'autres frameworks ML.", "Clore.ai propose des tarifs 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="", 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 de machine learning sont disponibles ?", "Parlez-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="", port=8000) openai_client = OpenAI(api_key="votre-cle-openai") # 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"✓ Ajouté {len(texts)} documents. 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 la 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 n'est 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é GPU avec plus de 45 000 utilisateurs.", "Clore.ai prend en charge le déploiement de charges de travail via Docker.", "Les serveurs GPU sur Clore.ai vont du GTX 1080 au H100.", "Vous pouvez déployer des applications 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="", port=8000) embedding_fn = embedding_functions.SentenceTransformerEmbeddingFunction( model_name="all-mpnet-base-v2" # Embeddings de meilleure qualité ) # Créer des collections séparées 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 serveurs GPU"], ids=["tech_001", "tech_002"], metadatas=[{"type": "guide", "version": "v2"}, {"type": "config"}] ) collections["faq"].add( documents=["Q : Comment payer ? R : Via cryptomonnaie.", "Q : Quels GPU ? R : 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 par métadonnées ```python import chromadb client = chromadb.HttpClient(host="", port=8000) collection = client.get_collection("technical_docs") # Ajouter des documents avec des métadonnées riches collection.add( documents=[ "Guide : Exécution de PyTorch sur des clusters GPU NVIDIA A100", "Guide : Entraînement distribué TensorFlow sur RTX 4090", "Tutoriel : Fine-tuning de LLM avec LoRA sur GPU", "Référence : matrice de compatibilité CUDA 12.1", "Guide : Réseautage Docker pour 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}, ] ) # Requête avec filtre de métadonnées results = collection.query( query_texts=["Guide d'entraînement GPU"], n_results=3, where={"type": "guide"}, # Ne retourner 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 # cache de 2 Go restart: unless-stopped healthcheck : test : ["CMD", "curl", "-f", "http://localhost:8000/api/v1/heartbeat"] intervalle : 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` | Niveau de verbosité des logs | | `CHROMA_MEMORY_LIMIT_BYTES` | Aucune | Mémoire maximale pour le cache de segments | | `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'embeddings | Modèle | Dimensions | Vitesse | Qualité | GPU requis | | ------------------------ | ---------- | ------- | --------- | -------------- | | `all-MiniLM-L6-v2` | 384 | Rapide | Bonne | Non | | `all-mpnet-base-v2` | 768 | Moyen | Meilleur | Optionnel | | `text-embedding-3-small` | 1536 | Rapide | Excellent | API uniquement | | `BAAI/bge-large-en-v1.5` | 1024 | Moyen | Meilleur | Oui | ### 2. Inserations en lot pour la vitesse ```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. Tuning 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 usage local ```python # Pour le développement directement sur le serveur Clore.ai import chromadb client = chromadb.PersistentClient(path="/workspace/chromadb/data") # Pas de serveur nécessaire, plus rapide pour une utilisation mono-processus ``` *** ## 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 logs 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 mémoire insuffisante ```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'Modèle d'embeddings sur : {model.device}') " ``` ### Problème : Collection introuvable après redémarrage ```bash # Vérifier que la persistance est activée curl http://localhost:8000/api/v1/collections # Si vide, IS_PERSISTENT n'a pas été défini ou le volume n'a pas été monté ``` *** ## Liens * **GitHub**: * **Documentation officielle**: * **Docker Hub**: * **PyPI**: * **Discord**: * **CLORE.AI Marketplace**: *** ## Recommandations GPU Clore.ai | Cas d’utilisation | GPU recommandé | Coût estimé sur Clore.ai | | ----------------------- | --------------- | ------------------------ | | Développement/Test | RTX 3090 (24GB) | \~$0.12/gpu/hr | | RAG en production | RTX 3090 (24GB) | \~$0.12/gpu/hr | | Embeddings à haut débit | RTX 4090 (24GB) | \~$0.70/gpu/hr | > 💡 Tous les exemples de ce guide peuvent être déployés sur [Clore.ai](https://clore.ai/marketplace) serveurs GPU. Parcourez les GPU disponibles et louez à l’heure — sans engagement, avec 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: ``` GET https://docs.clore.ai/guides/guides_v2-fr/rag-et-bases-de-donnees-vectorielles/chromadb.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.