BERTopic transforme des textes en topics interprétables en combinant embeddings de transformers, réduction UMAP, clustering HDBSCAN et représentation c‑TF‑IDF (créé par Maarten Grootendorst). Je vous guide étape par étape pour comprendre, implémenter et optimiser ce pipeline robuste pour des résultats sémantiques cohérents.
Qu’est‑ce que BERTopic
BERTopic est un pipeline modulaire qui convertit des documents en embeddings sémantiques, les regroupe par similarité puis extrait des mots représentatifs pour chaque cluster.
1. Architecture générale du pipeline (embeddings → réduction de dimension → clustering → c‑TF‑IDF).
Les documents sont d’abord transformés en vecteurs numériques appelés embeddings, souvent issus de modèles comme Sentence‑BERT (SBERT). Ensuite, une réduction de dimension (par exemple UMAP) projette ces vecteurs dans un espace plus maniable afin de préserver la structure locale et globale. La phase de clustering (souvent HDBSCAN) regroupe les points proches en topics sans fixer a priori le nombre de clusters. Enfin, le c‑TF‑IDF — class‑based TF‑IDF — calcule l’importance des termes au niveau de chaque cluster en traitant chaque cluster comme un « document » unique pour extraire des mots représentatifs et rendre les topics interprétables.
2. Origine et auteur et modularité.
Le package BERTopic a été développé par Maarten Grootendorst et est disponible comme bibliothèque Python open‑source. La modularité permet de remplacer chaque composant (embeddings, méthode de réduction, algorithme de clustering, ou méthode d’extraction de termes) sans réécrire le pipeline, ce qui facilite les expérimentations et l’adaptation au domaine — par exemple remplacer SBERT par un modèle spécialisé en médical ou UMAP par PCA selon la taille du corpus. J’insiste sur cette remplaçabilité car elle prolonge la durée de vie d’un projet et améliore la reproductibilité.
3. Cas d’usage types avec exemples concrets courts.
Exemples pratiques :
- Exploration de corpus — Découvrir thèmes émergents dans 50k articles de presse pour orienter la rédaction.
- Segmentation de feedbacks clients — Regrouper 10k retours utilisateurs pour isoler problèmes récurrents et prioriser correctifs.
- Veille thématique — Suivre l’évolution des discussions sur la cybersécurité dans des flux Twitter et détecter nouvelles tendances.
4. Résultat attendu.
Les topics produits sont sémantiquement cohérents et interprétables grâce à l’association vecteurs+ c‑TF‑IDF, et le clustering (HDBSCAN) permet aussi d’identifier les outliers ou documents non‑assignés, utiles pour repérer le bruit ou cas rares.
| Embeddings | Convertir le texte en vecteurs sémantiques exploitables. |
| Réduction de dimension | Projeter les embeddings pour préserver similarités et accélérer le clustering. |
| Clustering | Regrouper les documents en topics cohérents et détecter outliers. |
| c‑TF‑IDF | Extraire les termes les plus représentatifs par topic pour l’interprétation. |
Comment sont calculés les embeddings et réduits
Les documents sont encodés en vecteurs denses par des modèles transformers spécialisés pour les phrases (ex. SentenceTransformers) puis projetés par UMAP pour faciliter le clustering.
Choix de modèles d’embeddings recommandé : privilégiez des modèles compacts comme all‑MiniLM‑L6‑v2 (384 dimensions) pour des traitements rapides et économiques, et des modèles plus grands comme all‑mpnet‑base‑v2 (768 dimensions) lorsque la qualité sémantique prime. Choisir implique un compromis vitesse/qualité : des modèles plus petits réduisent la latence et la mémoire et restent très performants sur des tâches de similarité, tandis que des modèles plus grands améliorent la finesse sémantique au prix de 2–4× de coût calculatoire sur CPU (ordre de grandeur, selon l’infrastructure).
Rôle sémantique des embeddings : ces vecteurs capturent le sens des phrases de sorte que la distance angulaire ou la similarité cosinus reflète la proximité de sens. Exemple visuel conceptuel : deux phrases synonymes se positionnent proches dans l’espace, tandis que des thèmes différents s’écartent. Vérifier la cohérence en observant les nearest neighbours (les voisins les plus proches) permet d’évaluer qualitativement la représentation.
Pourquoi UMAP : UMAP préserve la structure locale tout en projetant vers un espace de dimension réduite utile pour le clustering. Paramètres clés et effets concrets : n_neighbors contrôle l’échelle locale (petit → très local, grand → plus global), n_components fixe la dimension de projection (2 pour visualisation, 5–50 pour clustering intermédiaire), min_dist ajuste l’entassement des points (0.0 → points plus serrés, >0.1 → plus espacés), metric choisit la distance (cosine recommandé pour embeddings). Pour de petits corpus (<1k), baissez n_neighbors à 2–10 ; pour de grands corpus (>50k), augmentez à 15–50.
Conseils pratiques pour l’échelle : encodez par batchs (32–256), préférez GPU pour l’inférence (gain significatif), envisagez la quantization (bitsandbytes/ONNX) pour gros modèles, et automatisez des contrôles qualité simples en listant les top‑k nearest neighbours pour des échantillons.
from sentence_transformers import SentenceTransformer
model = SentenceTransformer('all-MiniLM-L6-v2')
docs = ["Texte A", "Texte B", "Texte C"]
embeddings = model.encode(docs, show_progress_bar=False, convert_to_numpy=True)
import umap
umap.UMAP(n_neighbors=2, n_components=2, min_dist=0.0, metric='cosine', random_state=42, init='random')| Paramètre | Impact |
| n_neighbors | Définit l’échelle locale vs globale; petit → plus fin localement, grand → regroupe thèmes. |
| n_components | Dimension de sortie; 2 pour visualisation, >2 souvent meilleur pour clustering. |
| min_dist | Contrôle la densité des points projetés; 0.0 → clusters serrés, >0.1 → séparation accrue. |
| metric | Distance utilisée; ‘cosine’ recommandé pour embeddings textuels. |
Comment BERTopic regroupe les documents et extrait les mots clés
BERTopic utilise HDBSCAN pour regrouper les embeddings réduits et c‑TF‑IDF pour représenter chaque cluster par mots clés distinctifs.
1. Principe de HDBSCAN (clustering hiérarchique à densité) : HDBSCAN identifie des régions denses d’embeddings sans présumer du nombre de clusters. Les paramètres essentiels sont min_cluster_size (taille minimale d’un cluster, influence directe sur la granularité) et min_samples (robustesse locale ; valeurs élevées rendent le modèle plus conservateur). La gestion des outliers se fait via le label -1, qui regroupe les points non assignés à un cluster dense. Les implications pour la granularité sont claires : réduire min_cluster_size augmente le nombre de topics fins, l’augmenter produit des topics plus larges et stables.
2. Définition claire et formule de c‑TF‑IDF utilisée dans BERTopic : c‑TF‑IDF = (tf_par_classe / somme(tf_classe)) × log(N / df). Dans cette formule, tf_par_classe est le nombre d’occurrences du mot dans tous les documents d’un cluster (classe), somme(tf_classe) est le total des tokens du cluster, N est le nombre de clusters (pseudo-documents) et df est le nombre de clusters contenant le mot. Cette normalisation par classe atténue les mots fréquents du corpus car l’IDF pénalise les termes présents dans plusieurs clusters et la fraction tf/somme(tf) valorise la spécificité locale.
3. Exemple chiffré simple :
Documents:
Doc1 (Cluster A): "chat chien chat"
Doc2 (Cluster A): "chat souris"
Doc3 (Cluster B): "chien oiseau"
Calculs:
Cluster A totals: chat=3, chien=1, souris=1 -> somme=tf=5
Cluster B totals: chien=1, oiseau=1 -> somme=tf=2
Nombre de clusters N=2
Pour "chat" dans A:
tf_par_classe = 3 -> 3/5 = 0.6
df = 1 (apparait seulement dans A) -> IDF = log(2/1)=0.6931
c-TF-IDF = 0.6 * 0.6931 ≈ 0.416
Pour "chien" dans A:
tf_par_classe = 1 -> 1/5 = 0.2
df = 2 (présent dans A et B) -> IDF = log(2/2)=0
c-TF-IDF = 0.2 * 0 = 04. Comment interpréter et affiner les topics : Filtrer les tokens non informatifs (nombres, ponctuation), ajuster les ngrams pour capturer expressions (« machine learning »), enrichir/adapter la liste de stopwords et régler min_cluster_size pour la granularité souhaitée. J’insiste sur la relecture humaine : valider que les mots clés racontent un sens cohérent et fusionner ou scinder manuellement si nécessaire.
| Comparaison | HDBSCAN | KMeans |
| Forces | Découvre nombre de clusters automatiquement, gère outliers, adapté aux formes non sphériques. | Rapide, déterministe (avec seed), facile à mettre à l’échelle. |
| Faiblesses | Plus lent, sensible aux paramètres de densité, résultats moins reproductibles sans réglages. | Exige le nombre de clusters, assume des clusters sphériques et égaux en taille. |
| Usage en topic modeling | Préférable pour découvrir topics naturels et outliers (rare topics). | Préférable pour partitionner rapidement quand le nombre de topics est connu. |
Comment implémenter BERTopic pas à pas
Comment implémenter BERTopic pas à pas
1. Fonction de prétraitement concise (minuscules, strip, suppression d’espaces multiples) et justification du prétraitement minimal.
Fonction de prétraitement simple : mettre en minuscules pour uniformiser, supprimer espaces en début/fin et réduire les espaces multiples pour éviter des tokens vides. Cette approche minimale conserve la richesse sémantique nécessaire aux encodeurs modernes basés sur Transformers (les modèles de phrase gèrent la ponctuation et la morphologie).
2. Extrait de code Python complet et explicite (en texte).
import re
import pandas as pd
from sentence_transformers import SentenceTransformer
import umap.umap_ as umap
import hdbscan
from bertopic import BERTopic
# Jeu d'exemples
docs = [
"La livraison a été rapide et le produit est conforme.",
"Service client inexistant, je suis très déçu.",
"Produit de qualité, fonctionne parfaitement.",
"Problème après mise à jour, bug récurrent.",
"Très bon rapport qualité-prix, recommandé."
]
# Prétraitement minimal
def preprocess(text):
text = text.lower().strip() # Minuscules et strip
text = re.sub(r'\s+', ' ', text) # Espaces multiples -> un espace
return text
docs_clean = [preprocess(d) for d in docs]
# Encodage
embedding_model = SentenceTransformer('all-MiniLM-L6-v2')
embeddings = embedding_model.encode(docs_clean, show_progress_bar=False)
# Configuration UMAP
umap_model = umap.UMAP(n_neighbors=15, n_components=5, metric='cosine', random_state=42)
# Configuration HDBSCAN
hdbscan_model = hdbscan.HDBSCAN(min_cluster_size=2, min_samples=1, prediction_data=True)
# Création et exécution de BERTopic
topic_model = BERTopic(umap_model=umap_model, hdbscan_model=hdbscan_model, embedding_model=embedding_model)
topics, probs = topic_model.fit_transform(docs_clean)
# Inspection
print(topic_model.get_topic_info())
print(topic_model.get_topic(0))
# Extraire documents par topic
doc_info = topic_model.get_document_info(docs_clean)
print(doc_info[doc_info.Topic == 0])3. Indications pour interpréter les sorties.
Label -1 signifie « bruit » ou documents non assignés à un cluster cohérent. Taille de cluster indique nombre de documents associés. Top n mots fournit les mots les plus représentatifs du topic (mesure souvent basée sur fréquence/pmi). Pour obtenir exemples par topic, filtrer topic_model.get_document_info(docs) sur la colonne Topic.
4. Conseils pour l’évaluation qualitative et quantitative des topics.
- Évaluer qualitativement : inspecter les top mots et 5 documents représentatifs par topic pour juger de la cohérence sémantique.
- Mesures quantitatives : calculer une cohérence topic (ex. UMass, CV) via gensim ou cooccurrence, et estimer une « silhouette » approximative en utilisant les embeddings moyens des documents par topic.
- Tests A/B : varier n_neighbors, n_components, min_cluster_size et comparer cohérence/chiffres; journaliser changements et valider sur jeu de test.
| Commande/Paramètre | Rôle | Valeur recommandée (prototypage) |
| Prétraitement | Uniformiser texte sans tout normaliser | Minuscules + strip + collapse spaces |
| embedding_model | Génère vecteurs sémantiques | all-MiniLM-L6-v2 |
| umap n_neighbors | Contrôle voisinage local global | 15 |
| umap n_components | Dimension de sortie pour clustering | 5 |
| hdbscan min_cluster_size | Taille minimale d’un cluster | 2-5 |
| hdbscan min_samples | Robustesse au bruit | 1 |
Quelles bonnes pratiques et limites en production
BERTopic apporte cohérence sémantique mais nécessite réglages et surveillance en production.
Déployer BERTopic en production exige des choix opérationnels clairs pour conserver interprétabilité et robustesse face aux flux de données.
1. Bonnes pratiques pour la mise en production : persistance des modèles d’embeddings, batching, indexation des vecteurs, pipeline de refresh des topics, tests de stabilité.
Persistation des embeddings : Sauvegarder les poids et surtout les embeddings calculés évite de recalculer des vecteurs à chaque requête et réduit le coût CPU/GPU. Batching : Traiter les documents en lots (batchs) pour limiter la latence et exploiter le GPU efficacement. Indexation des vecteurs : Utiliser un index vectoriel (Faiss, Annoy, Milvus) pour requêtes rapides et k-NN à l’échelle. Pipeline de refresh : Automatiser un pipeline qui recalcule et reclustre périodiquement pour capter l’évolution du langage. Tests de stabilité : Comparer topics entre runs via measures comme la similarité cosinus moyenne ou NMI (Normalized Mutual Information) pour détecter régressions.
2. Limitations connues : sensibilité aux embeddings choisis, difficulté à interpréter topics très larges, outliers nombreux sur corpus bruyants, coût compute pour gros volumes.
Sensibilité aux embeddings : Les modèles d’embeddings (vecteurs représentant le sens) influencent directement la qualité des clusters. Topics larges : Certains clusters regroupent thèmes hétérogènes et deviennent peu interprétables. Outliers : Sur données bruyantes, HDBSCAN produit de nombreux petits clusters ou points marqués « noise ». Coût compute : Le calcul d’embeddings et le reclustering fréquent sont coûteux sur des millions de documents.
3. Stratégies d’atténuation : fine‑tuning d’embeddings, filtrage des documents, ajustement de HDBSCAN, usage d’heuristiques humaines pour fusion/division de topics.
Fine‑tuning : Adapter un modèle d’embeddings sur votre domaine améliore la cohérence sémantique. Filtrage : Supprimer stopwords spécifiques, doublons et documents non informatifs réduit les outliers. Réglage HDBSCAN : Ajuster min_cluster_size et min_samples pour contrôler granularité. Heuristiques humaines : Permettre révisions manuelles pour fusionner ou scinder topics critiques.
4. Mesures opérationnelles recommandées : monitoring de drift sémantique, fréquence de réentraînement, seuils d’alerte sur taille/qualité des clusters.
Monitoring de drift : Suivre l’évolution des centroides et de la distribution des distances pour détecter dérive sémantique (changement dans l’usage des mots). Fréquence : Planifier réentraînement basé sur volume et drift (par exemple hebdomadaire ou mensuel). Seuils d’alerte : Définir alertes si plus de X% de documents deviennent « noise » ou si taille moyenne des clusters chute fortement.
# Exemple : sauvegarde rapide d'embeddings avec numpy
import numpy as np
# embeddings : ndarray shape (N, D)
np.save("embeddings.npy", embeddings) # réutilisable pour reclustering
| Mesure | Coût | Complexité | Bénéfice |
| Persistance des embeddings | Faible (stockage) | Faible | Latence réduite, coût compute ↓ |
| Indexation vectorielle | Moyen (infra) | Moyen | Requêtes rapides à grande échelle |
| Batching | Faible | Faible | Meilleure utilisation GPU/CPU |
| Pipeline de refresh | Moyen à élevé | Moyen | Topics à jour, détection dérive |
| Fine‑tuning embeddings | Élevé (GPU, données) | Élevé | Qualité sémantique nettement améliorée |
| Filtrage et heuristiques humaines | Faible à moyen | Moyen | Interprétabilité accrue |
| Monitoring & alertes | Faible | Faible à moyen | Réactivité opérationnelle |
Vous voulez produire des topics fiables et actionnables avec BERTopic ?
BERTopic offre un pipeline pragmatique et modulable pour transformer du texte brut en topics interprétables en combinant embeddings de transformers, UMAP, HDBSCAN et c‑TF‑IDF. En appliquant un prétraitement minimal, en choisissant des embeddings adaptés et en réglant UMAP/HDBSCAN, vous obtenez des topics cohérents exploitables pour la veille, l’analyse de feedback ou la segmentation. En production, anticipez la persistance des modèles, le monitoring et la réévaluation régulière pour garantir des résultats stables. Bénéfice pour vous : insights exploitables plus rapides et une base fiable pour automatiser la prise de décision.
FAQ
A propos de l’auteur
Franck Scandolera — expert & formateur en Tracking avancé server‑side, Analytics Engineering, Automatisation No/Low Code (n8n) et intégration de l’IA en entreprise. Responsable de l’agence webAnalyste et de l’organisme de formation Formations Analytics. Références clients : Logis Hôtel, Yelloh Village, BazarChic, Fédération Française de Football, Texdecor. Dispo pour aider les entreprises => contactez‑moi.
⭐ Analytics engineer, Data Analyst et Automatisation IA indépendant ⭐
- Ref clients : Logis Hôtel, Yelloh Village, BazarChic, Fédération Football Français, Texdecor…
Mon terrain de jeu :
- Data Analyst & Analytics engineering : tracking avancé (GTM server, e-commerce, CAPI, RGPD), entrepôt de données (BigQuery, Snowflake, PostgreSQL, ClickHouse), modèles (Airflow, dbt, Dataform), dashboards décisionnels (Looker, Power BI, Metabase, SQL, Python).
- Automatisation IA des taches Data, Marketing, RH, compta etc : conception de workflows intelligents robustes (n8n, App Script, scraping) connectés aux API de vos outils et LLM (OpenAI, Mistral, Claude…).
- Engineering IA pour créer des applications et agent IA sur mesure : intégration de LLM (OpenAI, Mistral…), RAG, assistants métier, génération de documents complexes, APIs, backends Node.js/Python.