Ricerca Semantica IA per PrestaShop

Questo modulo aggiunge una ricerca semantica basata sull’intelligenza artificiale al tuo negozio PrestaShop: autocompletamento, pagina dei risultati, blocco «Potrebbe piacerti anche» sulla scheda prodotto e pannello analytics condividono la stessa classifica per significato, calcolata con embedding vettoriali.

Requisiti

• PrestaShop da 8.0 a 9.x
• PHP da 7.4 a 8.3 con l’estensione cURL attivata
• Una chiave API di un provider di embedding: OpenAI, Mistral AI o qualsiasi gateway compatibile con OpenAI

Installazione

1. Nel back office, apri Moduli > Gestore moduli.
2. Fai clic su Carica un modulo e carica il file ZIP.
3. Una volta installato, fai clic su Configura.

Il modulo crea quattro tabelle (dfvectorsearch_index, dfvectorsearch_qcache, dfvectorsearch_log, dfvectorsearch_similar) e una scheda nascosta per le sue chiamate AJAX. Nulla è visibile nel front finché l’indice non viene costruito.

Configurazione del provider di embedding

Nella scheda Impostazioni, scegli il tuo provider e inserisci la tua chiave API.

OpenAI

Seleziona il provider OpenAI e inserisci la tua chiave. Il modello consigliato è text-embedding-3-small (buon rapporto qualità/prezzo). Per la massima precisione su un catalogo esigente, puoi usare text-embedding-3-large.

Mistral AI (hosting europeo)

Seleziona Mistral AI per un trattamento dei dati in Europa, conforme al GDPR. Il modello da utilizzare è mistral-embed.

Gateway compatibile con OpenAI

Seleziona Custom per usare il tuo gateway (proxy interno, Azure OpenAI, ecc.). Inserisci quindi l’URL di base dell’API, ad esempio https://mio-gateway.esempio.com/v1.

La chiave API viene mascherata dopo il salvataggio. Lascia il valore mascherato invariato per conservare la chiave esistente; inserisci una nuova chiave solo se desideri sostituirla.

Dimensioni

Il campo Dimensioni consente di ridurre la dimensione dei vettori per accelerare la ricerca su cataloghi molto grandi. Lascia 0 per la dimensione predefinita del modello. I modelli OpenAI text-embedding-3 supportano dimensioni ridotte (ad esempio 512).

Cambiare provider, modello o numero di dimensioni rende obsoleto l’intero indice: al salvataggio, l’indice viene automaticamente contrassegnato per la ricostruzione completa e la cache delle query viene svuotata. Rilancia poi un’indicizzazione.

Costruire l’indice

Dopo aver salvato la chiave API, vai al riquadro Indice di embedding in cima alla pagina di configurazione.

1. Fai clic su Indicizza ora. Il modulo elabora i prodotti a lotti con una barra di avanzamento, lingua per lingua e negozio per negozio.
2. Lascia la pagina aperta finché lo stato non mostra Indice aggiornato.

Dimensione dei lotti

L’impostazione Dimensione del lotto di indicizzazione controlla quanti prodotti vengono elaborati per chiamata (da 5 a 100). Riducila se il tuo server incontra timeout.

Indicizzazione pianificata (cron)

Per mantenere l’indice sincronizzato automaticamente con il catalogo, copia l’URL di indicizzazione cron mostrata nella configurazione e chiamala regolarmente (ad esempio ogni 15 minuti) dallo scheduler del tuo hosting.

L’URL contiene un token di sicurezza. Ogni chiamata lavora per una ventina di secondi e poi si ferma in modo pulito, per restare compatibile con i limiti di tempo di esecuzione di PHP.

Come funziona la reindicizzazione

Ogni volta che un prodotto viene aggiunto, modificato o eliminato, la voce corrispondente viene contrassegnata per la reindicizzazione. Il modulo calcola un’impronta (checksum) del testo del prodotto: se è cambiato solo il prezzo o lo stock, il testo resta identico e non viene attivata alcuna nuova chiamata API. I prodotti e le lingue disattivati vengono automaticamente ripuliti dall’indice.

Ricerca nel front

Autocompletamento

Attiva Autocompletamento front office per agganciare un menu di suggerimenti semantici alla barra di ricerca del tuo tema. Il campo Selettore CSS del campo di ricerca indica al modulo a quale campo agganciarsi. Il valore predefinito #search_widget input[type="text"] funziona con i temi basati su classic.

Disattivare l’autocompletamento del tema

L’impostazione Disattiva l’autocompletamento del tema (attiva per impostazione predefinita) rimuove i suggerimenti di ricerca nativi (ps_searchbar e simili) per evitare un doppio menu a tendina. Il modulo rimuove lo script nativo e nasconde qualsiasi menu iniettato da un tema personalizzato.

Modalità ibrida

Con la modalità ibrida attivata (consigliata), la classifica semantica viene messa in testa e i risultati nativi per parola chiave assenti vengono aggiunti in coda. Non ottieni mai meno risultati della ricerca originale.

Soglia e numero di risultati

Il punteggio di similarità minimo (tra 0 e 0,99; consigliato: 0,30) scarta i risultati troppo distanti. Il numero massimo di risultati limita i suggerimenti mostrati nell’autocompletamento.

La pagina dei risultati di ricerca

L’impostazione Prendi il controllo della pagina dei risultati (attiva per impostazione predefinita) fa fornire al modulo la classifica della pagina tramite il hook productSearchProvider, il meccanismo ufficiale di PrestaShop usato dalla navigazione a faccette. In concreto:

• autocompletamento e pagina mostrano gli stessi prodotti, nello stesso ordine;
• paginazione e ordinamenti del tema restano funzionanti (l’ordinamento «rilevanza» conserva l’ordine semantico; prezzo, nome e data vengono ricalcolati all’interno della classifica);
• se l’API di embedding non è disponibile, il modulo ripiega silenziosamente sui risultati nativi e registra l’incidente: la pagina di ricerca non si rompe mai.

Il modulo si attiva solo su una ricerca testuale. Categorie, pagine di tag e altri elenchi conservano i loro meccanismi nativi.

Prodotti simili (Potrebbe piacerti anche)

Il Blocco prodotti simili (attivo per impostazione predefinita) mostra su ogni scheda prodotto un «Potrebbe piacerti anche» calcolato per prossimità semantica tra i vettori già memorizzati nel tuo database. Non viene effettuata alcuna chiamata API: il blocco funziona anche senza chiave API finché esiste l’indice.

• Numero di prodotti simili: da 2 a 12 (predefinito 6).
• Punteggio minimo dei prodotti simili: soglia dedicata, indipendente da quella di ricerca (consigliato: 0,45). Al di sotto, il prodotto non appare, anche se vengono mostrate meno schede. Modificarla svuota automaticamente la cache dei simili.
• Un bonus di affinità favorisce i prodotti della stessa categoria predefinita e della stessa marca.
• I risultati sono in cache 24 ore per prodotto e invalidati automaticamente alla reindicizzazione.
• Il rendering usa le miniature native del tuo tema: etichette, wishlist, vista rapida e stili hover inclusi.

Su un piccolo catalogo dimostrativo dove tutte le schede condividono lo stesso testo di marketing, le similarità sono naturalmente più lasche. Alza la soglia a 0,55-0,60 per conservare solo le corrispondenze vicine.

Statistiche e analytics

La pagina di configurazione mostra un pannello calcolato sugli ultimi 30 giorni: numero di ricerche, tasso senza risultati, risultati medi per ricerca, istogramma del volume giornaliero, top 20 delle query (conteggio, risultati medi, punteggio migliore) e top 20 delle query senza risultati.

Le query senza risultati sono una miniera d’oro: indicano esattamente cosa cercano i tuoi clienti senza trovarlo, e quindi cosa aggiungere al tuo catalogo o ai tuoi sinonimi.

• Il pulsante Esporta CSV scarica il registro completo (separatore punto e virgola) con la fonte di ogni ricerca: autocompletamento o pagina dei risultati.
• Il registro viene ripulito automaticamente dopo 365 giorni.

Cache delle query

Gli embedding delle query dei clienti sono in cache per 30 giorni. Le ricerche ripetute sono istantanee e non vengono rifatturate. Il pulsante Svuota la cache delle query consente di reimpostarla in qualsiasi momento.

Aggiornamento del modulo

Se aggiorni il modulo sostituendone i file (al di fuori del Gestore moduli), apri una volta la pagina di configurazione: il modulo registra allora automaticamente i hook mancanti, crea le tabelle e le colonne mancanti e imposta i nuovi valori predefiniti. I file CSS e JS del front integrano un cache-buster, non serve svuotare la cache del browser.

Risoluzione dei problemi

• Non compare alcun risultato: verifica che l’indice sia costruito (contatore «Vettori indicizzati» > 0) e che la chiave API sia valida.
• Compaiono due menu a tendina: verifica che Disattiva l’autocompletamento del tema sia attivo, poi svuota una volta la cache di PrestaShop.
• Autocompletamento e pagina dei risultati differiscono: apri una volta la pagina di configurazione del modulo (il hook della pagina dei risultati viene registrato automaticamente) e verifica che Prendi il controllo della pagina dei risultati sia attivo.
• Il blocco Potrebbe piacerti anche è vuoto: l’indice deve essere costruito per la lingua e il negozio correnti; altrimenti abbassa il punteggio minimo dei prodotti simili.
• Timeout durante l’indicizzazione: riduci la dimensione dei lotti e privilegia l’indicizzazione via cron.
• Risultati incoerenti dopo un cambio di modello: rilancia una ricostruzione completa dell’indice.