Intégrer Chroma dans une stack existante
Client, HNSW, ingestion incrémentale, migration cloud : le chemin complet pour brancher Chroma sur une stack existante sans réindexer ton corpus.
Chroma 1.5.9 est sorti sur PyPI le 5 mai 2026, et la vraie question n'est plus « faut-il une base vectorielle », mais « comment la brancher sans casser ce qui tourne déjà ». Bonne nouvelle : dans 80 % des cas, l'intégration tient en une classe de client à remplacer, pas en une refonte.
Mauvaise nouvelle : le mode de client par défaut est aussi le plus gros piège de la bibliothèque. Tu le choisis en trois minutes, tu le paies pendant six mois.
Chroma complète ta base, il ne la remplace pas
Chroma stocke des vecteurs et des métadonnées, rien de plus. Il n'a ni transactions relationnelles, ni contraintes d'intégrité, ni jointures. Le placer au mauvais endroit dans ton architecture est la première cause d'échec d'intégration.
La règle est simple : ton Postgres (ou MySQL, ou Mongo) reste la source de vérité métier. Chroma devient l'index de similarité dérivé, reconstructible à tout moment depuis la base principale.
| Donnée | Où elle vit | Pourquoi |
|---|---|---|
| Utilisateurs, commandes, droits | Base relationnelle | Transactions, contraintes, sauvegardes éprouvées |
| Vecteurs d'embeddings | Chroma | Recherche ANN, filtres métadonnées |
| Texte source des chunks | Base relationnelle | Ré-indexation sans repayer d'inférence |
| Identifiants de corrélation | Les deux | L'id Chroma doit pointer vers une ligne réelle |
Concrètement : si ton index Chroma disparaît ce soir, tu dois pouvoir le reconstruire demain matin avec un script qui relit ta table documents. Si ce n'est pas le cas, tu as mis la source de vérité du mauvais côté.
Ta clé d'id Chroma doit être déterministe, pas un UUID aléatoire généré à l'ingestion. C'est ce qui rend la ré-indexation idempotente — j'y reviens plus bas.
Choisis ton client avant d'écrire une seule ligne de métier
Chroma expose quatre clients, et chacun impose une topologie différente. La documentation officielle les liste dans Chroma Clients, mais le tableau ci-dessous te donne le critère de choix réel.
| Client | Persistance | Multi-processus | Usage légitime |
|---|---|---|---|
EphemeralClient | Aucune | Non | Notebook, tests unitaires |
PersistentClient | SQLite local | Non (verrou exclusif) | CLI, worker unique, script batch |
HttpClient | Serveur Chroma | Oui | API web, plusieurs réplicas applicatifs |
CloudClient | Chroma Cloud | Oui, managé | Équipe sans envie d'exploiter un serveur |
import chromadb
# Développement : rien à nettoyer après le test
ephemeral = chromadb.EphemeralClient()
# Script batch sur une seule machine
local = chromadb.PersistentClient(path="/data/chroma")
# API web avec plusieurs workers : serveur obligatoire
http = chromadb.HttpClient(host="chroma", port=8000)
# Chroma Cloud : tenant et base résolus depuis la clé si elle est scopée
cloud = chromadb.CloudClient(
tenant="mon-tenant",
database="production",
api_key=os.environ["CHROMA_API_KEY"],
)L'API des collections est identique dans les quatre cas. collection.query(), collection.add(), les filtres where et where_document ne changent pas d'un mode à l'autre.
C'est précisément pour ça que le mauvais choix passe inaperçu en développement : tout marche sur ton laptop, et tout casse au premier déploiement à deux réplicas.
Le piège du PersistentClient en production
PersistentClient verrouille son répertoire de données au niveau fichier. Deux processus Python pointés sur le même chemin ne partagent pas l'index : le second lit des données périmées, ou corrompt la base SQLite sous-jacente.
Le scénario classique : une API FastAPI lancée avec uvicorn main:app --workers 4. Chaque worker instancie son propre PersistentClient sur le même volume. Quatre index concurrents sur quatre descripteurs de fichiers différents.
La version serveur règle le problème parce qu'un seul processus possède le stockage et que tous les autres passent par HTTP.
# docker-compose.yml
services:
chroma:
image: chromadb/chroma:latest
environment:
CHROMA_SERVER_AUTHN_PROVIDER: "chromadb.auth.token_authn.TokenAuthenticationServerProvider"
CHROMA_SERVER_AUTHN_CREDENTIALS: "${CHROMA_TOKEN}"
CHROMA_AUTH_TOKEN_TRANSPORT_HEADER: "X-Chroma-Token"
volumes:
- chroma_data:/chroma/chroma
ports:
- "8000:8000" # jamais exposé publiquement tel quel
volumes:
chroma_data:from chromadb.config import Settings
client = chromadb.HttpClient(
host="chroma",
port=8000,
settings=Settings(
chroma_client_auth_provider="chromadb.auth.token.TokenAuthClientProvider",
chroma_client_auth_credentials=os.environ["CHROMA_TOKEN"],
),
)Sans authentification, n'importe quel processus du réseau Docker lit et supprime tes collections. Le jeton ci-dessus n'est pas optionnel dès que le port 8000 sort de localhost.
Sur un montage Docker, monte un volume nommé plutôt qu'un bind mount sur le code applicatif : un docker compose down -v mal placé efface l'index.
Ingestion incrémentale : ne réindexe pas ce que tu as déjà
Le coût d'une intégration Chroma n'est pas la recherche, c'est l'ingestion. Si tu re-embeddes tout ton corpus à chaque déploiement, tu paies l'inférence N fois pour rien.
La parade tient en deux principes : des id déterministes dérivés du contenu, et des métadonnées qui te permettent de filtrer côté Chroma sans repasser par la base.
import hashlib, chromadb, psycopg
client = chromadb.HttpClient(host="chroma", port=8000)
collection = client.get_or_create_collection(
name="docs",
metadata={"hnsw:space": "cosine"},
)
def chunk_id(doc_id: int, chunk_index: int, text: str) -> str:
digest = hashlib.sha256(text.encode("utf-8")).hexdigest()[:16]
return f"{doc_id}:{chunk_index}:{digest}"
def ingest(rows, embed_batch):
ids = [chunk_id(r["doc_id"], r["index"], r["text"]) for r in rows]
existing = set(collection.get(ids=ids, include=[])["ids"])
todo = [r for r, i in zip(rows, ids) if i not in existing]
if not todo:
return 0
for start in range(0, len(todo), 256):
batch = todo[start:start + 256]
vectors = embed_batch([r["text"] for r in batch])
collection.upsert(
ids=[chunk_id(r["doc_id"], r["index"], r["text"]) for r in batch],
embeddings=vectors,
documents=[r["text"] for r in batch],
metadatas=[{"doc_id": r["doc_id"], "lang": r["lang"], "updated": r["updated_at"]} for r in batch],
)
return len(todo)Le hash dans l'id fait le travail : si le texte d'un chunk change, l'identifiant change, et le upsert ajoute la nouvelle version au lieu de laisser l'ancienne en place. Si le texte est identique, tu économises l'appel d'embedding.
Le paramètre embeddings= est important : il permet d'injecter des vecteurs pré-calculés en lot, hors ligne, sans que la bibliothèque appelle elle-même une fonction d'embedding.
Deux fonctions récentes améliorent vraiment ce pipeline côté filtrage : les tableaux de métadonnées (février 2026) et GroupBy (janvier 2026), qui évite de remonter quinze chunks du même document dans un top-k. Le détail est dans le changelog Chroma.
Un endpoint de recherche dans une API qui existe déjà
Voici l'intégration minimale côté FastAPI. Le client Chroma est créé une fois au démarrage, pas à chaque requête.
from contextlib import asynccontextmanager
import chromadb, os
from fastapi import FastAPI, Query
@asynccontextmanager
async def lifespan(app: FastAPI):
app.state.chroma = chromadb.HttpClient(host="chroma", port=8000)
app.state.docs = app.state.chroma.get_collection("docs")
yield
app.state.chroma = None
app = FastAPI(lifespan=lifespan)
@app.get("/search")
def search(q: str = Query(min_length=3), lang: str | None = None, k: int = 8):
where = {"lang": lang} if lang else None
res = app.state.docs.query(
query_texts=[q],
n_results=k,
where=where,
include=["documents", "metadatas", "distances"],
)
return [
{"id": i, "text": d, "score": 1 - dist, "meta": m}
for i, d, m, dist in zip(
res["ids"][0], res["documents"][0], res["metadatas"][0], res["distances"][0]
)
]Un détail que tout le monde découvre en production : avec hnsw:space = "cosine", distance vaut 1 - similarité. Un score de 0,85 en sortie correspond à 0,15 de distance brute. Afficher la distance telle quelle au front donne l'impression que tes résultats sont mauvais alors qu'ils sont excellents.
Si tu débutes sur ce type de pipeline, la mécanique d'évaluation d'un retrieval est détaillée dans Bien démarrer avec les RAG evaluation : recall@k et MRR, pas seulement la latence.
Fige les paramètres HNSW dès la première ingestion
Chroma indexe avec HNSW, et trois paramètres déterminent ton compromis rappel/latence : M, construction_ef et search_ef. Le point critique, c'est que hnsw:space ne peut plus être modifié après la création de la collection : il faut recréer et tout réingérer.
collection = client.create_collection(
name="docs",
metadata={
"hnsw:space": "cosine", # immuable après création
"hnsw:M": 32, # voisins par nœud
"hnsw:construction_ef": 200, # qualité de construction
"hnsw:search_ef": 128, # qualité de recherche
},
)Les chiffres d'un benchmark VectorDBBench sur 50 000 vecteurs en 1 536 dimensions montrent la forme de la courbe : le rappel atteint 0,9936 avec ef_construction = 64, 0,9966 à 128, puis 0,9979 à 256. Doubler le paramètre une première fois rapporte environ 3 % de rappel, la seconde fois seulement 1,3 %.
Traduction opérationnelle : monter construction_ef de 64 à 128 est presque toujours rentable, le passer à 512 ne l'est presque jamais. Et à l'inverse, les gains de rappel se paient en QPS.
Un point qui bloque beaucoup de tuning : dans Chroma, search_ef ne peut pas être modifié après la création de l'index. Tu dois décider de ta valeur cible avant la première ingestion massive, pas après.
Mesure avant/après, sinon tu intègres à l'aveugle
Une intégration sans mesure ne se défend pas en revue d'architecture. Trois chiffres suffisent, et ils se collectent en une heure.
| Métrique | Comment la mesurer | Seuil d'alerte typique |
|---|---|---|
| Latence p95 de recherche | 200 requêtes réelles chronométrées | > 150 ms en intra-réseau |
| recall@10 | 50 requêtes annotées à la main vs recherche exhaustive | < 0,90 sur ton corpus |
| Dérive de collection | collection.count() comparé à ta table source | Écart > 0,5 % |
Le troisième est le plus sous-estimé. Un job d'ingestion qui plante au milieu ne laisse pas d'erreur visible côté recherche : il laisse simplement des chunks absents, et un retrieval qui répond avec un air convaincu.
Sur les ordres de grandeur, les benchmarks publics situent Chroma autour de 8 ms de latence en requête unique sur un corpus moyen, avec une variance très faible. Sur 100 requêtes concurrentes, la même base passe à environ 23 secondes cumulées là où pgvector tient autour de 9,8 secondes. La conclusion est nette : Chroma gagne en requête isolée, Postgres gagne en concurrence.
Si ta stack tourne déjà sur Postgres, l'extension pgvector est souvent le choix rationnel, parce qu'elle t'évite un second système à sauvegarder et à superviser. Ces arbitrages sont détaillés dans pgvector vs ChromaDB : quand étendre PostgreSQL et quand passer dédié.
Basculer sur Chroma Cloud sans ré-embedder
Le jour où ton PersistentClient devient un point de défaillance unique, la migration ne demande pas de recalculer un seul vecteur. Le chemin officiel est décrit dans la documentation de migration Chroma.
chroma login
chroma copy --from-local --to-cloud --all --db productionLa copie transporte les vecteurs et les métadonnées tels quels. Aucun appel d'inférence, donc aucune dérive silencieuse de tes résultats si un modèle d'embedding a changé de version entre-temps.
Pour un basculement progressif, copie collection par collection et rejoue ta suite de requêtes annotées sur la copie cloud avant de basculer. Côté code, l'opération se limite au constructeur :
# avant
client = chromadb.PersistentClient(path="/data/chroma")
# après
client = chromadb.CloudClient(
cloud_host="europe-west1.gcp.trychroma.com",
cloud_port=443,
api_key=os.environ["CHROMA_API_KEY"],
)La région européenne est disponible depuis avril 2026, ce qui règle la question du stockage hors UE pour beaucoup d'équipes. Tous les collection.query() restent inchangés.
Questions fréquentes
Faut-il réindexer les embeddings déjà calculés ?
Non, et c'est même à éviter. Chroma accepte des vecteurs pré-calculés via le paramètre embeddings= de add() et upsert(). Ré-embedder un corpus de 200 000 chunks juste pour changer de base te coûte l'inférence et introduit un risque de dérive si la version du modèle a bougé.
Chroma ou pgvector quand je fais déjà tourner Postgres ?
Reste sur pgvector si tu as besoin de jointures avec tes tables métier, de transactions et d'une seule sauvegarde à gérer. Prends Chroma si ta charge est surtout faite de requêtes isolées peu concurrentes, si tu veux des filtres de métadonnées riches et une mise en route en dix minutes. La bascule coûte plus cher que le choix initial.
Combien de vecteurs avant de quitter le mode persistant ?
Prévois la migration vers 5 à 10 millions de vecteurs. Au-delà, HNSW devient gourmand en RAM, et le stockage de Chroma reste nettement plus volumineux que celui de pgvector pour le même corpus. Surveille collection.count() comme une métrique de capacité, pas comme une décoration.
Et si je dois relire Chroma depuis un LLM agentique ?
Passe par un serveur HTTP authentifié, jamais par un accès direct au dossier de données. Un agent qui hérite d'un chemin de fichier hérite aussi du droit d'effacer l'index. Les garde-fous à poser côté outillage sont traités dans Les bonnes pratiques des LLM en 2026.
Mon avis, tranché : commence avec un vrai serveur Chroma en Docker, même en local. Le coût de mise en place est d'une soirée, il t'évite la réécriture complète que le PersistentClient t'imposera au moment où tu auras le plus besoin de stabilité.