Ricerca Visuale per Immagine e Shop the Look IA — Guida completa

Questo modulo aggiunge la ricerca prodotti per immagine al tuo negozio: il cliente trascina una foto e ottiene gli articoli del tuo catalogo visivamente più simili, ordinati per punteggio di similarità. La modalità Shop the Look rileva ogni articolo di un’intera scena e propone i prodotti corrispondenti. Il motore è agnostico: scegli tu il fornitore IA (Voyage, Cohere, OpenAI o Mistral) e usi la tua chiave. Questa guida copre installazione, configurazione, indicizzazione del catalogo e funzionamento della ricerca.

Installazione

1. Scarica l’archivio dfvisualsearch.zip dal tuo account DataFirefly.
2. Back office PrestaShop → Moduli → Carica un modulo → invia lo ZIP.
3. Il modulo crea la sua tabella di indice, registra i suoi hook e aggiunge una scheda di amministrazione dedicata.

Configurazione generale

Vai su Moduli → Ricerca Visuale & Shop the Look IA → Configura.

Scegliere il fornitore

Seleziona il motore dall’elenco, poi inserisci la chiave API corrispondente. Paghi l’IA in base al consumo presso il fornitore, senza abbonamenti aggiunti dal modulo.

• Voyage e Cohere: embedding multimodali diretti dell’immagine.
• OpenAI e Mistral: analisi vision e poi embedding, e sbloccano in più lo Shop the Look.
• Chiave API: memorizzata lato server, mai esposta al front office. Ogni fornitore ha il proprio modello e la propria dimensione del vettore configurabili.

Comportamento

• Numero di risultati: quanti prodotti mostrare per una ricerca per immagine.
• Similarità minima (0–1): 0 mostra tutto ordinato per pertinenza; aumentala (ad esempio 0,2–0,4) per scartare le corrispondenze deboli. Da calibrare in base al fornitore.
• Attivare lo Shop the Look e prodotti per articolo rilevato.
• Prodotti simili nella scheda prodotto e il loro numero.
• Inserire il pulsante fotocamera nell’intestazione, oppure posizionarlo manualmente nel tuo tema tramite l’hook displayDfVisualSearchButton.
• Dimensione massima di upload e reindicizzazione automatica al salvataggio di un prodotto.

Indicizzare il catalogo

Nel pannello Indice del catalogo della configurazione:

1. Clicca su Indicizza / reindicizza il catalogo: il modulo elabora i prodotti a lotti, con una barra di avanzamento, senza rischio di timeout del server.
2. Il contatore mostra i prodotti indicizzati per il fornitore attivo.
3. Svuota l’indice rimuove i vettori del negozio corrente.

L’indicizzazione trasforma l’immagine di copertina di ogni prodotto in un vettore memorizzato nel database. Una volta indicizzato, un prodotto viene ri-codificato solo se la sua immagine cambia.

Come funziona la ricerca

Ogni immagine viene trasformata in un vettore (embedding) normalizzato. La foto inviata dal cliente viene codificata dallo stesso fornitore, poi confrontata con l’indice tramite similarità del coseno — che, su vettori normalizzati, si riduce a un semplice prodotto scalare. I prodotti vengono ordinati per punteggio decrescente e filtrati in base alla soglia minima configurata.

• Voyage e Cohere codificano l’immagine direttamente.
• OpenAI e Mistral descrivono l’immagine con un modello vision, poi codificano quella descrizione: indicizzazione e query vivono così nello stesso spazio vettoriale.

Shop the Look

Da una foto di scena, lo Shop the Look identifica ogni articolo visibile e avvia una ricerca per articolo, presentando i risultati in gruppi distinti.

Prodotti visivamente simili

Nella scheda prodotto compare automaticamente un blocco «prodotti visivamente simili». Riutilizza il vettore già calcolato durante l’indicizzazione del prodotto: non viene inviata alcuna richiesta aggiuntiva all’IA, quindi la raccomandazione non aggiunge costi ricorrenti.

Visualizzazione lato cliente

Il pulsante fotocamera apre una finestra in cui il cliente trascina e rilascia una foto o la seleziona. Compare un’anteprima, poi i risultati vengono mostrati come schede prodotto con il loro punteggio di similarità in percentuale. Se lo Shop the Look è attivo, il cliente può spuntare l’opzione per ottenere i risultati raggruppati per articolo rilevato.

Scegliere un fornitore

Tutti i fornitori gestiscono la ricerca per immagine. La scelta dipende dalle tue esigenze:

• Voyage / Cohere: embedding multimodali diretti, semplici e rapidi, senza Shop the Look.
• OpenAI / Mistral: analisi vision che sblocca il rilevamento di più articoli dello Shop the Look.

Compatibilità e note tecniche

• PrestaShop dalla 1.7.6 alla 9.x, multinegozio e multilingua; ogni negozio mantiene il proprio indice.
• Controller di amministrazione legacy (nessun controller Symfony) per la compatibilità PS8/PS9.
• Hook utilizzati: displayHeader, displayTop, displayDfVisualSearchButton, displayFooterProduct, actionProductSave, actionProductDelete.
• Vettori memorizzati normalizzati nel database, codificati per un’archiviazione robusta; ricerca per prodotto scalare.
• Un limitatore anti-abuso per sessione protegge la tua quota IA.
• Endpoint di ricerca AJAX tramite il link del modulo; risposta in formato JSON.

FAQ e risoluzione dei problemi

Il pulsante di ricerca non compare. Verifica che un fornitore sia configurato e che la sua chiave sia valida (pulsante Prova il fornitore), poi che l’inserimento nell’intestazione sia attivo o che l’hook sia posizionato nel tuo tema.

La ricerca non restituisce risultati. Assicurati che il catalogo sia stato indicizzato per il fornitore attivo e abbassa la similarità minima se è troppo alta per lo spazio vettoriale del fornitore.

Lo Shop the Look restituisce un solo gruppo. Il fornitore attivo non supporta il rilevamento (Voyage o Cohere). Passa a OpenAI o Mistral per il rilevamento di più articoli, poi reindicizza.

Ho cambiato fornitore e i risultati sono incoerenti. Esegui una reindicizzazione completa: i vettori devono essere ricalcolati nello spazio del nuovo fornitore.