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 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)

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

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

APIs d’embeddings

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.

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

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).

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