Audit Sémantique — Documentation

Installation

Prérequis

• PrestaShop 8.0 à 9.x
• PHP 7.4 minimum (8.x recommandé)
• MySQL 5.7+ ou MariaDB 10.3+
• Une clé API OpenAI ou Mistral (optionnel — un mode local sans API est inclus)

Installer le module

1. Décompressez le fichier dfsemanticaudit.zip téléchargé depuis votre compte client.
2. Uploadez le dossier dfsemanticaudit/ dans /modules/ de votre PrestaShop via FTP, ou utilisez l’installation par ZIP depuis Modules → Module manager → Téléverser un module.
3. Cliquez sur Installer.

Activer le module

Le module crée automatiquement quatre tables SQL (ps_dfsa_content, ps_dfsa_audit, ps_dfsa_cluster, ps_dfsa_assignment) ainsi qu’un onglet d’administration accessible depuis le menu de gauche.

Configuration

Avant le premier audit, rendez-vous dans Modules → DataFirefly → Audit Sémantique → Configuration.

Choix du fournisseur d’embeddings

Trois fournisseurs sont disponibles. Le choix détermine la qualité des clusters obtenus.

OpenAI (recommandé)

Le fournisseur par défaut. Utilise le modèle text-embedding-3-small (1 536 dimensions). Qualité maximale, coût marginal : environ 0,02 € pour 1 000 produits lors de la première indexation.

• Clé API : créez-la depuis platform.openai.com/api-keys
• Modèle : laissez text-embedding-3-small par défaut. text-embedding-3-large (3 072 dim) donne une qualité légèrement supérieure mais coûte 6× plus cher.

Mistral

Alternative européenne hébergée en France. Utilise mistral-embed (1 024 dimensions). Tarification comparable à OpenAI.

• Clé API : créez-la depuis console.mistral.ai
• Modèle : mistral-embed

TF-IDF local

Fonctionne entièrement sur votre serveur, sans appel API, sans coût récurrent. Utilise les principes classiques du traitement statistique du langage (TF-IDF normalisé) avec une dimension de 384.

• Qualité suffisante pour les catalogues de moins de 500 produits.
• Supporte FR, EN, ES, DE, IT (stopwords intégrés).
• Aucune clé API requise.

Paramètres d’audit

• k (nombre de clusters) : 8 par défaut. Plage 2–50.
• Seuil hors-topic : distance cosinus à partir de laquelle un contenu est signalé. 0,55 par défaut. Plage 0,1 à 1,5.

Auto-reindex

Activé par défaut. Le module enregistre des hooks sur la création, modification et suppression des produits, catégories et pages CMS. À chaque changement, le contenu est marqué pour ré-embedding au prochain run, sans effort manuel.

Lancer son premier audit

Trois étapes à effectuer dans l’ordre depuis le tableau de bord.

Étape 1 — Réindexer le contenu

Cliquez sur Réindexer le contenu. Le module parcourt vos produits, catégories actives, pages CMS et fabricants, calcule un hash SHA1 du titre + extrait, et ne marque pour traitement que les contenus nouveaux ou modifiés.

Pour 1 000 contenus, cette étape dure quelques secondes.

Étape 2 — Générer les embeddings

Cliquez sur Générer les embeddings. Le module envoie les contenus marqués comme « dirty » au fournisseur sélectionné par lots de 50 (OpenAI/Mistral) ou en une passe locale (TF-IDF). Une barre de progression suit l’avancement.

Pour 1 000 contenus :

• OpenAI : ~30 secondes
• Mistral : ~40 secondes
• TF-IDF local : <1 seconde

Étape 3 — Lancer l’audit

Cliquez sur Lancer l’audit. Le clustering k-means cosinus regroupe les contenus en k clusters (initialisation k-means++, 50 itérations maximum), étiquette chaque cluster avec ses top termes (TF×IDF), calcule la distance de chaque contenu à son centroïde, et identifie les outliers.

Cette étape prend moins d’une seconde, même pour 5 000 contenus.

Comprendre le rapport

Tableau de bord

Quatre KPIs clés en haut :

• Contenus indexés — total de produits, catégories, CMS et fabricants embarqués.
• Pages hors-topic — nombre absolu, taux en pourcentage et répartition par type.
• Clusters thématiques — nombre de groupes thématiques identifiés.
• Distance médiane — distance cosinus médiane au centroïde. En dessous de 0,40 = catalogue très cohérent. Au-dessus de 0,60 = catalogue dispersé.

Clusters

Vue Clusters : liste détaillée triée par taille, avec étiquette automatique (top 5 termes TF×IDF), score de cohésion (0 = dispersé, 1 = identique), et taille (nombre de contenus).

Un cluster avec une cohésion < 0,40 est trop hétérogène — c’est souvent le signe qu’il faudrait scinder le sujet en deux sous-thèmes, ou que k est trop bas.

Carte sémantique 2D

Projection de tous les contenus sur un plan via la technique Johnson-Lindenstrauss (une projection aléatoire qui préserve approximativement les distances).

Chaque point est un contenu, chaque couleur un cluster. Les croix marquent les centroïdes. Les points avec un contour rouge sont les hors-topic. La légende à droite permet de masquer/afficher chaque cluster individuellement en cliquant dessus.

Pages hors-topic

Vue Pages hors-topic : tableau triable des contenus dont la distance cosinus au centroïde dépasse le seuil configuré. Pour chaque ligne :

• Type, titre, URL publique et lien direct vers la fiche d’édition
• Cluster actuel (avec sa couleur)
• Distance au centroïde (plus elle est élevée, plus le contenu est éloigné)
• Cluster suggéré (si pertinent)
• Δ Gain : réduction de distance si le contenu était déplacé

Pages irrécupérables

En bas de la vue Hors-topic, une section spéciale liste les contenus éloignés de tous les clusters. Le module n’a pas trouvé de destination viable pour eux.

Trois actions à envisager :

1. Supprimer si la page n’a pas de trafic SEO ni de conversion.
2. Noindex pour préserver le budget de crawl sans perdre l’historique.
3. Réécrire pour aligner le contenu avec un cluster existant.

Suggestions de restructuration

Vue Suggestions : équivalente à Pages hors-topic mais centrée sur l’action. Tous les déplacements proposés sont listés avec le gain de cohérence attendu. Triez par gain décroissant pour traiter les cas les plus impactants d’abord.

Le module ne modifie jamais votre arborescence automatiquement. Les changements restent sous votre contrôle via le back-office PrestaShop standard.

Export CSV

Depuis chaque vue de rapport, un bouton Exporter CSV permet de télécharger les données brutes. Utile pour :

• Partager le rapport avec un consultant SEO externe
• Traiter les données dans Excel/Sheets
• Archiver l’état d’un audit avant de modifier l’arborescence

Automatisation via cron

Le module expose une URL signée affichée dans la page de configuration. Elle déclenche en headless l’enchaînement complet indexation → embeddings → audit.

Exemple de tâche cron hebdomadaire (chaque lundi 3h) :

0 3 * * 1 wget -q -O /dev/null "https://votre-boutique.com/modules/dfsemanticaudit/cron.php?token=VOTRE_TOKEN"

Le token est dérivé de la _COOKIE_KEY_ de votre PrestaShop et ne change qu’à la réinstallation. Notez-le précieusement.

Coûts API

Estimation pour un catalogue moyen (1 000 produits) :

• OpenAI text-embedding-3-small : ~0,02 € la première fois, puis quasi nul (seuls les contenus modifiés sont retraités)
• OpenAI text-embedding-3-large : ~0,13 € la première fois
• Mistral mistral-embed : ~0,10 € la première fois
• TF-IDF local : 0 €

Multi-langues et multi-boutique

Le module est nativement multi-langues et multi-boutique. Chaque audit s’exécute sur un couple langue × boutique donné, en utilisant la langue de contexte du back-office.

Pour auditer votre boutique en français puis en anglais, changez de langue dans la barre supérieure de PrestaShop, puis relancez un nouvel audit.

Dépannage

L’étape « Générer les embeddings » échoue avec une erreur 401

Votre clé API est invalide ou expirée. Vérifiez-la dans la page de configuration et reconfigurez-la si nécessaire.

L’étape « Générer les embeddings » échoue avec une erreur 429

Vous avez atteint la limite de débit de votre fournisseur. Attendez quelques minutes puis relancez — le module reprendra là où il s’était arrêté grâce à son traitement par lots.

Aucun cluster ne semble pertinent

Trois pistes :

1. Augmentez le nombre de clusters (k). Si votre catalogue a 10 thématiques distinctes mais que k=4, le clustering ne pourra pas les séparer.
2. Passez du mode TF-IDF local à OpenAI ou Mistral. Sur les catalogues hétérogènes, la qualité sémantique fait toute la différence.
3. Vérifiez que les titres et descriptions de vos contenus sont suffisamment riches. Un produit avec un titre de 2 mots et aucune description ne donnera pas un bon embedding.

Trop de pages signalées hors-topic

Augmentez le seuil hors-topic (par exemple de 0,55 à 0,70). C’est attendu si votre catalogue couvre légitimement plusieurs thématiques larges.

Aucune page signalée hors-topic mais le catalogue semble incohérent

Baissez le seuil (par exemple de 0,55 à 0,40) pour resserrer la détection.

FAQ

Faut-il obligatoirement une clé API ?

Non. Le mode TF-IDF local fonctionne sans connexion externe. Il est légèrement moins précis que OpenAI/Mistral mais suffit pour démarrer ou pour un catalogue homogène.

Le module modifie-t-il automatiquement mon arborescence ?

Non. Le module ne fait que recommander. Tous les déplacements de contenu restent à votre charge via le back-office standard de PrestaShop.

Comment choisir le nombre de clusters (k) ?

Règle empirique : k ≈ nombre de catégories principales de premier niveau. Par défaut k=8 fonctionne bien entre 100 et 5 000 produits. Lancez 2 ou 3 audits avec différentes valeurs de k pour comparer si vous hésitez — les audits précédents restent en historique.

Mes vecteurs sont-ils envoyés à un serveur tiers ?

Avec OpenAI ou Mistral : oui, les titres et extraits de vos contenus sont envoyés à leur API d’embeddings. Avec le mode TF-IDF local : non, aucune donnée ne quitte votre serveur.

Combien de temps les audits sont-ils conservés ?

Indéfiniment, jusqu’à suppression manuelle depuis le tableau de bord. Vous pouvez consulter l’historique complet pour mesurer l’évolution de votre cohérence sémantique au fil du temps.

Le module fonctionne-t-il en multi-boutique ?

Oui. Chaque boutique du multistore peut avoir ses propres audits indépendants.