Comment Optimiser l’Utilisation des Tokens avec ChromaDB (Étape par Étape)
Si vous ne faites pas attention à l’utilisation des tokens dans vos requêtes de base de données vectorielle, vous dépensez vos crédits et vos performances plus vite que vous ne le réalisez — alors voici comment optimiser l’utilisation des tokens avec ChromaDB comme si vous vouliez réellement économiser de l’argent et du temps.
Ce que Vous Allez Construire et Pourquoi Cela Compte
Nous construisons une pipeline minimaliste mais efficace qui prend des documents en désordre du monde réel, les stocke dans ChromaDB, et les interroge avec des embeddings OpenAI, tout en réduisant le gaspillage de tokens au maximum.
Prérequis
- Python 3.11+
- pip install chroma-core==0.10.0 (dernière version en mars 2026)
- Clé API OpenAI avec accès aux points de terminaison d’embeddings
- Connaissance de base des bases de données vectorielles et des API de modèles de langage large
Étape 1 : Configurez Votre Environnement ChromaDB
Tout d’abord, vous devez installer et faire fonctionner ChromaDB d’une manière qui s’intègre bien à votre environnement. Chroma-core, le moteur principal de ChromaDB, attire beaucoup d’attention sur GitHub : plus de 26,759 étoiles et 2,140 forks, donc ce n’est pas un simple projet de niche. Cela signifie beaucoup d’aide de la part de la communauté, mais aussi quelques problèmes ouverts inévitables (et ChromaDB en a 513 ouverts en mars 2026).
La dernière version, sous licence Apache-2.0, a été mise à jour le 2026-03-21 — donc elle est activement maintenue, et c’est bien car vous allez fortement vous appuyer sur elle pour gérer vos embeddings de manière judicieuse.
# Installer chroma-core si ce n'est pas déjà fait
pip install chroma-core==0.10.0Configurer un ChromaDB persistant signifie généralement juste exécuter ce petit extrait de code :
from chromadb import Client
client = Client() # Utilise les paramètres par défaut - SQLite + disque local
collection = client.get_or_create_collection(name="mydocs")Pourquoi faire cela en premier ? Parce que chaque autre étape tourne autour de la budgétisation variable des tokens — et la gestion des dépendances de ChromaDB vient en premier.
Problèmes courants : Si vous rencontrez des erreurs comme ModuleNotFoundError, vérifiez vos versions. Les mises à jour de Chroma-core changent souvent les internals, donc se fixer sur une version spécifique évite les plantages aléatoires.
Étape 2 : Chunking du Contenu pour l’Efficacité des Tokens
Vos documents ne sont pas propres et soignés — ils comportent des en-têtes, des tableaux, des notes de bas de page et des éléments indésirables. Alimenter de longues chaînes aux API d’embedding est un moyen sûr de vous priver de tokens. Chaque token compte.
Au lieu de cela, vous segmentez votre contenu intelligemment. Pas trop grand, pas trop petit. Une taille de segment qui correspond ou est légèrement inférieure aux limites de tokens de votre API d’embedding économise beaucoup de ressources de calcul et de coûts.
import tiktoken # Pour le comptage des tokens, le tokenizeur propre à OpenAI
from langchain.text_splitter import RecursiveCharacterTextSplitter
# Initialiser un séparateur pour des segments d'environ ~500 tokens (sécurisé pour les embeddings OpenAI)
splitter = RecursiveCharacterTextSplitter(
chunk_size=500,
chunk_overlap=50,
length_function=lambda text: len(tiktoken.encoding_for_model("text-embedding-3-small").encode(text))
)
def chunk_text(text):
chunks = splitter.split_text(text)
print(f"Divisé en {len(chunks)} segments")
return chunks
# Exemple d'utilisation
doc_text = open("messy_doc.txt").read()
chunks = chunk_text(doc_text)Pourquoi le chunking économise des tokens : Si vous envoyez des documents entiers à l’API d’embedding, vous obtenez d’énormes embeddings mais surtout du bruit — de plus, vous pourriez dépasser les limites de tokens ou déclencher des limites de taux. Des segments petits mais significatifs produisent de manière fiable des embeddings ciblés pour une recherche vectorielle précise.
Erreurs à surveiller : Les segments qui se chevauchent peuvent parfois sembler redondants dans les résultats de recherche — ajustez chunk_overlap en conséquence. Et attention à votre choix de tokenizeur. Si vous ne correspondez pas aux modèles de tokenizeurs, vos comptages de tokens varieront de 20 à 30 %, ruinant ainsi votre plan de budgétisation des tokens.
Étape 3 : Embeddings avec ChromaDB – Optimisez, Ne Blindez Pas Tout
C’est ici que de nombreux développeurs dépassent leur budget de tokens. Alimenter chaque segment par le point de terminaison d’embedding d’OpenAI vous surprend dans votre budget.
Au lieu de cela, vous souhaitez pré-filtrer les segments avant d’embed. Utilisez un filtre de similarité textuelle peu coûteux. Comme une vérification rapide de la TF-IDF, puis n’embed que les 30 à 40 % des meilleurs segments. Cela réduit le stockage, le temps de requête et le coût en tokens.
from sklearn.feature_extraction.text import TfidfVectorizer
import numpy as np
# Une approximation peu coûteuse pour filtrer les segments significatifs avant un embedding coûteux
def filter_chunks(chunks, query, keep_ratio=0.4):
vectorizer = TfidfVectorizer()
X = vectorizer.fit_transform(chunks + [query])
query_vec = X[-1]
chunk_vecs = X[:-1]
similarities = (chunk_vecs @ query_vec.T).toarray().flatten()
threshold = np.quantile(similarities, 1 - keep_ratio)
filtered = [chunk for chunk, sim in zip(chunks, similarities) if sim >= threshold]
print(f"Filtré de {len(chunks)} à {len(filtered)} segments avant l'embedding")
return filtered
chunks_to_embed = filter_chunks(chunks, "Qu'est-ce que l'optimisation de l'utilisation des tokens ?")Maintenant, n’embed que chunks_to_embed dans ChromaDB :
from openai import OpenAI
import chromadb
client = chromadb.Client()
collection = client.get_or_create_collection("mydocs")
embedding_model = OpenAI()
for chunk in chunks_to_embed:
embedding = embedding_model.embeddings.create(input=chunk).data[0].embedding
collection.add(
documents=[chunk],
embeddings=[embedding],
ids=[hash(chunk) % (10 ** 8)] # ID unique mais simple
)Pourquoi cette approche ? Parce que les embeddings sont de grands consommateurs de tokens. Un seul segment de 500 tokens coûte 500 tokens juste pour être vectorisé. Voulez-vous vraiment embed des fragments inutiles ? Non. Filtrez intelligemment et économisez des tokens.
Erreurs que vous pourriez rencontrer : Limitations de taux API. L’insertion par lots de ChromaDB peut aider à atténuer les appels API — plus d’informations ci-dessous.
Étape 4 : Insertion par Lots pour Réduire les Appels API
Ce n’est pas seulement une question de tokens — vous consommez de la latence et finissez par payer plus pour trop d’appels petits. Les insertions par lots tuent deux oiseaux d’un coup : meilleur débit et moins de frappes API redondantes.
Le collection.add de ChromaDB prend en charge plusieurs documents & embeddings à la fois. Regroupez vos segments filtrés en lots de 50 ou 100 pour économiser du temps.
BATCH_SIZE = 50
def batch(iterable, n=1):
l = len(iterable)
for ndx in range(0, l, n):
yield iterable[ndx:min(ndx + n, l)]
for chunk_batch in batch(chunks_to_embed, BATCH_SIZE):
embeddings = [embedding_model.embeddings.create(input=chunk).data[0].embedding for chunk in chunk_batch]
collection.add(
documents=chunk_batch,
embeddings=embeddings,
ids=[hash(chunk) % (10 ** 8) for chunk in chunk_batch]
)
print(f"Indexé {len(chunk_batch)} segments en lot")Pourquoi par lots ? Une requête = un événement de facturation de token et une opération réseau. Ne soyez pas ce développeur qui attend 100 appels API individuels à l’heure.
Attention à :
- Des lots trop grands — plus de 100 par appel peut vous ralentir.
- Des échecs partiels — encapsulez vos appels dans un try/except pour gérer des erreurs intermittentes comme des délais d’attente ou des 429.
Étape 5 : Comptage Intelligent des Tokens Avant les Requêtes — Ne Devinez Pas
Lors de l’exécution de requêtes, vous devez avoir une idée des tokens que l’ensemble du pipeline consomme. Cela est particulièrement crucial si vos requêtes elles-mêmes sont de longs passages ou un mélange de saisie utilisateur et de contexte.
Au lieu d’estimer les comptes de tokens, fiez-vous à tiktoken ou équivalent pour compter exactement les tokens à chaque étape. Ainsi, vous pouvez soit tronquer soit ajuster les entrées à la volée avant d’utiliser cette requête.
def count_tokens(text, model_name="gpt-4o-mini"):
tokenizer = tiktoken.encoding_for_model(model_name)
tokens = tokenizer.encode(text)
return len(tokens)
query = "Expliquez l'optimisation des tokens dans ChromaDB aussi simplement que possible."
tokens_used = count_tokens(query)
print(f"Compte des tokens pour la requête : {tokens_used}")Pourquoi s’en soucier ? Parce que les embeddings d’OpenAI et les complétions de chat ont des limites strictes de tokens. Dépasser 4,096 tokens déclenche généralement une troncature, des erreurs, ou des frais supplémentaires que vous préféreriez éviter.
Erreurs que vous verrez : Le redouté OpenAIError: La longueur maximale de contexte de ce modèle est de 4097 tokens. Gérez ces erreurs en comptant les tokens avant d’envoyer des requêtes et en tronquant les entrées utilisateur ou le contexte en conséquence (détaillé dans la section suivante).
Étape 6 : Tronquage du Contexte et Mise en Cache des Embeddings
Lorsque vous alimentez des documents et l’historique de chat dans votre modèle de langage, le total des tokens utilisés compte énormément. Une erreur courante des débutants est de toujours envoyer votre document entier ou tout l’historique de chat sans discernement. Vous dépassez les limites de tokens en quelques secondes.
Votre meilleure option : tronquer et mettre en cache.
- Mettre en cache les embeddings pour les documents statiques (ne pas ré-embed le même texte)
- Tronquer l’historique de chat intelligemment, en priorisant les saisies importantes récentes
- Utiliser une fenêtre de tokens glissante d’environ ~3,000 tokens pour le contexte dans le chat/complétions
Voici un extrait illustrant la vérification du cache et le tronquage :
embedding_cache = {}
def get_embedding(text):
if text in embedding_cache:
print("Hit dans le cache pour l'embedding")
return embedding_cache[text]
embedding = embedding_model.embeddings.create(input=text).data[0].embedding
embedding_cache[text] = embedding
return embedding
def trim_context(contexts, max_tokens=3000, model_name="gpt-4o-mini"):
trimmed = []
token_count = 0
for c in reversed(contexts): # commencer par le plus récent
tcount = count_tokens(c, model_name)
if (token_count + tcount) <= max_tokens:
trimmed.insert(0, c)
token_count += tcount
else:
break
print(f"Contexte réduit à {len(trimmed)} messages totalisant {token_count} tokens")
return trimmedCette approche en cache vous fait économiser des centaines, voire des milliers, de tokens chaque mois.
Les Pièges
Voici où le code idéal du tutoriel se casse dans la réalité :
| Piège | Ce qui se passe | Comment éviter |
|---|---|---|
| Mismatches de limites de tokens | Vos comptes de tokens sont incorrects à cause d'un mismatch entre le tokenizer ou le modèle ; vous dépassez ou êtes en deçà des tokens | Utilisez toujours tiktoken.encoding_for_model() qui correspond exactement au modèle d'embedding ou de complétion que vous utilisez |
| Embeddings dupliqués | Embedding le même morceau plusieurs fois gaspille des tokens et du stockage | Implémentez un cache et un hachage de somme de contrôle des documents |
| Erreurs de chevauchement de morceaux | Ectroverlap trop important crée des vecteurs redondants ; trop peu de chevauchement perd le contexte dans les documents fragmentés | Expérimentez avec le paramètre chunk_overlap, en vous en tenant à 10-15 % de la taille du morceau |
| Planification des appels asynchrones | Plusieurs appels asynchrones à ChromaDB ou OpenAI peuvent provoquer des conditions de concurrence ou des insertions partielles | Utilisez du code synchronisé ou une mise en file d'attente asynchrone appropriée ; les insertions par lots vous protègent de cela |
| Comptage de tokens peu fiable sur les textes non anglais | Les tokenizers peuvent mal compter à cause de caractères multi-octets ou de scripts inhabituels | Testez avec des langues représentatives, ajustez les tailles de morceaux en conséquence |
Exemple de code complet : Mettre tout ensemble
Cet exemple combine toutes les étapes précédentes dans un pipeline fonctionnel :
import tiktoken
from chromadb import Client
from openai import OpenAI
from langchain.text_splitter import RecursiveCharacterTextSplitter
from sklearn.feature_extraction.text import TfidfVectorizer
import numpy as np
# Constantes
MODEL_NAME = "text-embedding-3-small"
EMBEDDING_BATCH_SIZE = 50
CHUNK_SIZE = 500
CHUNK_OVERLAP = 50
# Configuration
client = Client()
collection = client.get_or_create_collection(name="mydocs")
openai_client = OpenAI()
tokenizer = tiktoken.encoding_for_model(MODEL_NAME)
def count_tokens(text):
return len(tokenizer.encode(text))
def chunk_text(text):
splitter = RecursiveCharacterTextSplitter(
chunk_size=CHUNK_SIZE,
chunk_overlap=CHUNK_OVERLAP,
length_function=count_tokens
)
return splitter.split_text(text)
def filter_chunks(chunks, query, keep_ratio=0.4):
vectorizer = TfidfVectorizer()
X = vectorizer.fit_transform(chunks + [query])
query_vec = X[-1]
chunk_vecs = X[:-1]
sims = (chunk_vecs @ query_vec.T).toarray().flatten()
thresh = np.quantile(sims, 1 - keep_ratio)
return [chunk for chunk, sim in zip(chunks, sims) if sim >= thresh]
def batch(iterable, n=1):
l = len(iterable)
for ndx in range(0, l, n):
yield iterable[ndx:min(ndx + n, l)]
def embed_and_index(chunks):
for chunk_batch in batch(chunks, EMBEDDING_BATCH_SIZE):
embeddings = []
for chunk in chunk_batch:
response = openai_client.embeddings.create(input=chunk)
embeddings.append(response.data[0].embedding)
ids = [str(hash(chunk) % (10**8)) for chunk in chunk_batch]
collection.add(documents=chunk_batch, embeddings=embeddings, ids=ids)
print(f"Batch indexé avec {len(chunk_batch)} morceaux")
# Pipeline principal
doc_text = open("messy_doc.txt").read()
print("Fragmentation du document...")
chunks = chunk_text(doc_text)
print(f"Créé {len(chunks)} morceaux")
# Simuler une requête d'exemple
query = "Comment l'utilisation des tokens est-elle optimisée avec ChromaDB ?"
print("Filtrage des morceaux avant l'embedding...")
chunks_to_embed = filter_chunks(chunks, query)
print(f"Embedding et indexation de {len(chunks_to_embed)} morceaux...")
embed_and_index(chunks_to_embed)
print("Pipeline complet.")Et après
Si vous êtes parvenu à mettre cela en œuvre avec succès, votre prochaine étape devrait être d'intégrer une récupération classée avec les complétions de GPT d'OpenAI pour construire un système de génération augmentée par récupération (RAG) qui obtient des réponses de votre base de données vectorielle avec des factures de tokens minimisées.
Concrètement, concentrez-vous sur la combinaison de vos requêtes ChromaDB avec un générateur de réponses qui tronque le contexte intelligemment, en appliquant idéalement une reformulation de requête pour réduire l'utilisation des tokens dans l'ingénierie des invites.
FAQ
Q : Pourquoi ne pas simplement envoyer tout le document à l'API d'embedding d'un coup ?
R : Parce que les limites de tokens de l'API d'embedding sont généralement limitées à quelques milliers de tokens—trop peu pour de gros documents—et vous payez de manière linéaire par token, donc vous gaspillez de l'argent et obtenez des embeddings moins précis qui nuisent à la précision de récupération.
Q : Comment gérer les documents qui changent fréquemment avec ChromaDB ?
R : Vous devez mettre en œuvre des embeddings de delta—n'embed que les morceaux nouveaux ou modifiés. Une approche naïve consiste à hacher le texte de chaque morceau et à le comparer aux ID stockés pour savoir quoi mettre à jour.
Q : Comment puis-je déboguer les erreurs de comptage des tokens dans mon application ?
R : Utilisez la bibliothèque officielle tiktoken d'OpenAI et assurez-vous que le nom du modèle dans encoding_for_model() correspond exactement à ce que vous envoyez à l'API. Vérifiez votre compte en imprimant des tableaux de tokens et en vérifiant les tailles de morceaux.
Recommandations pour différents profils de développeurs
Développeurs Juniors : Commencez par comprendre les limites de tokens et la fragmentation. N'essayez pas d'optimiser tout à la fois. Votre objectif devrait être de diviser les documents en morceaux de ~500 tokens et de vous assurer que vos appels API fonctionnent sans erreurs.
Développeurs de niveau intermédiaire : Implémentez le filtrage et le regroupement ensuite. Utilisez le TF-IDF pour pré-sélectionner les morceaux à embed. Ajoutez un cache afin de ne pas ré-embed les doublons. À ce stade, vous économiserez vraiment de l'argent et du temps.
Ingénieurs seniors : Automatisez la surveillance des tokens de bout en bout. Construisez des tableaux de bord qui vous alertent lorsque l'utilisation augmente. Explorez des chunkers personnalisés adaptés à votre type de document. Intégrez des métriques d'utilisation avec des tableaux de bord de coûts et expérimentez avec l'ingénierie des prompts pour réduire le contexte.
Données en date du 22 mars 2026. Sources : https://github.com/chroma-core/chroma, https://community.openai.com/t/issue-chromadb-document-and-token-openai-limitations/317378
Articles connexes
- Fonctionnalités de sécurité du kit d'outils d'agent IA
- Options open source du kit d'outils d'agent IA
- Guide du kit d'outils AutoGen
🕒 Published: