PS PrestaShop PrestaShop Intermédiaire

Maillage Interne Sémantique IA — Guide complet

Installer, configurer et exploiter le maillage interne sémantique par embeddings IA : indexation, suggestions, ancres, rollback et worker CLI.

Mis à jour Version du module 1.0.0

Présentation

DataFirefly Maillage Interne Sémantique IA (dfaisemanticlinks) construit le maillage interne de votre boutique PrestaShop à partir d’embeddings vectoriels. Chaque produit, catégorie et page CMS est transformé en vecteur par un fournisseur IA (Mistral ou OpenAI), les vecteurs sont comparés par similarité cosinus, et le module propose des liens contextuels avec des ancres extraites verbatim du texte source. Vous validez les suggestions une par une ou en lot, et chaque lien inséré peut être retiré chirurgicalement grâce à un marqueur unique data-dfasl.

Le module ne fait aucun appel IA au front-office : les similarités sont pré-calculées et les liens validés sont écrits directement dans les descriptions. Impact performance : zéro.

Prérequis

  • PrestaShop 8.0 → 9.x (PrestaShop 1.7 non supporté)
  • PHP 8.1, 8.2 ou 8.3
  • MySQL 5.7+ / MariaDB 10.3+
  • Une clé API Mistral (console.mistral.ai) ou OpenAI (platform.openai.com)
  • Accès CLI recommandé pour les catalogues de plus de 1 000 entités (cron)

Installation

  1. Back-office → Modules → Gestionnaire de modules → Installer un module.
  2. Uploadez dfaisemanticlinks.zip puis cliquez sur Installer.
  3. Le module crée 5 tables préfixées dfasl_ (embedding, queue, suggestion, inserted_link, job) et un menu Maillage IA avec 4 onglets : Tableau de bord, Suggestions, Liens insérés, Paramètres.

La désinstallation supprime proprement les 5 tables et toutes les variables de configuration DFASL_*. Exportez vos données avant si vous souhaitez les conserver.

Configuration

1. Fournisseur d’embeddings

Onglet Paramètres, premier bloc :

  • Fournisseur : Mistral (mistral-embed, 1024 dimensions, par défaut, hébergement UE) ou OpenAI (text-embedding-3-small, 1536 dimensions).
  • Clé API : collez la clé du fournisseur sélectionné.
  • Tester la connexion : le bouton envoie une chaîne de test et affiche les dimensions reçues. Validez toujours la clé ici avant de lancer une indexation.

Si vous changez de fournisseur après une indexation, les dimensions vectorielles changent (1024 vs 1536). Le module vous invitera à relancer un Tout réindexer — les anciens vecteurs sont écrasés, mais les liens déjà insérés restent en place.

2. Indexation

  • Types indexés : produits, catégories, pages CMS — chacun activable indépendamment.
  • Longueur minimum (défaut 200 caractères) : les contenus trop courts après nettoyage HTML sont ignorés.
  • Taille de lot (défaut 20) : nombre d’items envoyés par requête API. Un seul appel d’embedding par lot.
  • Auto-réindexation (défaut activée) : chaque modification produit/catégorie/CMS replace l’entité en file d’attente via hooks. Désactivez-la temporairement pendant un import CSV massif.

3. Suggestions et insertion

  • Seuil de similarité (défaut 0,78) : les paires sous le seuil sont ignorées. Descendez à 0,72 pour plus de suggestions, montez à 0,82 pour plus de strictness.
  • Liens max par page (défaut 5) : protection anti-suroptimisation SEO.
  • Stratégie d’ancrage : n-grammes optimisés (défaut) ou titre brut de la cible.

Première indexation

  1. Onglet Tableau de bord → bouton Tout réindexer : toutes les entités actives des types activés sont placées en file d’attente, dans toutes les langues actives.
  2. Cliquez sur Traiter un lot autant de fois que nécessaire (petits catalogues), ou lancez le worker CLI (voir plus bas).
  3. Chaque lot : extraction + nettoyage du texte, appel d’embedding en batch, stockage du vecteur, puis calcul des suggestions par similarité cosinus.

Le tableau de bord affiche en continu : entités totales, embeddings actifs, suggestions en attente, liens actifs, et les statuts de la file (En attente, En cours, Terminé, En erreur).

Coût indicatif : 1 000 produits en 3 langues ≈ 1,5 million de tokens ≈ 0,15 € (Mistral) ou 0,03 $ (OpenAI). La détection par hash SHA-256 fait que les ré-indexations suivantes ne re-payent que les contenus réellement modifiés.

Valider les suggestions

Onglet Suggestions : table paginée avec, par ligne, la source, la cible, le score de similarité, l’ancre proposée, un snippet de contexte, et les boutons Insérer / Rejeter.

Choisir l’ancre

Le générateur d’ancres extrait les n-grammes (2 à 6 mots) du titre cible présents verbatim dans le corps source, classés du plus long au plus court. Le menu déroulant liste tous les candidats ; l’option Personnaliser ouvre un champ libre. L’ancre par défaut est le n-gramme le plus long trouvé — en général 3 ou 4 mots incluant les mots-clés principaux de la cible.

Insertion

À l’insertion, le module lie la première occurrence de l’ancre qui n’est pas déjà dans une balise a, code ou pre (motifs PCRE SKIP/FAIL). Si aucune occurrence libre n’existe, un paragraphe de repli avec la classe dfasl-related est ajouté en pied de description. Chaque lien reçoit un attribut data-dfasl avec un identifiant unique de 36 caractères.

Actions en masse

Cochez plusieurs lignes (case en tête de colonne pour tout sélectionner) puis Insérer la sélection ou Rejeter la sélection. Pagination sur 50 lignes.

Retirer un lien (rollback)

Onglet Liens insérés : liste paginée des liens actifs avec source, cible, ancre, date, employé. Le bouton Retirer supprime uniquement la balise a data-dfasl portant cet identifiant — le texte de l’ancre reste intact, aucun autre élément HTML n’est touché, et le lien est marqué comme retiré en base.

Worker CLI et cron

Pour les catalogues volumineux, utilisez le worker en ligne de commande :

php modules/dfaisemanticlinks/bin/analyze.php [options]
  • --shop=N : cible une boutique précise (multishop).
  • --enqueue-all : réenqueue toutes les entités actives avant de traiter.
  • --loop : boucle tant qu’il reste des items en attente.
  • --max-batches=N : limite le nombre de lots par run (sécurité anti-runaway).
  • --sleep=N : pause en secondes entre lots (rate limits API).

Cron recommandé toutes les 15 minutes :

*/15 * * * * php /chemin/vers/prestashop/modules/dfaisemanticlinks/bin/analyze.php --loop --max-batches=50 --sleep=1

Le worker réinitialise automatiquement les entrées bloquées en statut « En cours » depuis plus de 30 minutes (crash d’un run précédent), marque les items en échec avec le message d’erreur API, et continue de traiter le reste du lot.

Auto-réindexation

Les hooks actionObjectProductUpdateAfter, actionObjectCategoryUpdateAfter et actionObjectCmsUpdateAfter replacent l’entité modifiée en file dans toutes les langues actives. Les hooks de suppression purgent embeddings et suggestions en cascade. Le hash de contenu SHA-256 évite tout appel API si le texte réel n’a pas changé (par exemple une simple modification de stock).

Multi-boutique et multilingue

Les embeddings sont scopés par triplet (entité, langue, boutique). Les suggestions ne croisent jamais les frontières linguistiques ni de boutique. La configuration (clé API, seuil, types indexés) peut différer par boutique via le sélecteur de contexte multiboutique standard PrestaShop.

Dépannage

« Clé API non configurée » ou erreur au test de connexion

Vérifiez que la clé correspond bien au fournisseur sélectionné dans le dropdown (une clé Mistral ne fonctionne pas avec le provider OpenAI et inversement) et qu’elle dispose de crédits. Les erreurs API détaillées sont journalisées dans Paramètres avancés → Logs (PrestaShopLogger).

Des items restent en statut « En cours »

Un worker a probablement été interrompu. Attendez 30 minutes (reset automatique) ou cliquez Vider la file puis relancez Tout réindexer.

Peu ou pas de suggestions générées

Trois causes fréquentes : seuil de similarité trop haut (essayez 0,72), contenus trop courts (sous la longueur minimum), ou catalogue trop homogène/hétérogène. Vérifiez aussi que les types d’entités souhaités sont activés dans les Paramètres.

L’ancre proposée est le titre brut de la cible

C’est le mode fallback : aucun n-gramme du titre cible n’apparaît verbatim dans le corps source. Choisissez une ancre personnalisée ou enrichissez la description source.

Architecture technique

  • PHP 8.1+ strict, PSR-4 sous le namespace DataFirefly/AiSemanticLinks/ mappé sur src/
  • Controllers admin legacy ModuleAdminController (compatibilité stable PS8/PS9)
  • Mini-conteneur de services maison (indépendant du container Symfony)
  • Vecteurs en BLOB float32 packé little-endian + norme L2 pré-calculée
  • 5 tables : dfasl_embedding, dfasl_queue, dfasl_suggestion, dfasl_inserted_link, dfasl_job
  • Code source non chiffré, prêt à override
Cette page vous a-t-elle été utile ?

Toujours bloqué ? Contactez le support