Recherche Sémantique IA pour PrestaShop

Ce module ajoute une recherche sémantique par intelligence artificielle à votre boutique PrestaShop. Au lieu de comparer littéralement les mots-clés, il comprend le sens de la requête du client grâce aux embeddings vectoriels et remonte les produits pertinents, même sans correspondance exacte.

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 trois tables (dfvectorsearch_index, dfvectorsearch_qcache, dfvectorsearch_log) 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.

Les compteurs affichent le nombre d’entrées indexables (produits × langues), les vecteurs déjà indexés, les entrées en attente et le nombre d’embeddings de requêtes en cache.

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

Indexation planifiée (cron)

Pour maintenir l’index synchronisé automatiquement avec les mises à jour du 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 tâches de votre hébergement.

L’URL contient un jeton de sécurité. Chaque appel travaille pendant une vingtaine de secondes puis s’arrête proprement, afin de 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 ou détachés de la boutique, ainsi que les langues désactivées, sont automatiquement nettoyés de l’index.

Recherche côté client

Activez Autocomplétion front-office pour attacher un menu de suggestions sémantiques à la barre de recherche de votre thème.

Sélecteur CSS

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. Pour un thème personnalisé, adaptez ce sélecteur au champ de recherche de votre thème.

Mode hybride

Avec le mode hybride activé (recommandé), le module combine le score sémantique avec une correspondance mot-clé sur le nom du produit. Les correspondances exactes de nom sont ainsi favorisées, sans sacrifier la pertinence sémantique.

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 champ nombre maximum de résultats limite le nombre de suggestions affichées.

Analyser les recherches

Chaque recherche est journalisée (requête, langue, boutique, nombre de résultats, meilleur score). Ces données vous aident à comprendre ce que cherchent réellement vos clients et à repérer les requêtes sans résultat pour enrichir votre catalogue.

Cache des requêtes

Les embeddings des requêtes clientes sont mis en cache pendant 30 jours. Les recherches répétées sont ainsi 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.

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.
• L’autocomplétion ne s’affiche pas : vérifiez le sélecteur CSS et que l’autocomplétion est activée. Les messages d’erreur détaillés sont consignés dans les journaux PrestaShop.
• 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.