Visueel Zoeken met Afbeelding & Shop the Look met AI: volledige gids

Deze module voegt zoeken op afbeelding toe aan uw winkel: de klant sleept een foto naar de zoekbalk en krijgt de artikelen uit uw catalogus die er visueel het meest op lijken, gerangschikt op gelijkeniscore. De Shop the Look-modus herkent elk artikel in een complete scène en stelt de bijbehorende producten voor. De engine is provider-onafhankelijk: u kiest zelf de AI-provider (Voyage, Cohere, OpenAI of Mistral) en gebruikt uw eigen sleutel. Deze gids behandelt de installatie, de configuratie, de indexering van de catalogus en de werking van de zoekfunctie.

Installatie

1. Download het archief dfvisualsearch.zip vanuit uw DataFirefly-account.
2. PrestaShop back-office → Modules → Een module uploaden → upload het ZIP-bestand.
3. De module maakt haar indextabel aan, registreert haar hooks en voegt een eigen beheertabblad toe.

Algemene configuratie

Ga naar Modules → Visueel Zoeken & Shop the Look met AI → Configureren.

De provider kiezen

Selecteer de engine in de lijst en vul de bijbehorende API-sleutel in. U betaalt de AI per gebruik bij de provider zelf, zonder extra abonnement via de module.

• Voyage en Cohere: directe multimodale embeddings van de afbeelding.
• OpenAI en Mistral: vision-analyse gevolgd door een embedding, en ontgrendelen daarnaast de Shop the Look.
• API-sleutel: wordt server-side opgeslagen en nooit blootgesteld aan de front-office. Elke provider heeft zijn eigen configureerbare model en vectordimensie.

Gedrag

• Aantal resultaten: hoeveel producten worden getoond bij een zoekopdracht op afbeelding.
• Minimale gelijkenis (0–1): 0 toont alles, gerangschikt op relevantie; verhoog de waarde (bijvoorbeeld 0,2 tot 0,4) om zwakke matches uit te sluiten. Kalibreer per provider.
• Shop the Look inschakelen en producten per gedetecteerd artikel.
• Vergelijkbare producten op de productpagina en het aantal ervan.
• De camera-knop in de header injecteren, of hem handmatig in uw thema plaatsen via de hook displayDfVisualSearchButton.
• Maximale uploadgrootte en automatische herindexering bij het opslaan van een product.

De catalogus indexeren

In het paneel Catalogusindex van de configuratie:

1. Klik op Catalogus indexeren / herindexeren: de module verwerkt de producten in batches, met een voortgangsbalk, zonder risico op een servertime-out.
2. De teller toont het aantal geïndexeerde producten voor de actieve provider.
3. Index legen verwijdert de vectoren van de huidige winkel.

De indexering zet de omslagafbeelding van elk product om in een vector die in de database wordt opgeslagen. Een geïndexeerd product wordt alleen opnieuw gecodeerd wanneer zijn afbeelding wijzigt.

Hoe de zoekfunctie werkt

Elke afbeelding wordt omgezet in een genormaliseerde vector (embedding). De foto die de klant instuurt wordt door dezelfde provider gecodeerd en vervolgens met de index vergeleken via cosinusgelijkenis — die zich op genormaliseerde vectoren herleidt tot een eenvoudig inwendig product. De producten worden daarna gerangschikt op aflopende score en gefilterd op de ingestelde minimumdrempel.

• De providers Voyage en Cohere coderen de afbeelding rechtstreeks.
• De providers OpenAI en Mistral beschrijven de afbeelding met een vision-model en coderen vervolgens die beschrijving: indexering en zoekopdracht leven zo in dezelfde vectorruimte.

Shop the Look

Vanuit een scènefoto identificeert de Shop the Look elk zichtbaar artikel en start per artikel een zoekopdracht, met de resultaten in aparte groepen.

Visueel vergelijkbare producten

Op de productpagina verschijnt automatisch een blok “visueel vergelijkbare producten”. Het hergebruikt de vector die al bij de indexering van het product is berekend: er wordt geen extra verzoek naar de AI gestuurd, en de aanbeveling voegt dus geen terugkerende kosten toe.

Weergave aan klantzijde

De camera-knop opent een modaal venster waarin de klant een foto sleept of selecteert. Er verschijnt een voorbeeld, waarna de resultaten als productkaarten worden getoond met hun gelijkeniscore in procenten. Als de Shop the Look is ingeschakeld, kan de klant de optie aanvinken om de resultaten gegroepeerd per gedetecteerd artikel te krijgen.

Een provider kiezen

Alle providers ondersteunen het zoeken op afbeelding. De keuze hangt af van uw behoeften:

• Voyage / Cohere: directe multimodale embeddings, eenvoudig en snel, zonder Shop the Look.
• OpenAI / Mistral: vision-analyse die de multi-artikeldetectie van de Shop the Look ontgrendelt.

Compatibiliteit en technische opmerkingen

• PrestaShop 1.7.6 tot 9.x, multistore en meertalig; elke winkel behoudt zijn eigen index.
• Legacy-beheercontroller (geen Symfony-controller) voor PS8/PS9-compatibiliteit.
• Gebruikte hooks: displayHeader, displayTop, displayDfVisualSearchButton, displayFooterProduct, actionProductSave, actionProductDelete.
• Vectoren worden genormaliseerd in de database opgeslagen, gecodeerd voor robuuste opslag; zoeken via inwendig product.
• Een anti-misbruiklimiet per sessie beschermt uw AI-quotum.
• AJAX-zoekendpoint via de modulelink; antwoord in JSON-formaat.

FAQ en probleemoplossing

De zoekknop verschijnt niet. Controleer of er een provider is geconfigureerd en of de sleutel geldig is (knop Provider testen), en daarna of de injectie in de header is ingeschakeld of de hook correct in uw thema is geplaatst.

De zoekopdracht geeft geen resultaten. Controleer of de catalogus is geïndexeerd voor de actieve provider, en verlaag de minimale gelijkenis als die te hoog is voor de vectorruimte van de provider.

De Shop the Look geeft maar één groep terug. De actieve provider ondersteunt de detectie niet (Voyage of Cohere). Schakel over naar OpenAI of Mistral voor multi-artikeldetectie en indexeer opnieuw.

Ik ben van provider gewisseld en de resultaten zijn inconsistent. Start een volledige herindexering: de vectoren moeten opnieuw worden berekend in de ruimte van de nieuwe provider.