Chroma : Guide complet base données vectorielle

Chroma est une base de données vectorielle open-source développée en Python, conçue pour simplifier l’implémentation de la recherche sémantique et des applications d’intelligence artificielle. Cette solution se distingue par sa facilité d’utilisation et sa capacité à évoluer du prototype à la production sans migration complexe.

Pour comprendre les concepts fondamentaux des bases de données vectorielles, consultez mon guide détaillé sur les bases de données vectorielles.

Chroma s’intègre naturellement dans les workflows modernes d’intelligence artificielle et de machine learning, particulièrement pour les applications de traitement du langage naturel et d’apprentissage automatique :

• RAG (Retrieval Augmented Generation) : Base de connaissances pour les LLM
• Recherche sémantique : Moteurs de recherche intelligents
• Systèmes de recommandation : Suggestions basées sur la similarité
• Analyse de sentiment : Classification et clustering de contenu

Pourquoi choisir Chroma ?

Chroma répond aux besoins croissants des développeurs qui souhaitent intégrer rapidement des fonctionnalités de recherche sémantique dans leurs applications. Ses points forts incluent :

• Installation simplifiée : Une seule commande pip pour commencer
• Mode embedded : Fonctionne directement dans votre application Python
• Gestion automatique des embeddings : Génération de vecteurs transparente
• Métadonnées riches : Filtrage et organisation avancés des données
• Écosystème IA : Intégration native avec LangChain, LlamaIndex et OpenAI

Parmi les points forts de Chroma, on trouve trois modes de déploiement adaptés à différents besoins :

• Mode in-memory : Idéal pour le développement et les tests rapides, les données restent en mémoire.
• Mode persistant : Stockage sur disque local pour les applications standalone et le développement.
• Mode serveur : Architecture client-serveur pour les environnements de production et les équipes.

La suite de ce guide vous accompagnera dans l’installation, la configuration et l’utilisation avancée de Chroma pour vos projets d’intelligence artificielle.

Installation et configuration de l’environnement

Cette section vous guide étape par étape pour installer et configurer Chroma sur votre système. Nous couvrirons tous les prérequis nécessaires et les différentes méthodes d’installation selon vos besoins.

Prérequis système

Avant d’installer Chroma, assurez-vous que votre système répond aux exigences minimales :

• Python 3.8 ou supérieur (Python 3.9+ recommandé)
• 4 GB de RAM minimum (8 GB recommandés pour les gros volumes)
• Système d’exploitation : Windows, macOS, ou Linux
• Connexion internet pour télécharger les dépendances

Vérification de la version Python

Ouvrez votre terminal et vérifiez votre version de Python :

# Vérifier la version de Python installée
python --version
# ou sur certains systèmes
python3 --version

Si Python n’est pas installé ou que la version est antérieure à 3.8, installez une version récente depuis python.org ↗.

Création d’un environnement virtuel

Pour éviter les conflits entre les dépendances, créez un environnement virtuel dédié à votre projet Chroma :

# Créer un environnement virtuel nommé 'Chroma-env'
python -m venv Chroma-env

# Activer l'environnement virtuel
# Sur Linux/macOS :
source Chroma-env/bin/activate

# Sur Windows :
Chroma-env\Scripts\activate

Votre terminal devrait maintenant afficher (Chroma-env) au début de la ligne de commande, indiquant que l’environnement virtuel est actif.

Installation de Chroma

Vous pouvez installer Chroma via le gestionnaire de paquets pip. Deux méthodes sont disponibles selon vos besoins :

• Méthode 1 : Installation standard avec pip : L’installation la plus simple utilise le gestionnaire de paquets pip :

  # Mettre à jour pip vers la dernière version
  pip install --upgrade pip
  
  # Installer Chroma avec les dépendances de base
  pip install Chroma

• Méthode 2 : Installation avec dépendances optionnelles : Pour bénéficier de toutes les fonctionnalités, installez Chroma avec les extensions :

  # Installation complète avec support des modèles d'embeddings
  pip install "Chroma[all]"
  
  # Ou installation sélective selon vos besoins
  pip install "Chroma[server]"     # Mode serveur
  pip install "Chroma[openai]"     # Intégration OpenAI
  pip install "Chroma[sentence]"   # Modèles Sentence Transformers

Vérification de l’installation

Testons maintenant que Chroma est correctement installé :

# Créer un fichier test_Chroma.py
import Chroma

# Afficher la version installée
print(f"Chroma version: {Chroma.__version__}")

# Créer un client Chroma en mode in-memory
client = Chroma.Client()

print("✅ Chroma installé et fonctionnel !")

Exécutez ce script pour vérifier l’installation :

python test_Chroma.py

Configuration des modes de fonctionnement

Chroma propose trois modes de configuration selon vos besoins.

• Mode 1 : In-Memory (Développement) : Le mode le plus simple pour débuter, les données restent en mémoire :

  import Chroma
  
  # Client en mémoire - données perdues à l'arrêt
  client = Chroma.Client()
  
  # Créer une collection de test
  collection = client.create_collection("test-collection")
  print("Mode in-memory configuré")

• Mode 2 : Persistant (Local) : Pour sauvegarder vos données sur le disque local :

  import Chroma
  
  # Client avec persistance sur disque
  client = Chroma.PersistentClient(path="./Chroma-data")
  
  # Les données seront sauvées dans le dossier ./Chroma-data
  collection = client.get_or_create_collection("ma-collection")
  print("Mode persistant configuré")

• Mode 3 : Serveur (Production) : Pour déployer Chroma comme service séparé :

  # Installer le serveur Chroma
  pip install "Chroma[server]"
  
  # Démarrer le serveur sur le port 8000
  chroma run --host 0.0.0.0 --port 8000 --path ./Chroma-server-data

  Puis connectez-vous depuis votre application :

  import Chroma
  
  # Client connecté au serveur Chroma
  client = Chroma.HttpClient(host='localhost', port=8000)
  
  collection = client.get_or_create_collection("collection-serveur")
  print("Mode serveur configuré")

Configuration des variables d’environnement

Pour faciliter la gestion des configurations, créez un fichier .env :

# Fichier .env
CHROMA_SERVER_HOST=localhost
CHROMA_SERVER_PORT=8000
CHROMA_PERSIST_DIRECTORY=./Chroma-data
CHROMA_SERVER_AUTH_CREDENTIALS=your-api-key

Chargez ces variables dans votre code Python :

import os
from dotenv import load_dotenv
import Chroma

# Charger les variables d'environnement
load_dotenv()

# Configuration basée sur les variables d'environnement
if os.getenv('CHROMA_SERVER_HOST'):
    client = Chroma.HttpClient(
        host=os.getenv('CHROMA_SERVER_HOST'),
        port=int(os.getenv('CHROMA_SERVER_PORT', 8000))
    )
else:
    client = Chroma.PersistentClient(
        path=os.getenv('CHROMA_PERSIST_DIRECTORY', './Chroma-data')
    )

Création et gestion des collections Chroma

Une collection dans Chroma est similaire à une table dans une base de données relationnelle, mais optimisée pour les opérations vectorielles. Chaque collection contient :

• Documents : Le texte original ou les données sources
• Embeddings : Les représentations vectorielles des documents
• Métadonnées : Informations structurées associées (tags, dates, etc.)
• IDs : Identifiants uniques pour chaque élément

Création de votre première collection

Commençons par créer une collection simple :

import Chroma

# Initialiser le client Chroma
client = Chroma.PersistentClient(path="./ma-base-vectorielle")

# Créer une nouvelle collection
collection = client.create_collection(
    name="documents-entreprise",
    metadata={"description": "Documents internes de l'entreprise"}
)

print(f"Collection créée : {collection.name}")
print(f"Nombre d'éléments : {collection.count()}")

Pour des besoins spécifiques, vous pouvez configurer votre collection avec des paramètres personnalisés :

import Chroma
from Chroma.config import Settings

# Configuration personnalisée du client
client = Chroma.PersistentClient(
    path="./Chroma-advanced",
    settings=Settings(
        chroma_db_impl="duckdb+parquet",  # Backend de stockage
        persist_directory="./Chroma-advanced"
    )
)

# Créer une collection avec embedding function personnalisée
collection = client.create_collection(
    name="articles-blog",
    metadata={
        "description": "Articles de blog avec recherche sémantique",
        "version": "1.0",
        "created_by": "admin"
    },
    embedding_function=Chroma.utils.embedding_functions.SentenceTransformerEmbeddingFunction(
        model_name="all-MiniLM-L6-v2"
    )
)

Gestion des collections existantes

Bien sûr, vous pouvez gérer vos collections existantes :

Lister toutes les collections

# Obtenir la liste de toutes les collections
collections = client.list_collections()

print("Collections disponibles :")
for coll in collections:
    print(f"- {coll.name} : {coll.count()} éléments")
    print(f"  Métadonnées : {coll.metadata}")

Récupérer une collection existante

# Récupérer une collection existante (erreur si n'existe pas)
collection = client.get_collection(name="documents-entreprise")

# Récupérer ou créer si n'existe pas
collection = client.get_or_create_collection(
    name="documents-entreprise",
    metadata={"description": "Documents internes de l'entreprise"}
)

Supprimer une collection

# Supprimer une collection (attention : action irréversible)
client.delete_collection(name="collection-obsolete")

# Vérification de sécurité avant suppression
collection_name = "test-collection"
if collection_name in [c.name for c in client.list_collections()]:
    confirm = input(f"Supprimer la collection '{collection_name}' ? (oui/non): ")
    if confirm.lower() == "oui":
        client.delete_collection(name=collection_name)
        print(f"Collection '{collection_name}' supprimée")

Configuration des fonctions d’embedding

Les fonctions d’embedding transforment vos textes en vecteurs numériques que Chroma peut comprendre et comparer. Cette section vous explique comment choisir et configurer le modèle le plus adapté à vos besoins.

Chaque modèle d’embedding a ses spécificités :

• Taille du modèle : Plus petit = plus rapide, plus grand = plus précis
• Langue supportée : Certains modèles sont optimisés pour le français
• Domaine d’application : Texte général, code, domaines spécialisés
• Coût : Modèles gratuits locaux vs API payantes

Chroma utilise par défaut le modèle all-MiniLM-L6-v2 si vous ne spécifiez rien. Ce modèle offre un bon compromis entre performance et rapidité :

# Chroma utilise par défaut le modèle all-MiniLM-L6-v2
# - Taille : 22 MB (compact et rapide)
# - Dimensions : 384 (économe en mémoire)
# - Langues : Principalement anglais, fonctionnel en français
collection = client.create_collection(name="collection-defaut")

# Les embeddings sont générés automatiquement à l'ajout
collection.add(
    documents=["Ceci est mon premier document", "Voici un second texte"],
    ids=["doc1", "doc2"]
)

print("✅ Embeddings générés automatiquement avec le modèle par défaut")

Pour du contenu en français ou multilingue, utilisez des modèles Sentence Transformers spécialisés :

from Chroma.utils.embedding_functions import SentenceTransformerEmbeddingFunction

# Modèle multilingue optimisé pour le français
# - Supporte 15+ langues dont le français
# - Dimensions : 512 (plus riche sémantiquement)
# - Idéal pour : contenu multilingue, recherche cross-lingue
embedding_function = SentenceTransformerEmbeddingFunction(
    model_name="distiluse-base-multilingual-cased"
)

collection = client.create_collection(
    name="documents-francais",
    embedding_function=embedding_function
)

print("✅ Collection configurée avec modèle multilingue")

# Alternative pour contenu technique français
embedding_function_tech = SentenceTransformerEmbeddingFunction(
    model_name="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
)

Configuration avec OpenAI

Les modèles OpenAI offrent une bonne qualité d’embedding, mais nécessitent une API payante :

from Chroma.utils.embedding_functions import OpenAIEmbeddingFunction

# Configuration OpenAI (nécessite une clé API valide)
# - text-embedding-3-small : 1536 dimensions, plus économique
# - text-embedding-3-large : 3072 dimensions, qualité maximale
openai_ef = OpenAIEmbeddingFunction(
    api_key="votre-cle-api-openai",  # Remplacer par votre vraie clé
    model_name="text-embedding-3-small"  # ou "text-embedding-3-large"
)

collection = client.create_collection(
    name="documents-openai",
    embedding_function=openai_ef
)

print("✅ Collection configurée avec embeddings OpenAI")

Synthèse sur le choix des modèles d’embedding

Modèle	Langues	Dimensions	Idéal pour
all-MiniLM-L6-v2	EN/FR	384	Performances générales
distiluse-base-multilingual-cased	Multi	512	Contenu multilingue
OpenAI text-embedding-3-small	Multi	1536	Qualité cloud, usage payant

Ajout de données dans les collections

Maintenant que votre environnement Chroma est configuré, explorons la création de collections vectorielles pour organiser vos données.

Les métadonnées permettent de structurer et filtrer vos documents lors des recherches. Les IDs assurent l’unicité et facilitent les mises à jour.

Ajout simple de documents

Pour ajouter des documents, utilisez la méthode add() de la collection. Voici un exemple :

# Ajouter des documents avec génération automatique d'embeddings
collection.add(
    documents=[
        "Chroma est une base de données vectorielle performante",
        "La recherche sémantique améliore l'expérience utilisateur",
        "Les embeddings capturent le sens des textes"
    ],
    ids=["doc_1", "doc_2", "doc_3"]
)

print(f"Collection contient maintenant {collection.count()} documents")

Ajout avec métadonnées

Pour enrichir vos documents, ajoutez des métadonnées structurées :

# Ajouter des documents avec métadonnées riches
collection.add(
    documents=[
        "Guide d'installation de Chroma pour débutants",
        "Optimisation des performances Chroma en production",
        "Intégration Chroma avec LangChain"
    ],
    metadatas=[
        {"category": "tutorial", "level": "beginner", "language": "fr", "topic": "installation", "framework": "python"},
        {"category": "optimization", "level": "advanced", "language": "fr", "topic": "performance", "environment": "production"}
    ],
    ids=["guide_install", "guide_perf", "guide_integration"]
)

Ajout par lots (batch)

Pour de gros volumes, utilisez l’ajout par lots :

# Préparer des données par lots
documents_batch = []
metadatas_batch = []
ids_batch = []

for i in range(1000):
    documents_batch.append(f"Document d'exemple numéro {i}")
    metadatas_batch.append({"batch": "1", "index": i})
    ids_batch.append(f"batch_doc_{i}")

# Ajouter par lots de 100
batch_size = 100
for i in range(0, len(documents_batch), batch_size):
    batch_end = min(i + batch_size, len(documents_batch))

    collection.add(
        documents=documents_batch[i:batch_end],
        metadatas=metadatas_batch[i:batch_end],
        ids=ids_batch[i:batch_end]
    )

    print(f"Ajouté batch {i//batch_size + 1}: documents {i} à {batch_end-1}")

Inspection et statistiques des collections

Vous pouvez facilement inspecter le contenu et les statistiques de vos collections pour mieux comprendre vos données.

Par exemple, pour obtenir un aperçu rapide :

# Statistiques générales
print(f"Nom de la collection : {collection.name}")
print(f"Nombre total d'éléments : {collection.count()}")
print(f"Métadonnées : {collection.metadata}")

# Aperçu des données
sample = collection.peek(limit=5)
print(f"Échantillon de {len(sample['ids'])} éléments :")
for i, doc_id in enumerate(sample['ids']):
    print(f"- ID: {doc_id}")
    print(f"  Document: {sample['documents'][i][:100]}...")
    print(f"  Métadonnées: {sample['metadatas'][i]}")

Autre exemple :

# Récupérer des documents par ID
results = collection.get(
    ids=["doc_1", "doc_2"],
    include=["documents", "metadatas", "embeddings"]
)

# Récupérer avec filtrage
filtered_results = collection.get(
    where={"category": "tutorial"},
    limit=10,
    include=["documents", "metadatas"]
)

print(f"Trouvé {len(filtered_results['ids'])} tutoriels")

Mise à jour et suppression de données

Vous pouvez modifier ou supprimer des documents existants dans une collection.

Pour mettre à jour un document, utilisez la méthode update() en fournissant l’ID de l’élément à modifier :

# Mettre à jour un document existant
collection.update(
    ids=["doc_1"],
    documents=["Chroma est une base de données vectorielle très performante"],
    metadatas=[{"category": "updated", "version": "2.0"}]
)

Pour supprimer des documents, utilisez la méthode delete() avec les IDs ou des filtres :

# Supprimer des documents par ID
collection.delete(ids=["doc_obsolete", "doc_temporaire"])

# Supprimer avec filtrage par métadonnées
collection.delete(where={"category": "draft"})

# Vider complètement une collection
# collection.delete()  # Attention : supprime tout !

Bonnes pratiques pour la gestion des collections

Pour maintenir des collections efficaces et performantes, suivez ces recommandations :

• Nommage clair : Utilisez des noms explicites pour vos collections et métadonnées.

  # Noms explicites et organisés
  collections_config = {
      "docs_tech_fr": {"lang": "fr", "type": "technical"},
      "docs_user_en": {"lang": "en", "type": "user_guide"},
      "faq_support": {"lang": "multilingual", "type": "support"}
  }
  
  for name, config in collections_config.items():
      collection = client.get_or_create_collection(
          name=name,
          metadata=config
      )

• Validation des données : Vérifiez la cohérence des documents, métadonnées et IDs avant l’ajout.

• Indexation régulière : Pour les gros volumes, réindexez périodiquement pour optimiser les performances.

Exemple complet : recherche de documents internes

Dans cette section, nous allons mettre en œuvre un cas d’usage complet de Chroma pour la recherche sémantique. Cet exemple simule une base de documents internes à une entreprise.

🎯 Objectif

Créer une base vectorielle locale avec Chroma, y insérer plusieurs documents, puis effectuer une recherche sémantique pour retrouver les contenus les plus pertinents par similarité.

1. Initialisation de l’environnement

import Chroma

# Création du client avec stockage persistant
client = Chroma.PersistentClient(path="./docs-internes-db")

# Création de la collection
collection = client.get_or_create_collection(
    name="documents-internes",
    metadata={"description": "Docs RH, techniques, et marketing"}
)

2. Insertion de documents

# Ajout de plusieurs documents avec métadonnées
collection.add(
    documents=[
        "La politique de télétravail 2025 est mise à jour avec de nouvelles règles.",
        "Le rapport technique sur la migration vers Kubernetes est disponible.",
        "Les prévisions marketing pour le T3 sont disponibles sur l'intranet.",
        "La documentation de l'API interne a été mise à jour avec les derniers endpoints.",
        "La checklist de sécurité des serveurs est obligatoire avant chaque déploiement."
    ],
    metadatas=[
        {"type": "RH", "niveau": "interne"},
        {"type": "technique", "niveau": "confidentiel"},
        {"type": "marketing", "niveau": "interne"},
        {"type": "technique", "niveau": "interne"},
        {"type": "technique", "niveau": "critique"}
    ],
    ids=["doc1", "doc2", "doc3", "doc4", "doc5"]
)

3. Recherche sémantique

# Requête utilisateur
requete = "documentation Kubernetes interne"

# Recherche dans la collection
resultats = collection.query(
    query_texts=[requete],
    n_results=3,
    include=["documents", "metadatas", "distances"]
)

# Affichage des résultats
for i, doc in enumerate(resultats['documents'][0]):
    print(f"Résultat {i+1} :")
    print(f"📝 Document : {doc}")
    print(f"📊 Métadonnées : {resultats['metadatas'][0][i]}")
    print(f"📐 Distance : {resultats['distances'][0][i]:.4f}")
    print("---")

Le moteur vectoriel retournera les documents les plus proches sémantiquement de la requête, même si les mots exacts ne sont pas présents.

Exemple :

Résultat 1 :
📝 Document : Le rapport technique sur la migration vers Kubernetes est disponible.
📊 Métadonnées : {'type': 'technique', 'niveau': 'confidentiel'}
📐 Distance : 0.1953
---

Résolution des problèmes courants

Erreur : “No module named ‘Chroma’”

Solution : Vérifiez que l’environnement virtuel est activé et que Chroma est installé :

# Réactiver l'environnement virtuel
source Chroma-env/bin/activate

# Réinstaller Chroma
pip install Chroma

Erreur de permissions sur Windows

Solution : Exécutez votre terminal en tant qu’administrateur ou utilisez l’option --user :

pip install --user Chroma

Problème de mémoire insuffisante

Solution : Augmentez la mémoire virtuelle ou utilisez un serveur dédié pour les gros volumes de données.

Conclusion

Vous disposez désormais de toutes les clés pour exploiter Chroma dans vos projets Python. Que ce soit pour de la recherche sémantique, des systèmes RAG ou des moteurs de recommandation, cette base vectorielle open-source offre un excellent compromis entre simplicité, performance et flexibilité.

Pour aller plus loin, explorez les ressources suivantes :

• Documentation officielle Chroma ↗
• Modèles Sentence Transformers ↗
• API OpenAI Embeddings ↗
• Intégration LangChain ↗