Ricerca Semantica IA per PrestaShop

Questo modulo aggiunge una ricerca semantica basata sull’intelligenza artificiale al tuo negozio PrestaShop. Invece di confrontare letteralmente le parole chiave, comprende il significato della query del cliente tramite embedding vettoriali e mostra i prodotti pertinenti, anche senza una corrispondenza esatta.

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 tre tabelle (dfvectorsearch_index, dfvectorsearch_qcache, dfvectorsearch_log) 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 usare 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.

I contatori mostrano il numero di voci indicizzabili (prodotti × lingue), i vettori già indicizzati, le voci in attesa e il numero di embedding delle query in cache.

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 gli aggiornamenti del 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 disattivati o scollegati dal negozio, così come le lingue disattivate, vengono automaticamente ripuliti dall’indice.

Ricerca nel front

Attiva Autocompletamento front office per agganciare un menu di suggerimenti semantici alla barra di ricerca del tuo tema.

Selettore CSS

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. Per un tema personalizzato, adatta questo selettore al campo di ricerca del tuo tema.

Modalità ibrida

Con la modalità ibrida attivata (consigliata), il modulo combina il punteggio semantico con una corrispondenza per parola chiave sul nome del prodotto. Le corrispondenze esatte di nome vengono così favorite, senza sacrificare la pertinenza semantica.

Soglia e numero di risultati

Il punteggio di similarità minimo (tra 0 e 0,99; consigliato: 0,30) scarta i risultati troppo distanti. Il campo numero massimo di risultati limita il numero di suggerimenti visualizzati.

Analizzare le ricerche

Ogni ricerca viene registrata (query, lingua, negozio, numero di risultati, punteggio migliore). Questi dati ti aiutano a capire cosa cercano davvero i tuoi clienti e a individuare le query senza risultati per arricchire il tuo catalogo.

Cache delle query

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

Risoluzione dei problemi

• Non compare alcun risultato: verifica che l’indice sia costruito (il contatore «Vettori indicizzati» sia > 0) e che la chiave API sia valida.
• L’autocompletamento non compare: verifica il selettore CSS e che l’autocompletamento sia attivato. I messaggi di errore dettagliati sono registrati nei log di PrestaShop.
• Timeout durante l’indicizzazione: riduci la dimensione dei lotti e privilegia l’indicizzazione tramite cron.
• Risultati incoerenti dopo un cambio di modello: rilancia una ricostruzione completa dell’indice.