# 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… - Pagina: - Lingua: it - Aggiornato il: 2026-08-05 - Altre lingue: [fr](https://www.datafirefly.com/documentation/recherche-semantique-ia-prestashop/index.md), [en](https://www.datafirefly.com/en/documentation/ai-semantic-search-prestashop/index.md), [es](https://www.datafirefly.com/es/documentation/busqueda-semantica-ia-prestashop/index.md), [de](https://www.datafirefly.com/de/documentation/ki-semantische-suche-prestashop/index.md), [pl](https://www.datafirefly.com/pl/documentation/recherche-semantique-ia-prestashop/index.md), [pt](https://www.datafirefly.com/pt/documentation/recherche-semantique-ia-prestashop/index.md), [nl](https://www.datafirefly.com/nl/documentation/recherche-semantique-ia-prestashop/index.md) - Indice: 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.