Tout ce que vous voudriez savoir avant d'installer.
Un regard détaillé sur le fonctionnement de DataFirefly Maillage Interne Sémantique IA — Embeddings vectoriels, similarités cosinus et insertion semi-automatique avec ancres intelligentes pour PrestaShop 8 & 9 (Mistral, OpenAI), pourquoi nous l'avons conçu ainsi, et la réflexion derrière les fonctionnalités ci-dessus.
Pourquoi le maillage interne sémantique est supérieur au maillage par mots-clés
Les modules de maillage interne classiques fonctionnent par règles mot-clé vers URL. Vous saisissez tapis berbère et associez l'URL de la catégorie tapis-berbere. Le moteur fait ensuite un find-replace dans le HTML de vos articles, produits ou pages. Cette approche a deux limites majeures. Elle est rigide : elle ne déclenche un lien que quand le mot-clé exact apparaît, ce qui exclut toutes les pages où le sujet est traité sous une autre formulation (tapis marocain, kilim, tapis traditionnel). Et elle est aveugle au contexte sémantique : le moteur ne sait pas si la page cible est vraiment pertinente pour le contenu source, il fait juste un match de chaîne. Le maillage sémantique fonctionne autrement : chaque contenu est représenté par un vecteur de plusieurs centaines de dimensions qui encode son sens — produit, catégorie, page CMS, blog. Deux contenus sont liés s'ils sont proches dans cet espace vectoriel, indépendamment des mots utilisés. Le module repère ainsi des opportunités de maillage qu'un moteur par mots-clés ne verrait jamais, et évite les faux positifs où un mot-clé apparaît dans un contexte non pertinent.
Embeddings IA : comment ça marche en pratique
Lors de la première indexation, le module parcourt toutes les entités actives de votre boutique pour les types activés (produits, catégories, pages CMS). Pour chaque entité, le contenu textuel est extrait et nettoyé : titre, meta_title, meta_description, description courte et description longue (le HTML est strippé proprement). Le texte nettoyé est ensuite envoyé en batch au fournisseur IA configuré (Mistral ou OpenAI), qui renvoie un vecteur d'embedding par item — une liste de nombres flottants qui représente la sémantique du texte. Ce vecteur est stocké en base sous forme de BLOB float32 packé en little-endian, avec sa norme L2 pré-calculée pour accélérer les calculs ultérieurs de similarité. La similarité entre deux contenus est ensuite calculée en PHP par produit scalaire normalisé (similarité cosinus), opération extrêmement rapide une fois les normes pré-calculées. Sur un catalogue de 5 000 entités, le calcul complet de toutes les paires en une langue prend quelques secondes seulement.
Pourquoi deux fournisseurs et pas un seul
Chaque fournisseur a son sweet spot. Mistral mistral-embed est l'option par défaut recommandée : 1024 dimensions, latence très basse, hébergement Europe (souveraineté UE pour les boutiques sensibles), coût d'environ 10 centimes par million de tokens — soit moins d'un euro pour indexer un catalogue de plusieurs milliers d'entités multilingues. OpenAI text-embedding-3-small est l'alternative : 1536 dimensions (espace vectoriel plus riche), excellent sur les langues non européennes, coût d'environ 2 cents par million de tokens (cinq fois moins cher que Mistral en USD). Le module unifie les deux fournisseurs derrière une interface commune : même format de retour, même mécanisme de batch, même gestion d'erreurs avec PrestaShopLogger. Vous pouvez basculer d'un fournisseur à l'autre depuis le dropdown de configuration — le module détectera que les dimensions ont changé et invitera à réindexer (un simple clic sur Tout réindexer).
Le générateur d'ancres, vraie pièce maîtresse du module
C'est le point qui fait la différence avec un module de suggestion brute. Pour chaque paire (source, cible) au-dessus du seuil de similarité, le générateur d'ancres applique l'algorithme suivant : il extrait le titre de la cible, le découpe en n-grammes de 2 à 6 mots, retire les stopwords (français et anglais), puis cherche chacun de ces n-grammes verbatim dans le corps de la source. Les n-grammes trouvés sont classés par longueur décroissante (les plus longs sont plus discriminants et plus optimisés SEO) et présentés dans le dropdown du back-office. L'ancre par défaut sélectionnée est la plus longue trouvée — ce qui donne typiquement un ancrage à 3 ou 4 mots qui inclut les mots-clés principaux du titre cible. Si aucun n-gramme du titre cible n'apparaît dans la source, le module propose le titre cible brut (mode fallback). Vous gardez bien sûr la main : dropdown éditable, option Personnaliser pour saisir n'importe quel texte d'ancre. Au moment de l'insertion, le module choisit la première occurrence du texte d'ancre dans le corps de la source qui n'est pas déjà dans une balise a, code ou pre — pas de risque de casser un lien existant ni de re-lier un texte déjà lié.
Rollback chirurgical par marqueur unique
C'est la fonctionnalité qui rassure tous les marchands prudents avec leurs descriptions. Chaque lien inséré reçoit un attribut HTML data-dfasl portant un identifiant unique de 36 caractères généré aléatoirement à l'insertion (format de type UUID). L'identifiant est aussi stocké en base dans la table dfasl_inserted_link, avec l'entité source, la cible, l'ancre, la date d'insertion et l'identifiant de l'employé qui a validé. Pour retirer un lien, vous allez dans l'onglet Liens insérés, vous cliquez sur Retirer à côté de la ligne concernée : le module fait une regex qui matche exactement le pattern d'ancre a data-dfasl avec cet identifiant unique, retire la balise a tout en gardant le texte de l'ancre intact, et marque le lien comme retiré dans la base. Aucune autre balise de la description n'est touchée, aucun lien manuel n'est en danger. Sur 500 liens insérés par le module dans 200 fiches produit, vous pouvez en retirer un seul en un clic sans toucher aux 499 autres.
Worker CLI et stratégie de traitement pour gros catalogues
Sur un catalogue de quelques dizaines de produits, tout peut se faire depuis le back-office : Tout réindexer puis Traiter un lot suffit. Au-delà de quelques milliers d'entités, l'interface devient lente et l'utilisateur n'a pas envie de garder son navigateur ouvert pendant des heures. Le module expose un worker CLI (bin/analyze.php) qui se lance en ligne de commande PHP avec quatre options. --shop pour cibler une boutique précise dans un environnement multishop. --enqueue-all pour réenqueuer toutes les entités actives avant de traiter — utile pour une re-indexation complète après un changement de fournisseur ou de modèle. --loop pour continuer à boucler tant qu'il reste des items à traiter. --max-batches pour limiter le nombre de lots traités dans un seul run (sécurité anti-runaway). --sleep pour intercaler une pause entre lots (utile pour rester sous les rate limits API). La commande type pour un cron toutes les 15 minutes est : php modules/dfaisemanticlinks/bin/analyze.php --loop --max-batches=50 --sleep=1. Le worker reset automatiquement les entrées bloquées en statut En cours depuis plus de 30 minutes (cas où un worker précédent aurait planté), gère les erreurs API en marquant les items concernés en statut En erreur avec le message, et continue de traiter les items sains du lot.
Auto-réindexation et fraîcheur de l'index
Un index qui se désynchronise du catalogue n'a plus aucune valeur. Le module gère la fraîcheur par hooks PrestaShop natifs. À chaque modification d'un produit, d'une catégorie ou d'une page CMS (hooks actionObjectProductUpdateAfter, actionObjectCategoryUpdateAfter, actionObjectCmsUpdateAfter), l'entité concernée est replacée dans la file d'attente avec un statut En attente, dans toutes les langues actives — le worker prochain la traitera automatiquement. À la suppression (hooks actionObjectProductDeleteAfter, actionObjectCategoryDeleteAfter, actionObjectCmsDeleteAfter), les embeddings et suggestions associées sont purgés en cascade. Le module inclut aussi un hash de contenu (SHA-256 du texte nettoyé) : si une entité est replacée en file sans que son contenu réel ait changé (par exemple parce qu'un employé a juste touché le stock), le batch d'indexation détecte le hash inchangé et skip l'appel API — économie de tokens. L'auto-réindexation est togglable depuis les Paramètres (option DFASL_AUTO_INDEX), utile pour la suspendre pendant un import CSV massif et la reprendre une fois l'import terminé avec un Tout réindexer.
Multi-boutique et multilingue natifs
Le module est nativement multi-boutique et multilingue. Les embeddings sont scopés par triplet (entité, langue, boutique) — un même produit dans deux boutiques aura deux embeddings indépendants si les descriptions diffèrent, et un même produit en français et en anglais aura deux embeddings différents bien que la fiche soit la même. Les suggestions ne croisent jamais les frontières linguistiques : un produit français ne se verra jamais suggérer un lien vers un produit anglais (ce qui n'aurait aucun sens en SEO). Les frontières boutiques sont respectées de la même façon. La configuration peut être différente par boutique (clé API, seuil de similarité, types indexés, hook d'affichage) — utile quand vous avez une boutique B2B avec contenu technique et une boutique B2C avec contenu grand public dans la même infrastructure.
Cas d'usage typiques
Boutique mode multilingue avec catalogue de 2 000 produits — le maillage sémantique repère les paires de produits visuellement ou stylistiquement proches (par exemple deux variations d'une coupe de robe) que des règles mots-clés rateraient systématiquement. Boutique B2B technique avec descriptions denses — le maillage sémantique relie les produits qui partagent un même cas d'usage industriel sans que le vocabulaire soit identique. Blog e-commerce — chaque article peut référencer automatiquement les produits, catégories et autres articles les plus pertinents par sens, avec ancres extraites verbatim du texte de l'article (le contraire d'un find-replace mécanique). Refonte de catalogue — après un import massif ou une réorganisation, un Tout réindexer reconstruit le maillage en quelques minutes là où une stratégie manuelle aurait pris des semaines de travail éditorial. Catalogue à fort vocabulaire spécifique (cosmétique bio, équipement médical, produits techniques) — le module détecte les proximités sémantiques que les non-experts ne verraient pas, et permet à l'équipe SEO de découvrir des opportunités de maillage non évidentes.
Architecture interne et compatibilité PrestaShop 8 et 9
Le module est construit en PHP 8.1+ avec types stricts, classes readonly et features modernes (match, enums). L'autoload est PSR-4 sous le namespace DataFirefly/AiSemanticLinks/ mappé sur src/. Les controllers admin sont en legacy ModuleAdminController (non Symfony Grid) — choix volontaire pour garantir une compatibilité stable entre PrestaShop 8.0 et 9.x sans avoir à maintenir deux variantes du code. Un mini-conteneur de services maison (ServiceContainer) wire les repositories et services métier — ce qui isole le module des différences de container Symfony entre les versions de PrestaShop, et évite une dépendance qui casserait à chaque mise à jour majeure. Cinq tables SQL préfixées dfasl_ : embedding (vecteurs et hashes), queue (file de travail), suggestion (paires proposées), inserted_link (liens actifs), job (operations de bulk). La désinstallation supprime proprement les 5 tables et purge toutes les variables de configuration DFASL_*. Le code source est livré non chiffré, conforme PSR — vous pouvez l'override, l'auditer, ou l'étendre comme bon vous semble.
Il n’y a pas encore d’avis.