# Détecteur de Topic Clusters — Documentation

> Cette documentation décrit l'installation, la configuration et l'utilisation du module Détecteur de Topic Clusters sur PrestaShop 8 et 9. Le module détecte automatiquement les regroupements thématiques de votre catalogue par…

- Page: <https://www.datafirefly.com/documentation/topic-cluster-detector/>
- Langue: fr
- Mis à jour le: 2026-06-28
- Autres langues: [en](https://www.datafirefly.com/en/documentation/topic-cluster-detector/index.md), [es](https://www.datafirefly.com/es/documentation/topic-cluster-detector/index.md), [de](https://www.datafirefly.com/de/documentation/topic-cluster-detector/index.md), [it](https://www.datafirefly.com/it/documentation/topic-cluster-detector/index.md), [pl](https://www.datafirefly.com/pl/documentation/topic-cluster-detector/index.md), [nl](https://www.datafirefly.com/nl/documentation/topic-cluster-detector/index.md), [pt](https://www.datafirefly.com/pt/documentation/topic-cluster-detector/index.md)
- Index: <https://www.datafirefly.com/documentation/llms.txt>

Cette documentation décrit l'installation, la configuration et l'utilisation du module **Détecteur de Topic Clusters** sur PrestaShop 8 et 9. Le module détecte automatiquement les regroupements thématiques de votre catalogue par clustering sémantique et suggère les pillar pages manquantes avec un brouillon SEO complet pour chaque opportunité.

## Présentation

Le Détecteur de Topic Clusters analyse votre catalogue produit pour faire émerger les **topic clusters réellement présents** dans votre offre, puis détecte les **pillar pages manquantes** : ces sujets transversaux fortement couverts par vos produits mais sans page-mère structurante (CMS ou catégorie).

Pour chaque gap détecté, le module génère un brouillon complet :

- Titre H1 SEO-optimisé
- Slug URL-safe
- Meta description
- Plan H2 markdown complet
- Liste des mots-clés cibles
- Score de priorité (taille × cohésion)

**À retenir.** Le module ne crée pas de pages directement dans PrestaShop. Il vous donne un brouillon à copier-coller dans une nouvelle page CMS ou landing catégorie, en gardant la décision éditoriale entre vos mains.

## Installation

### Prérequis

- PrestaShop **8.0+** ou **9.x**
- PHP **8.0 minimum** (PHP 8.1 ou 8.2 recommandé)
- `memory_limit` de 512 Mo minimum (1024 Mo recommandé pour les gros catalogues)
- Optionnel : clé API OpenAI ou Mistral pour le mode embeddings

### Procédure d'installation

1. Téléchargez le fichier `dftopicclusters.zip` depuis votre espace client DataFirefly.
2. Dans le back-office PrestaShop, allez dans **Modules → Module Manager** puis cliquez sur **Téléverser un module**.
3. Sélectionnez le ZIP et confirmez. Le module s'installe automatiquement.
4. Une fois installé, cliquez sur **Configurer**.

À l'installation, le module crée automatiquement :

- Les 5 tables SQL préfixées `df_topicclusters_`
- L'onglet parent **DataFirefly** sous le menu Améliorer (s'il n'existe pas déjà)
- L'onglet enfant **Topic Clusters** sous ce parent
- Les 19 clés de configuration par défaut

### Premier accès

Une fois installé, le module est accessible via **Améliorer → DataFirefly → Topic Clusters**. Le tableau de bord vous présente le formulaire de lancement d'une nouvelle analyse et l'historique des runs précédents (vide à la première ouverture).

## Configuration

Cliquez sur le bouton **Paramètres** en haut à droite du tableau de bord pour accéder à la page de configuration. Les réglages sont groupés en cinq sections.

### Général

| Clé | Défaut | Description |
| --- | --- | --- |
| `DFTC_MODE` | `tfidf` | Mode de clustering : `tfidf` (local), `openai` ou `mistral` |
| `DFTC_K_AUTO` | activé | Si activé, calcule automatiquement k = ceil(√(N/2)) borné à [5, 30] |
| `DFTC_K_MANUAL` | 12 | Valeur de k utilisée si `DFTC_K_AUTO` est désactivé |
| `DFTC_MAX_ITER` | 60 | Nombre maximum d'itérations du k-means |
| `DFTC_MIN_CLUSTER_SIZE` | 3 | Taille minimale d'un cluster ; en-dessous, écarté |

### Extraction de texte

Permet de choisir quels champs du produit sont injectés dans l'analyse. La pondération par champ est fixe (nom × 3, meta × 2, description courte × 2, catégories × 2, tags × 2, description longue × 1, features × 1).

- `DFTC_INCLUDE_DESCRIPTION` — Inclure la description longue (recommandé : activé)
- `DFTC_INCLUDE_CATEGORIES` — Inclure les noms de catégories (recommandé : activé)
- `DFTC_INCLUDE_TAGS` — Inclure les tags PrestaShop (recommandé : activé)
- `DFTC_INCLUDE_FEATURES` — Inclure les caractéristiques produit (recommandé : désactivé sauf si vous avez des features très descriptives)

### Réglages TF-IDF

| Clé | Défaut | Description |
| --- | --- | --- |
| `DFTC_MIN_DOC_FREQ` | 2 | Terme ignoré s'il apparaît dans moins de N produits |
| `DFTC_MAX_DOC_FREQ_RATIO` | 0.50 | Terme ignoré s'il apparaît dans plus de X % du catalogue |
| `DFTC_NGRAM_MAX` | 2 | 1 = unigrammes, 2 = unigrammes + bigrammes |
| `DFTC_TOP_TERMS_COUNT` | 8 | Nombre de termes affichés par cluster |

### APIs d'embeddings

| Clé | Description |
| --- | --- |
| `DFTC_OPENAI_API_KEY` | Bearer token OpenAI (sk-...) |
| `DFTC_OPENAI_MODEL` | Modèle (défaut `text-embedding-3-small`) |
| `DFTC_MISTRAL_API_KEY` | Clé API Mistral |
| `DFTC_MISTRAL_MODEL` | Modèle (défaut `mistral-embed`) |
| `DFTC_BATCH_SIZE` | Nombre de produits par appel API (défaut 32) |

### Détection des pillar pages

- `DFTC_PILLAR_MATCH_THRESHOLD` — Seuil de match (défaut 0.45). En-dessous, le cluster est marqué _pillar gap_. Augmentez le seuil pour être plus strict, diminuez-le pour être plus tolérant.

## Les trois modes en détail

### Mode TF-IDF (recommandé pour démarrer)

Le TF-IDF (Term Frequency × Inverse Document Frequency) est une méthode statistique classique en NLP. Le module construit un vocabulaire à partir de tous les textes produits, filtre les termes trop rares ou trop fréquents, puis représente chaque produit comme un vecteur creux dans cet espace.

**Avantages :** 100 % local, instantané, aucun coût, aucune dépendance externe. Excellent pour les catalogues lexicalement homogènes (un domaine, un vocabulaire cohérent).

**Limites :** ne comprend pas les synonymes (deux produits utilisant des termes différents pour le même concept seront mal regroupés).

### Mode OpenAI embeddings

Utilise l'API OpenAI `text-embedding-3-small` par défaut. Chaque produit est représenté par un vecteur dense de 1536 dimensions qui capture sa sémantique.

**Avantages :** comprend les synonymes, les variantes lexicales et le contexte. Excellent pour les catalogues diversifiés ou aux descriptions narratives.

**Coût indicatif :** environ 0,02 USD par million de tokens, soit moins de 0,10 USD pour un catalogue de 1 000 produits.

**Astuce.** Le cache d'embeddings est automatique : si vous relancez un run sur le même catalogue sans modifier les textes, les vecteurs sont récupérés depuis la table `df_topicclusters_embedding_cache` sans nouvel appel API.

### Mode Mistral embeddings

Utilise l'API Mistral `mistral-embed` par défaut. Modèle multilingue performant, particulièrement bon en français.

**Avantages :** hébergé en Europe (conformité RGPD facilitée), excellent sur les contenus francophones, tarif compétitif.

## Lancer une analyse

Depuis le tableau de bord, le formulaire **Lancer une nouvelle analyse** propose six paramètres :

- **Langue** — la langue dans laquelle les textes produits seront extraits et analysés. Lancez un run distinct pour chaque langue active de votre boutique.
- **Mode** — TF-IDF, OpenAI ou Mistral (surcharge le réglage par défaut pour ce run uniquement).
- **Nb clusters (k)** — Laissez 0 pour l'auto-k. Sinon, forcez une valeur entre 2 et 100.
- **Taille minimale** — Clusters plus petits écartés (défaut 3).
- **Seuil pillar** — Seuil de match en-dessous duquel un cluster est marqué gap (défaut 0.45).
- **Limite produits** — Limite le nombre de produits analysés (utile pour debug ou test rapide). Laissez 0 pour analyser tout le catalogue.

Cliquez sur **Lancer l'analyse**. Le run démarre immédiatement. Pour un catalogue de 1 000 produits :

- Mode TF-IDF : 5 à 15 secondes
- Mode embeddings (premier run) : 30 secondes à 2 minutes selon le batch size
- Mode embeddings (runs suivants avec cache chaud) : équivalent au TF-IDF

**Important.** Le module pose `set_time_limit(0)` et `memory_limit=1024M` pour la durée du run. Sur les hébergements très contraints, ces directives peuvent être ignorées. Privilégiez un run de nuit ou utilisez la limite produits pour découper.

## Lire les résultats

Une fois le run terminé, vous accédez à la page de détail. Chaque cluster est affiché sous forme de carte avec quatre sections.

### En-tête de cluster

L'en-tête combine un badge de statut, un numéro de cluster et un label généré. Le badge est :

- **PILLAR GAP** (orange) — Aucune pillar page existante ne couvre ce sujet. Opportunité forte.
- **OK** (vert) — Une page CMS ou catégorie couvre déjà ce sujet (le module l'a matchée).

Le label est composé des 3 top-termes du cluster joints par `·`. Exemple : "sneakers · cuir premium · chaussures".

### Statistiques

- **Produits** — Nombre de produits dans le cluster
- **Cohésion** — Similarité moyenne des membres au centroïde (0 à 100 %). Plus c'est élevé, plus le cluster est homogène.
- **Match** — Score de match avec la meilleure pillar page existante. Si en-dessous du seuil → gap.

### Top termes

Les termes les plus représentatifs du cluster. En mode TF-IDF, ce sont les termes ayant la plus forte composante dans le centroïde. En mode embeddings, le module calcule un TF interne au cluster pondéré par l'IDF global pour faire ressortir les termes distinctifs.

### Suggestion de pillar page

Présente uniquement si le cluster est marqué gap. Contient :

- **Titre** — Titre H1 SEO-optimisé en français naturel
- **Slug** — URL-safe, en kebab-case
- **Meta description** — 150-160 caractères
- **Priorité** — Score combiné taille (0.6) × cohésion (0.4)
- **Plan suggéré** — Plan H2 en markdown avec sections classiques (intro, qu'est-ce que, comment choisir, comparatif, meilleurs produits, cas d'usage, erreurs à éviter, FAQ, CTA)

### Produits du cluster

Liste des produits regroupés avec leur score de similarité au centroïde, classés par similarité décroissante. Cliquez sur l'ID produit pour ouvrir directement la fiche dans une nouvelle fenêtre.

## Workflow recommandé

Voici une utilisation typique du module en 4 étapes.

1. **Premier audit** — Lancez un run TF-IDF sur votre langue principale, avec les paramètres par défaut. Examinez les clusters marqués gap : sont-ils pertinents éditorialement ?
2. **Tri** — Pour chaque gap, utilisez le bouton **Ignorer** si le cluster ne mérite pas une pillar page (par exemple un regroupement accidentel de produits hétéroclites). Les gaps restants sont vos priorités.
3. **Rédaction** — Pour chaque gap retenu, créez une nouvelle page CMS dans PrestaShop avec le titre, slug et meta du brouillon. Utilisez le plan H2 comme squelette de rédaction. Cliquez sur **Marquer Fait** une fois publié.
4. **Relance** — Après publication des nouvelles pages, relancez un run. Les anciens gaps doivent maintenant être OK (le module détectera les nouvelles pillar pages).

**Bonnes pratiques SEO.** Une pillar page de qualité fait au moins 1 500 mots, intègre des liens internes vers les produits du cluster, et utilise les top-termes naturellement dans le contenu. Le brouillon généré est un point de départ, pas un livrable final.

## Export

Depuis la page de détail d'un run, deux boutons en haut à droite permettent d'exporter :

- **CSV** — Tableau avec une ligne par cluster, colonnes : id_cluster, label, n_members, cohésion, pillar_gap, match_score, suggested_title, suggested_slug, suggested_meta, priority_score, target_keywords. Encodage UTF-8 avec BOM (compatible Excel).
- **JSON** — Export complet incluant la liste des produits par cluster et le plan markdown intégral. Idéal pour automatisation ou intégration externe.

## Architecture technique

### Base de données

Le module crée 5 tables avec préfixe `df_topicclusters_` :

- `run` — Métadonnées de chaque exécution (mode, langue, statut, durée, compteurs)
- `cluster` — Clusters individuels (label, top termes JSON, cohésion, flag pillar_gap, match_score)
- `cluster_product` — Appartenance produit → cluster avec score de similarité
- `pillar` — Suggestions de pillar pages (titre, slug, meta, outline, priorité, statut)
- `embedding_cache` — Cache des vecteurs d'embeddings indexé par hash de texte

### PSR-4 et autoload

Le namespace racine est `DataFirefly/TopicClusters/`. Un autoload manuel est enregistré via `spl_autoload_register` dans le fichier principal du module, donc aucune dépendance Composer n'est requise.

### Controllers et compatibilité PS 8 / PS 9

Le module utilise un `ModuleAdminController` legacy (et non un controller Symfony) pour garantir la compatibilité avec les deux versions majeures. Les requêtes SQL sont écrites pour respecter les schémas des deux versions, notamment la suppression de la colonne `meta_keywords` en PS 9.

## Performances et limites

- **Catalogues jusqu'à 1 000 produits** — Runs en quelques secondes. Aucune préoccupation particulière.
- **1 000 à 10 000 produits** — Mode TF-IDF reste rapide (10-60 s). Mode embeddings : prévoir 1 à 5 minutes pour le premier run, instantané ensuite grâce au cache.
- **Plus de 10 000 produits** — Privilégier le paramètre **Limite produits** pour découper, ou augmenter `memory_limit` à 2 Go.

La complexité du k-means est O(n × k × iter × d) où n est le nombre de produits, k le nombre de clusters, iter le nombre d'itérations (typiquement 10-30) et d la dimension des vecteurs (variable en TF-IDF, 1536 en OpenAI).

## Dépannage

### Aucun cluster détecté

Vérifiez que vos produits ont bien du contenu textuel dans la langue analysée (au moins un nom et idéalement une description). Si `DFTC_MIN_DOC_FREQ` est trop haut pour votre catalogue, baissez-le à 1.

### Tous les clusters sont marqués pillar gap

Le seuil `DFTC_PILLAR_MATCH_THRESHOLD` est probablement trop élevé. Essayez 0.30 au lieu de 0.45 si votre boutique a peu de pages CMS. Vérifiez aussi que vos pages CMS et catégories sont bien actives.

### Erreur "Unknown column meta_keywords"

Cette erreur survient sur PrestaShop 9 avec une version antérieure du module. Mettez à jour vers la version 1.0.0 ou supérieure qui retire toute référence à `meta_keywords` (colonne supprimée en PS 9).

### Erreur "Compile Error: Access level to processExport() must be public"

Cette erreur survenait sur une version pré-1.0.0. Le nom de méthode est désormais `doExport()` pour éviter la collision avec `AdminControllerCore`. Mettez à jour le module.

### Le run échoue avec erreur API

Vérifiez que la clé API renseignée dans la configuration est valide et a des crédits. Testez avec `curl` en CLI pour confirmer que le serveur peut atteindre `api.openai.com` ou `api.mistral.ai`.

## Évolutions à venir

- Création directe de pages CMS depuis le brouillon (en un clic)
- Comparaison de runs (avant/après publication de pillar pages)
- Visualisation graphique du réseau sémantique inter-clusters
- Support des embeddings Cohere et Voyage AI
- Cron automatique pour relances périodiques

**Support.** Pour toute question ou bug, contactez [support@datafirefly.com](mailto:support@datafirefly.com). Les retours sont précieux pour orienter la roadmap.