Recherche Visuelle par Image & Shop the Look IA — Guide complet

Ce module ajoute la recherche produit par image à votre boutique : le client glisse une photo et obtient les articles de votre catalogue les plus proches visuellement, classés par score de similarité. Le mode Shop the Look détecte chaque article d’une scène complète et propose les produits correspondants. Le moteur est agnostique : vous choisissez le fournisseur IA (Voyage, Cohere, OpenAI ou Mistral) et utilisez votre propre clé. Ce guide couvre l’installation, la configuration, l’indexation du catalogue et le fonctionnement de la recherche.

Installation

1. Téléchargez l’archive dfvisualsearch.zip depuis votre compte DataFirefly.
2. Back-office PrestaShop → Modules → Téléverser un module → envoyez le ZIP.
3. Le module crée sa table d’index, enregistre ses hooks et ajoute un onglet d’administration dédié.

Configuration générale

Rendez-vous dans Modules → Recherche Visuelle & Shop the Look IA → Configurer.

Choisir le fournisseur

Sélectionnez le moteur dans la liste, puis renseignez la clé API correspondante. Vous payez l’IA à l’usage chez le fournisseur, sans abonnement ajouté par le module.

• Voyage et Cohere : embeddings multimodaux directs de l’image.
• OpenAI et Mistral : analyse vision puis embedding, et débloquent en plus le Shop the Look.
• Clé API : stockée côté serveur, jamais exposée au front-office. Chaque fournisseur a son propre modèle et sa dimension de vecteur configurables.

Comportement

• Nombre de résultats : combien de produits afficher pour une recherche par image.
• Similarité minimale (0–1) : 0 affiche tout, classé par pertinence ; augmentez (par exemple 0,2 à 0,4) pour écarter les correspondances faibles. À calibrer selon le fournisseur.
• Activer le Shop the Look et produits par article détecté.
• Produits similaires sur la fiche produit et leur nombre.
• Injecter le bouton appareil-photo dans l’en-tête, ou le placer manuellement dans votre thème via le hook displayDfVisualSearchButton.
• Taille maximale d’upload et réindexation automatique à la sauvegarde d’un produit.

Indexer le catalogue

Dans le panneau Index du catalogue de la configuration :

1. Cliquez sur Indexer / réindexer le catalogue : le module traite les produits par lots, avec une barre de progression, sans risque de timeout serveur.
2. Le compteur indique les produits indexés pour le fournisseur actif.
3. Vider l’index supprime les vecteurs de la boutique courante.

L’indexation transforme l’image de couverture de chaque produit en un vecteur stocké en base. Une fois indexé, un produit n’est ré-encodé que si son image change.

Comment fonctionne la recherche

Chaque image est convertie en vecteur (embedding) normalisé. La photo envoyée par le client est encodée par le même fournisseur, puis comparée à l’index par similarité cosinus — qui, sur des vecteurs normalisés, se réduit à un simple produit scalaire. Les produits sont ensuite classés par score décroissant et filtrés par le seuil minimal configuré.

• Les fournisseurs Voyage et Cohere encodent l’image directement.
• Les fournisseurs OpenAI et Mistral décrivent l’image avec un modèle de vision, puis encodent cette description : l’indexation et la requête vivent ainsi dans le même espace vectoriel.

Shop the Look

À partir d’une photo de scène, le Shop the Look identifie chaque article visible et lance une recherche par article, présentant les résultats en groupes distincts.

Produits visuellement similaires

Sur la fiche produit, un bloc « produits visuellement similaires » s’affiche automatiquement. Il réutilise le vecteur déjà calculé lors de l’indexation du produit : aucune requête supplémentaire n’est envoyée à l’IA, et la recommandation n’ajoute donc aucun coût récurrent.

Affichage côté client

Le bouton appareil-photo ouvre une modale où le client glisse-dépose une photo ou la sélectionne. Un aperçu s’affiche, puis les résultats apparaissent sous forme de cartes produit avec leur score de similarité en pourcentage. Si le Shop the Look est activé, le client peut cocher l’option pour obtenir les résultats groupés par article détecté.

Choisir un fournisseur

Tous les fournisseurs assurent la recherche par image. Le choix dépend de vos besoins :

• Voyage / Cohere : embeddings multimodaux directs, simples et rapides, sans Shop the Look.
• OpenAI / Mistral : analyse vision qui débloque la détection multi-articles du Shop the Look.

Compatibilité et notes techniques

• PrestaShop 1.7.6 à 9.x, multiboutique et multilingue ; chaque boutique conserve son propre index.
• Contrôleur d’administration legacy (pas de contrôleur Symfony) pour la compatibilité PS8/PS9.
• Hooks utilisés : displayHeader, displayTop, displayDfVisualSearchButton, displayFooterProduct, actionProductSave, actionProductDelete.
• Vecteurs stockés normalisés en base, encodés pour un stockage robuste ; recherche par produit scalaire.
• Une limitation anti-abus par session protège votre quota IA.
• Endpoint de recherche AJAX via le lien de module ; réponse au format JSON.

FAQ et dépannage

Le bouton de recherche n’apparaît pas. Vérifiez qu’un fournisseur est configuré et que sa clé est valide (bouton Tester le fournisseur), puis que l’injection dans l’en-tête est activée ou que le hook est bien placé dans votre thème.

La recherche ne renvoie aucun résultat. Assurez-vous que le catalogue a été indexé pour le fournisseur actif, et abaissez la similarité minimale si elle est trop élevée pour l’espace vectoriel du fournisseur.

Le Shop the Look renvoie un seul groupe. Le fournisseur actif ne gère pas la détection (Voyage ou Cohere). Passez à OpenAI ou Mistral pour la détection multi-articles, puis réindexez.

J’ai changé de fournisseur et les résultats sont incohérents. Relancez une indexation complète : les vecteurs doivent être recalculés dans l’espace du nouveau fournisseur.