Semantisch zoeken met AI voor PrestaShop: volledige gids

Deze module voegt semantisch zoeken via kunstmatige intelligentie toe aan uw PrestaShop-winkel: autocomplete, zoekresultatenpagina, blok “Dit vindt u misschien ook leuk” op de productpagina en analytics-dashboard delen dezelfde rangschikking op betekenis, berekend met vectorembeddings.

Vereisten

• PrestaShop 8.0 tot 9.x
• PHP 7.4 tot 8.3 met de cURL-extensie actief
• Een API-sleutel bij een embeddings-provider: OpenAI, Mistral AI, of elke OpenAI-compatibele gateway

Installatie

1. Open in de back-office Modules > Modulebeheer.
2. Klik op Een module installeren en upload het ZIP-bestand.
3. Klik na de installatie op Configureren.

De module maakt vier tabellen aan (dfvectorsearch_index, dfvectorsearch_qcache, dfvectorsearch_log, dfvectorsearch_similar) en een verborgen tabblad voor haar AJAX-aanroepen. Aan klantzijde is niets zichtbaar zolang de index niet is opgebouwd.

Configuratie van de embeddings-provider

Kies in het tabblad Instellingen uw provider en vul uw API-sleutel in.

OpenAI

Selecteer de provider OpenAI en voer uw sleutel in. Het aanbevolen model is text-embedding-3-small (goede prijs-kwaliteitverhouding). Voor maximale precisie op een veeleisende catalogus kunt u text-embedding-3-large gebruiken.

Mistral AI (Europese hosting)

Selecteer Mistral AI voor gegevensverwerking in Europa, conform de AVG. Het te gebruiken model is mistral-embed.

OpenAI-compatibele gateway

Selecteer Custom om uw eigen gateway te gebruiken (interne proxy, Azure OpenAI, enzovoort). Vul dan de basis-URL van de API in, bijvoorbeeld https://mijn-gateway.voorbeeld.com/v1.

De API-sleutel wordt na het opslaan gemaskeerd. Laat de gemaskeerde waarde staan om de bestaande sleutel te behouden; voer alleen een nieuwe sleutel in als u ze wilt vervangen.

Dimensies

Met het veld Dimensies kunt u de vectorgrootte verkleinen om het zoeken op zeer grote catalogi te versnellen. Laat 0 staan om de standaardgrootte van het model te gebruiken. De OpenAI-modellen text-embedding-3 aanvaarden gereduceerde dimensies (bijvoorbeeld 512).

Van provider, model of aantal dimensies veranderen maakt de hele index verouderd: bij het opslaan wordt de index automatisch gemarkeerd voor volledige heropbouw en wordt de zoekopdrachtcache geleegd. Start daarna opnieuw een indexering.

De index opbouwen

Ga na het opslaan van de API-sleutel naar het blok Embeddings-index bovenaan de configuratiepagina.

1. Klik op Nu indexeren. De module verwerkt de producten in batches met een voortgangsbalk, taal per taal en winkel per winkel.
2. Laat de pagina open tot de status Index up-to-date toont.

Batchgrootte

De instelling Grootte van de indexeringsbatch stuurt het aantal verwerkte producten per aanroep (5 tot 100). Verlaag ze als uw server time-outs tegenkomt.

Geplande indexering (cron)

Om de index automatisch synchroon te houden met de catalogus, kopieert u de cron-indexerings-URL uit de configuratie en roept u ze regelmatig aan (bijvoorbeeld elke 15 minuten) vanuit de planner van uw hosting.

De URL bevat een beveiligingstoken. Elke aanroep werkt een twintigtal seconden en stopt dan netjes, om compatibel te blijven met de PHP-uitvoeringstijdlimieten.

Hoe de herindexering werkt

Bij elke toevoeging, wijziging of verwijdering van een product wordt de bijbehorende entry gemarkeerd voor herindexering. De module berekent een vingerafdruk (checksum) van de producttekst: is alleen de prijs of de voorraad veranderd, dan blijft de tekst identiek en wordt geen enkele nieuwe API-aanroep geactiveerd. Gedeactiveerde producten en talen worden automatisch uit de index opgeruimd.

Zoeken aan klantzijde

Autocomplete

Activeer Front-office autocomplete om een menu met semantische suggesties aan de zoekbalk van uw thema te hangen. Het veld CSS-selector van het zoekveld vertelt de module aan welk veld ze zich moet hechten. De standaardwaarde #search_widget input[type="text"] werkt met thema’s gebaseerd op classic.

De autocomplete van het thema uitschakelen

De instelling Autocomplete van het thema uitschakelen (standaard actief) verwijdert de native zoeksuggesties (ps_searchbar en gelijkaardige) om een dubbel dropdownmenu te vermijden. De module deregistreert het native script en verbergt elk menu dat een aangepast thema injecteert.

Hybride modus

Met de hybride modus actief (aanbevolen) komt de semantische rangschikking vooraan en worden de ontbrekende native trefwoordresultaten erachter toegevoegd. U krijgt nooit minder resultaten dan de oorspronkelijke zoekfunctie.

Drempel en aantal resultaten

De minimale gelijkenisscore (tussen 0 en 0,99; aanbevolen: 0,30) weert resultaten die te ver afstaan. Het maximale aantal resultaten begrenst de suggesties in de autocomplete.

De zoekresultatenpagina

De instelling De resultatenpagina overnemen (standaard actief) laat de module de rangschikking van de zoekpagina leveren, via de hook productSearchProvider, het officiële PrestaShop-mechanisme dat ook de facetnavigatie gebruikt. Concreet:

• de autocomplete en de pagina tonen dezelfde producten, in dezelfde volgorde;
• de paginering en de sorteringen van het thema blijven werken (de sortering “relevantie” behoudt de semantische volgorde; prijs, naam en datum worden binnen de rangschikking herberekend);
• is de embeddings-API onbeschikbaar, dan schakelt de module geruisloos over op de native resultaten en logt ze het incident: de zoekpagina gaat nooit kapot.

De module treedt alleen op bij een tekstzoekopdracht. Categorieën, tagpagina’s en andere lijsten behouden hun native mechanismen.

Vergelijkbare producten (Dit vindt u misschien ook leuk)

Het blok vergelijkbare producten (standaard actief) toont op elke productpagina een “Dit vindt u misschien ook leuk”, berekend op semantische nabijheid tussen de al opgeslagen vectoren. Er gebeurt geen enkele API-aanroep: het blok werkt zelfs zonder API-sleutel zolang de index bestaat.

• Aantal vergelijkbare producten: van 2 tot 12 (standaard 6).
• Minimumscore van de vergelijkbare producten: aparte drempel, onafhankelijk van die van het zoeken (aanbevolen: 0,45). Daaronder verschijnt het product niet, ook al betekent dat minder kaarten. Aanpassen leegt automatisch de cache van de vergelijkbare producten.
• Een affiniteitsbonus bevoordeelt producten uit dezelfde standaardcategorie en van hetzelfde merk.
• De resultaten worden 24 uur per product gecachet en automatisch ongeldig gemaakt bij herindexering.
• De weergave gebruikt de native miniaturen van uw thema: badges, wishlist, quick view en hoverstijlen inbegrepen.

Op een kleine democatalogus waar alle fiches dezelfde marketingtekst delen, zijn de gelijkenissen natuurlijk losser. Verhoog de drempel naar 0,55-0,60 om alleen de nauwe overeenkomsten te behouden.

Statistieken en analytics

De configuratiepagina toont een dashboard berekend over de laatste 30 dagen: aantal zoekopdrachten, percentage zonder resultaat, gemiddeld aantal resultaten per zoekopdracht, histogram van het volume per dag, top 20 van de zoekopdrachten (frequentie, gemiddelde resultaten, beste score) en top 20 van de zoekopdrachten zonder resultaat.

Zoekopdrachten zonder resultaat zijn een goudmijn: ze tonen precies wat uw klanten zoeken zonder het te vinden, en dus wat u aan uw catalogus of synoniemen moet toevoegen.

• De knop Exporteren als CSV downloadt het volledige logboek (puntkomma als scheidingsteken) met de bron van elke zoekopdracht: autocomplete of resultatenpagina.
• Het logboek wordt na 365 dagen automatisch opgeruimd.

Zoekopdrachtcache

De embeddings van klantzoekopdrachten worden 30 dagen gecachet. Herhaalde zoekopdrachten zijn onmiddellijk en worden niet opnieuw door de provider aangerekend. Met de knop Zoekopdrachtcache legen kunt u hem op elk moment resetten.

Module-update

Werkt u de module bij door haar bestanden te vervangen (buiten het Modulebeheer om), open dan één keer de configuratiepagina: de module registreert dan automatisch de ontbrekende hooks, maakt de ontbrekende tabellen en kolommen aan en zet de nieuwe standaardinstellingen. De CSS- en JS-bestanden van de front bevatten een cache-buster; het legen van de browsercache is niet nodig.

Probleemoplossing

• Er komt geen enkel resultaat op: controleer of de index is opgebouwd (teller “Geïndexeerde vectoren” > 0) en of de API-sleutel geldig is.
• Er verschijnen twee dropdownmenu’s: controleer of Autocomplete van het thema uitschakelen actief is en leeg dan één keer de PrestaShop-cache.
• Autocomplete en resultatenpagina verschillen: open één keer de configuratiepagina van de module (automatische registratie van de hook van de resultatenpagina) en controleer of De resultatenpagina overnemen actief is.
• Het blok Dit vindt u misschien ook leuk is leeg: de index moet opgebouwd zijn voor de huidige taal en winkel; verlaag anders de minimumscore van de vergelijkbare producten.
• Time-outs tijdens de indexering: verklein de batches en geef de voorkeur aan indexering via cron.
• Inconsistente resultaten na een modelwissel: start een volledige heropbouw van de index.