Vector Search Native — Documentazione completa

Panoramica

Vector Search Native trasforma la ricerca prodotti di WooCommerce in un motore semantico. Invece di confrontare parole chiave lettera per lettera, il plugin converte ogni prodotto e ogni query in vettori numerici (embeddings) tramite un modello di IA, e calcola poi la loro similarità di significato. Il risultato: un cliente che digita «giacca leggera di cotone per l’estate» trova il vostro «blazer estivo in lino», anche senza nessuna parola in comune.

Il plugin supporta tre provider di embeddings — OpenAI, Voyage AI e Cohere — intercambiabili con un clic, con un’indicizzazione incrementale che chiama l’API solo quando il contenuto di un prodotto è realmente cambiato, e un fallback automatico alla ricerca nativa per parole chiave quando la ricerca vettoriale non basta.

Requisiti

• WordPress 6.2 o superiore
• WooCommerce 7.0 o superiore (testato fino a 9.4)
• PHP 8.0 o superiore
• Una chiave API di uno dei tre provider: OpenAI, Voyage AI o Cohere
• WP-Cron funzionante (o un cron di sistema che chiami wp-cron.php)

Installazione

1. Nel vostro back office WordPress, andate in Plugin → Aggiungi nuovo → Carica plugin.
2. Selezionate il file vector-search-native.zip e cliccate su Installa ora.
3. Cliccate su Attiva. Il plugin crea automaticamente le sue due tabelle (wp_vsn_embeddings e wp_vsn_index_queue) e pianifica il suo task cron.
4. Un nuovo menu Vector Search appare sotto WooCommerce.

Configurazione del provider

Andate in WooCommerce → Vector Search. La sezione «Embedding provider» elenca i tre provider disponibili. Selezionate il vostro nel menu a tendina «Active provider», incollate la vostra chiave API nel blocco corrispondente, scegliete un modello e cliccate su Test connection. Un messaggio verde che conferma la dimensione del vettore (per esempio «Connection OK. Embedding dimension: 1536») valida la configurazione.

Quale modello scegliere

• OpenAI text-embedding-3-small (1536d): il miglior rapporto qualità-prezzo, raccomandato di default.
• OpenAI text-embedding-3-large (3072d): qualità massima, circa 6 volte più caro.
• Voyage voyage-3 (1024d): retrieval eccellente, addestrato per la ricerca.
• Cohere embed-multilingual-v3.0 (1024d): la scelta per cataloghi multilingue IT/EN/FR/ES/DE.

Indicizzazione iniziale

1. Sempre sulla pagina Vector Search, cliccate su Queue all products for reindex. Tutti i prodotti pubblicati entrano nella coda.
2. Cliccate su Auto-process until done. Il plugin elabora la coda per lotti (25 prodotti di default) fino a svuotarla, in diretta dal vostro browser.
3. I contatori «Indexed», «Queued» e «Stuck» si aggiornano in tempo reale.

Potete anche lasciare che WP-Cron faccia il lavoro in background: il task vsn_process_queue gira secondo l’intervallo configurato (5 minuti di default) e svuota progressivamente la coda.

Funzionamento della ricerca

Una volta completata l’indicizzazione, la ricerca prodotti di WooCommerce (frontend e widget standard) viene intercettata automaticamente. Il plugin:

1. Converte la query del visitatore in vettore tramite il provider attivo (con cache di 10 minuti).
2. Calcola la similarità coseno contro tutti i vettori prodotto memorizzati.
3. Trattiene i prodotti sopra la soglia minima di similarità (0,30 di default) entro il limite massimo di candidati (200 di default).
4. Inietta gli ID ordinati per rilevanza nella query WordPress.

Se il numero di risultati è inferiore alla soglia di fallback (3 di default), il plugin si fa da parte e lascia che la ricerca nativa per parole chiave di WooCommerce venga eseguita normalmente. I vostri visitatori non vedono mai una pagina vuota a causa di un problema lato IA.

Impostazioni avanzate

Contenuto indicizzato

La sezione «Content to index» permette di scegliere i campi inclusi nell’embedding: descrizione breve, descrizione lunga, SKU, categorie, tag e attributi. Il titolo del prodotto è sempre indicizzato. Ridurre i campi può affinare la rilevanza su certi cataloghi; includerli tutti massimizza il recall.

Soglie e candidati

• Minimum similarity (0,0 – 1,0): sotto questo punteggio coseno, un prodotto viene scartato. Salite verso 0,4 – 0,5 per filtrare aggressivamente, scendete verso 0,2 per allargare.
• Max candidates: numero di prodotti restituiti a WooCommerce dopo l’ordinamento. La paginazione si applica poi normalmente.
• Fallback threshold: numero minimo di risultati vettoriali prima di passare alle parole chiave.

Coda e cron

• Cron interval: frequenza di elaborazione della coda (1, 5, 15 minuti o ogni ora).
• Batch size (1 – 100): prodotti elaborati per tick. Aumentate con prudenza per evitare i rate limit del provider.
• Ogni prodotto fallito viene ritentato fino a 5 volte, con l’ultimo messaggio di errore conservato in base. Il contatore «Stuck» segnala i prodotti che hanno esaurito i tentativi.

API REST

Cinque endpoint sono esposti sotto /wp-json/vsn/v1/, tutti riservati agli utenti con la capacità manage_woocommerce:

• POST /reindex — mette tutti i prodotti in coda.
• POST /process — elabora un lotto immediatamente.
• GET /stats — restituisce i contatori (totale, indicizzati, in coda, bloccati).
• POST /test — testa una chiave API (parametri: provider, api_key, model).
• POST /clear — svuota interamente l’indice degli embeddings.

Esempio di reindicizzazione completa da uno script di deployment:

curl -X POST https://vostro-negozio.it/wp-json/vsn/v1/reindex 
  -u admin:PASSWORD_APPLICAZIONE

Hook per sviluppatori

vsn_indexed_text

Personalizza il testo inviato al provider per ogni prodotto. Ideale per iniettare campi ACF o metadati di business:

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

vsn_should_engage

Controllo fine di quando la ricerca vettoriale si attiva:

// Disattivare la ricerca vettoriale per le query di una sola parola.
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 );

Negozi multilingue

Con WPML o Polylang, ogni traduzione è un prodotto WordPress distinto: ognuna viene quindi embeddata separatamente, nella propria lingua. Due raccomandazioni:

• Utilizzate un modello multilingue (Cohere embed-multilingual-v3.0 o Voyage voyage-multilingual-2) affinché le query e le schede vengano proiettate nello stesso spazio semantico qualunque sia la lingua.
• Dopo l'aggiunta di una nuova lingua o una campagna massiva di traduzione, lanciate una reindicizzazione completa per coprire i nuovi prodotti.

Risoluzione dei problemi

Prodotti che restano in «Stuck»

Un prodotto passa a «Stuck» dopo 5 fallimenti consecutivi. Cause frequenti: chiave API non valida o scaduta, rate limit del provider, o timeout di rete. Verificate la vostra chiave con Test connection, correggete, poi cliccate su Queue all products for reindex — questo azzera i contatori di tentativi.

La ricerca sembra invariata

• Verificate che la casella Enabled sia spuntata nelle impostazioni generali.
• Verificate che il contatore «Indexed» corrisponda al vostro numero di prodotti.
• Se utilizzate un plugin di ricerca di terze parti (FiboSearch, SearchWP…), questo può cortocircuitare la query WordPress standard prima dell'intercettazione. Disattivatelo o contattateci per un adattamento di integrazione.

La coda non si svuota da sola

WP-Cron si attiva solo con le visite. Su un sito a basso traffico, configurate un cron di sistema:

*/5 * * * * curl -s https://vostro-negozio.it/wp-cron.php > /dev/null 2>&1

Disinstallazione

La disattivazione del plugin sospende il cron ma conserva i dati. L'eliminazione del plugin dalla pagina Plugin attiva uninstall.php, che rimuove le due tabelle MySQL, l'opzione delle impostazioni e i task pianificati. Nessun residuo in base.

FAQ

Posso usare il plugin senza chiave API?

No — la ricerca semantica richiede un provider. Senza chiave, il plugin resta inerte e la ricerca nativa di WooCommerce continua a funzionare normalmente.

Le chiavi API sono esposte lato client?

No. Tutte le chiamate ai provider avvengono lato server, da PHP. La chiave non appare mai nell'HTML né nelle richieste del browser.

Quale volume di catalogo è supportato?

Lo scan coseno in PHP resta molto veloce fino a circa 50.000 prodotti su hosting condiviso standard. Oltre, contattateci per discutere di un'integrazione con un indice approximate-nearest-neighbor dedicato.