Recherche Sémantique IA pour PrestaShop

Ce module ajoute une recherche sémantique par intelligence artificielle à votre boutique PrestaShop : autocomplétion, page de résultats de recherche, bloc « Vous aimerez aussi » sur la fiche produit et tableau de bord analytics partagent le même classement par le sens, calculé par embeddings vectoriels.

Prérequis

• PrestaShop 8.0 à 9.x
• PHP 7.4 à 8.3 avec l’extension cURL activée
• Une clé API chez un fournisseur d’embeddings : OpenAI, Mistral AI, ou toute passerelle compatible OpenAI

Installation

1. Dans le back-office, ouvrez Modules > Module Manager.
2. Cliquez sur Installer un module et téléversez le fichier ZIP.
3. Une fois installé, cliquez sur Configurer.

Le module crée quatre tables (dfvectorsearch_index, dfvectorsearch_qcache, dfvectorsearch_log, dfvectorsearch_similar) et un onglet caché pour ses appels AJAX. Rien n’est visible côté client tant que l’index n’est pas construit.

Configuration du fournisseur d’embeddings

Dans l’onglet Réglages, choisissez votre fournisseur puis renseignez votre clé API.

OpenAI

Sélectionnez le fournisseur OpenAI et saisissez votre clé. Le modèle recommandé est text-embedding-3-small (bon rapport qualité / prix). Pour une précision maximale sur un catalogue exigeant, vous pouvez utiliser text-embedding-3-large.

Mistral AI (hébergement européen)

Sélectionnez Mistral AI pour un traitement des données en Europe, conforme au RGPD. Le modèle à utiliser est mistral-embed.

Passerelle compatible OpenAI

Sélectionnez Custom pour utiliser votre propre passerelle (proxy interne, Azure OpenAI, etc.). Renseignez alors l’URL de base de l’API, par exemple https://ma-passerelle.exemple.com/v1.

La clé API est masquée après enregistrement. Laissez la valeur masquée telle quelle pour conserver la clé existante ; saisissez une nouvelle clé uniquement si vous souhaitez la remplacer.

Dimensions

Le champ Dimensions permet de réduire la taille des vecteurs pour accélérer la recherche sur les très gros catalogues. Laissez 0 pour utiliser la taille par défaut du modèle. Les modèles OpenAI text-embedding-3 acceptent des dimensions réduites (par exemple 512).

Changer de fournisseur, de modèle ou de nombre de dimensions rend tout l’index obsolète : à l’enregistrement, l’index est automatiquement marqué pour reconstruction complète et le cache des requêtes est vidé. Relancez ensuite une indexation.

Construire l’index

Après avoir enregistré la clé API, rendez-vous dans l’encart Index d’embeddings en haut de la page de configuration.

1. Cliquez sur Indexer maintenant. Le module traite les produits par lots avec une barre de progression, langue par langue et boutique par boutique.
2. Laissez la page ouverte jusqu’à ce que le statut affiche Index à jour.

Taille des lots

Le réglage Taille du lot d’indexation contrôle le nombre de produits traités par appel (5 à 100). Réduisez-le si votre serveur rencontre des délais d’expiration.

Indexation planifiée (cron)

Pour maintenir l’index synchronisé automatiquement avec le catalogue, copiez l’URL d’indexation cron affichée dans la configuration et appelez-la régulièrement (par exemple toutes les 15 minutes) depuis le planificateur de votre hébergement.

L’URL contient un jeton de sécurité. Chaque appel travaille une vingtaine de secondes puis s’arrête proprement, pour rester compatible avec les limites de temps d’exécution PHP.

Comment fonctionne la réindexation

À chaque ajout, modification ou suppression de produit, l’entrée correspondante est marquée pour réindexation. Le module calcule une empreinte (checksum) du texte du produit : si seul le prix ou le stock a changé, le texte reste identique et aucun nouvel appel API n’est déclenché. Les produits désactivés et les langues désactivées sont automatiquement nettoyés de l’index.

Recherche côté client

Autocomplétion

Activez Autocomplétion front-office pour attacher un menu de suggestions sémantiques à la barre de recherche de votre thème. Le champ Sélecteur CSS du champ de recherche indique au module à quel champ s’accrocher. La valeur par défaut #search_widget input[type="text"] fonctionne avec les thèmes basés sur classic.

Désactiver l’autocomplétion du thème

Le réglage Désactiver l’autocomplétion du thème (activé par défaut) supprime les suggestions de recherche natives (ps_searchbar et équivalents) pour éviter un double menu déroulant. Le module dé-enregistre le script natif et masque tout menu injecté par un thème personnalisé.

Mode hybride

Avec le mode hybride activé (recommandé), le classement sémantique est placé en tête et les résultats mot-clé natifs absents sont ajoutés à la suite. Vous n’obtenez jamais moins de résultats que la recherche d’origine.

Seuil et nombre de résultats

Le score de similarité minimum (entre 0 et 0,99 ; recommandé : 0,30) écarte les résultats trop éloignés. Le nombre maximum de résultats limite les suggestions affichées dans l’autocomplétion.

La page de résultats de recherche

Le réglage Prendre le contrôle de la page de résultats (activé par défaut) fait fournir le classement de la page de recherche par le module, via le hook productSearchProvider, le mécanisme officiel de PrestaShop utilisé par la navigation à facettes. Concrètement :

• l’autocomplétion et la page affichent les mêmes produits, dans le même ordre ;
• la pagination et les tris du thème restent fonctionnels (le tri « pertinence » conserve l’ordre sémantique, prix, nom et date sont recalculés dans le classement) ;
• si l’API d’embeddings est indisponible, le module bascule silencieusement sur les résultats natifs et journalise l’incident : la page de recherche ne casse jamais.

Le module ne se déclenche que sur une recherche texte. Les catégories, pages de tags et autres listings conservent leurs mécanismes natifs.

Produits similaires (Vous aimerez aussi)

Le Bloc produits similaires (activé par défaut) affiche sur chaque fiche produit un « Vous aimerez aussi » calculé par proximité sémantique entre les vecteurs déjà stockés en base. Aucun appel API n’est effectué : le bloc fonctionne même sans clé API tant que l’index existe.

• Nombre de produits similaires : de 2 à 12 (défaut 6).
• Score minimum des produits similaires : seuil dédié, indépendant de celui de la recherche (recommandé : 0,45). En dessous, le produit n’apparaît pas, quitte à afficher moins de cartes. Le modifier purge automatiquement le cache des similaires.
• Un bonus d’affinité favorise les produits de la même catégorie par défaut et de la même marque.
• Les résultats sont mis en cache 24 heures par produit et invalidés automatiquement à la réindexation.
• Le rendu utilise les miniatures natives de votre thème : badges, wishlist, quick view et styles de survol compris.

Sur un petit catalogue de démonstration où toutes les fiches partagent le même texte marketing, les similarités sont naturellement plus lâches. Montez le seuil à 0,55-0,60 pour ne conserver que les correspondances proches.

Statistiques et analytics

La page de configuration affiche un tableau de bord calculé sur les 30 derniers jours : nombre de recherches, taux sans résultat, résultats moyens par recherche, histogramme du volume par jour, top 20 des requêtes (occurrences, résultats moyens, meilleur score) et top 20 des requêtes sans résultat.

Les requêtes sans résultat sont une mine d’or : elles indiquent précisément ce que vos clients cherchent sans le trouver, et donc quoi ajouter à votre catalogue ou à vos synonymes.

• Le bouton Exporter en CSV télécharge le journal complet (séparateur point-virgule) avec la source de chaque recherche : autocomplétion ou page de résultats.
• Le journal est purgé automatiquement après 365 jours.

Cache des requêtes

Les embeddings des requêtes clientes sont mis en cache 30 jours. Les recherches répétées sont instantanées et ne sont pas refacturées par le fournisseur. Le bouton Vider le cache des requêtes permet de le réinitialiser à tout moment.

Mise à jour du module

Si vous mettez à jour le module en remplaçant ses fichiers (hors Module Manager), ouvrez une fois la page de configuration : le module enregistre alors automatiquement les hooks manquants, crée les tables et colonnes manquantes et pose les nouveaux réglages par défaut. Les fichiers CSS et JS du front intègrent un cache-buster, aucun vidage de cache navigateur n’est nécessaire.

Dépannage

• Aucun résultat ne remonte : vérifiez que l’index est construit (compteur « Vecteurs indexés » > 0) et que la clé API est valide.
• Deux menus déroulants s’affichent : vérifiez que Désactiver l’autocomplétion du thème est activé, puis videz le cache PrestaShop une fois.
• Autocomplétion et page de résultats diffèrent : ouvrez la page de configuration du module une fois (enregistrement automatique du hook de la page de résultats), et vérifiez que Prendre le contrôle de la page de résultats est activé.
• Le bloc Vous aimerez aussi est vide : l’index doit être construit pour la langue et la boutique courantes ; sinon, baissez le score minimum des produits similaires.
• Timeouts pendant l’indexation : réduisez la taille des lots et privilégiez l’indexation par cron.
• Résultats incohérents après un changement de modèle : relancez une reconstruction complète de l’index.