Vector Search Native: volledige documentatie

Overzicht

Vector Search Native maakt van het productzoeken in WooCommerce een semantische motor. In plaats van zoekwoorden letter voor letter te vergelijken, zet de plugin elk product en elke zoekopdracht via een AI-model om in numerieke vectoren (embeddings) en berekent ze daarna de gelijkenis in betekenis. Het resultaat: een klant die “lichte katoenen zomerjas” typt, vindt uw “zomerse linnen blazer”, ook zonder één gemeenschappelijk woord.

De plugin ondersteunt drie embeddingproviders (OpenAI, Voyage AI en Cohere), die u met één klik kunt wisselen, met een incrementele indexering die de API alleen aanroept wanneer de inhoud van een product echt is veranderd, en een automatische terugval naar het ingebouwde zoeken op trefwoorden wanneer het vectorzoeken niet volstaat.

Vereisten

• WordPress 6.2 of hoger
• WooCommerce 7.0 of hoger (getest tot 9.4)
• PHP 8.0 of hoger
• Een API-sleutel bij een van de drie providers: OpenAI, Voyage AI of Cohere
• Een werkende WP-Cron (of een systeemcron die wp-cron.php aanroept)

Installatie

1. Ga in uw WordPress-beheer naar Plugins → Nieuwe plugin → Plugin uploaden.
2. Selecteer het bestand vector-search-native.zip en klik op Nu installeren.
3. Klik op Activeren. De plugin maakt automatisch haar twee tabellen aan (wp_vsn_embeddings en wp_vsn_index_queue) en plant haar crontaak in.
4. Er verschijnt een nieuw menu Vector Search onder WooCommerce.

De provider instellen

Ga naar WooCommerce → Vector Search. Het onderdeel “Embedding provider” toont de drie beschikbare providers. Kies er een in de keuzelijst “Active provider”, plak uw API-sleutel in het bijbehorende blok, kies een model en klik daarna op Test connection. Een groene melding met de dimensie van de vector (bijvoorbeeld “Connection OK. Embedding dimension: 1536”) bevestigt dat de configuratie klopt.

Welk model kiezen

• OpenAI text-embedding-3-small (1536d): de beste prijs-kwaliteitverhouding, standaard aanbevolen.
• OpenAI text-embedding-3-large (3072d): maximale kwaliteit, ongeveer 6 keer duurder.
• Voyage voyage-3 (1024d): uitstekende retrieval, getraind voor zoeken.
• Cohere embed-multilingual-v3.0 (1024d): de keuze voor meertalige catalogi in FR, EN, ES, DE en IT.

Eerste indexering

1. Klik op dezelfde pagina Vector Search op Queue all products for reindex. Alle gepubliceerde producten komen in de wachtrij.
2. Klik op Auto-process until done. De plugin verwerkt de wachtrij in blokken (standaard 25 producten) tot die leeg is, live vanuit uw browser.
3. De tellers “Indexed”, “Queued” en “Stuck” worden in realtime bijgewerkt.

U kunt het werk ook door WP-Cron op de achtergrond laten doen: de taak vsn_process_queue draait volgens het ingestelde interval (standaard 5 minuten) en werkt de wachtrij geleidelijk weg.

Hoe het zoeken werkt

Zodra de indexering klaar is, wordt het productzoeken van WooCommerce (frontend en standaardwidgets) automatisch onderschept. De plugin:

1. zet de zoekopdracht van de bezoeker via de actieve provider om in een vector (met een cache van 10 minuten);
2. berekent de cosinusgelijkenis tegenover alle opgeslagen productvectoren;
3. houdt de producten over die boven de minimale gelijkenisdrempel liggen (standaard 0,30), tot het maximale aantal kandidaten (standaard 200);
4. voegt de op relevantie gesorteerde ID’s toe aan de WordPress-query.

Blijft het aantal resultaten onder de terugvaldrempel (standaard 3), dan trekt de plugin zich terug en laat ze het ingebouwde zoeken op trefwoorden van WooCommerce gewoon zijn werk doen. Uw bezoekers zien dus nooit een lege pagina door een probleem aan de AI-kant.

Geavanceerde instellingen

Geïndexeerde inhoud

In het onderdeel “Content to index” kiest u welke velden in de embedding worden opgenomen: korte beschrijving, lange beschrijving, SKU, categorieën, tags en attributen. De producttitel wordt altijd geïndexeerd. Minder velden kan de relevantie bij sommige catalogi aanscherpen; alles opnemen maximaliseert het bereik.

Drempels en kandidaten

• Minimum similarity (0,0 tot 1,0): onder deze cosinusscore wordt een product niet weerhouden. Ga richting 0,4 of 0,5 om streng te filteren, of richting 0,2 om te verbreden.
• Max candidates: het aantal producten dat na sortering aan WooCommerce wordt teruggegeven. De paginering werkt daarna gewoon.
• Fallback threshold: het minimale aantal vectorresultaten voordat er op trefwoorden wordt overgeschakeld.

Wachtrij en cron

• Cron interval: hoe vaak de wachtrij wordt verwerkt (1, 5 of 15 minuten, of elk uur).
• Batch size (1 tot 100): het aantal producten per cyclus. Verhoog dit voorzichtig om ratelimieten bij de provider te vermijden.
• Elk mislukt product wordt tot 5 keer opnieuw geprobeerd, waarbij de laatste foutmelding in de database wordt bewaard. De teller “Stuck” toont de producten die hun pogingen hebben opgebruikt.

REST API

Er zijn vijf endpoints beschikbaar onder /wp-json/vsn/v1/, alle voorbehouden aan gebruikers met de capability manage_woocommerce:

• POST /reindex: zet alle producten in de wachtrij.
• POST /process: verwerkt meteen één blok.
• GET /stats: geeft de tellers terug (totaal, geïndexeerd, in wachtrij, geblokkeerd).
• POST /test: test een API-sleutel (parameters: provider, api_key, model).
• POST /clear: maakt de embeddingindex volledig leeg.

Voorbeeld van een volledige herindexering vanuit een uitrolscript:

curl -X POST https://uw-winkel.nl/wp-json/vsn/v1/reindex 
  -u admin:APPLICATIEWACHTWOORD

Hooks voor ontwikkelaars

vsn_indexed_text

Past de tekst aan die per product naar de provider gaat. Ideaal om ACF-velden of eigen metagegevens toe te voegen:

add_filter( 'vsn_indexed_text', function ( $text, $product ) {
    $materiaal = get_post_meta( $product->get_id(), 'matiere', true );
    if ( $materiaal ) {
        $text .= "nMateriaal: " . $materiaal;
    }
    return $text;
}, 10, 2 );

vsn_should_engage

Bepaalt nauwkeurig wanneer het vectorzoeken wordt ingeschakeld:

// Vectorzoeken uitschakelen bij zoekopdrachten van één woord.
add_filter( 'vsn_should_engage', function ( $engage, $query ) {
    $s = (string) $query->get( 's' );
    if ( str_word_count( $s ) < 2 ) {
        return false;
    }
    return $engage;
}, 10, 2 );

Meertalige winkels

Met WPML of Polylang is elke vertaling een apart WordPress-product, dus elke vertaling krijgt haar eigen embedding, in de eigen taal. Twee aanbevelingen:

• Gebruik een meertalig model (Cohere embed-multilingual-v3.0 of Voyage voyage-multilingual-2), zodat zoekopdrachten en productpagina's in dezelfde semantische ruimte terechtkomen, ongeacht de taal.
• Voer na het toevoegen van een nieuwe taal of een grote vertaalcampagne een volledige herindexering uit om de nieuwe producten mee te nemen.

Probleemoplossing

Er blijven producten op "Stuck" staan

Een product komt op "Stuck" na 5 mislukte pogingen op rij. Veelvoorkomende oorzaken: een ongeldige of verlopen API-sleutel, een ratelimiet bij de provider, of een netwerktimeout. Controleer uw sleutel met Test connection, corrigeer het probleem en klik daarna op Queue all products for reindex; dat zet de pogingentellers terug op nul.

Het zoeken lijkt onveranderd

• Controleer of het vakje Enabled is aangevinkt bij de algemene instellingen.
• Controleer of de teller "Indexed" overeenkomt met uw aantal producten.
• Gebruikt u een externe zoekplugin (FiboSearch, SearchWP en dergelijke), dan kan die de standaard WordPress-query onderscheppen vóór de plugin. Schakel die uit of neem contact met ons op voor een integratie op maat.

De wachtrij loopt niet vanzelf leeg

WP-Cron gaat alleen af bij bezoeken. Stel op een site met weinig verkeer een systeemcron in:

*/5 * * * * curl -s https://uw-winkel.nl/wp-cron.php > /dev/null 2>&1

Verwijderen

De plugin deactiveren zet de cron stil maar behoudt de gegevens. De plugin verwijderen via de pluginpagina start uninstall.php, dat de twee MySQL-tabellen, de instellingenoptie en de geplande taken verwijdert. Er blijft niets in de database achter.

Veelgestelde vragen

Kan ik de plugin zonder API-sleutel gebruiken?

Nee, semantisch zoeken vereist een provider. Zonder sleutel blijft de plugin inactief en werkt het ingebouwde zoeken van WooCommerce gewoon verder.

Worden de API-sleutels aan de clientzijde blootgesteld?

Nee. Alle aanroepen naar de providers gebeuren aan de serverzijde, vanuit PHP. De sleutel verschijnt nooit in de HTML of in de verzoeken van de browser.

Welke catalogusomvang wordt ondersteund?

De cosinusscan in PHP blijft zeer performant tot ongeveer 50.000 producten op gangbare gedeelde hosting. Daarboven kunt u contact met ons opnemen om een integratie met een aparte approximate-nearest-neighbor-index te bespreken.