# 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…

- Pagina: <https://www.datafirefly.com/it/documentation/ai-visual-search-shop-the-look/>
- Lingua: it
- Aggiornato il: 2026-06-17
- Altre lingue: [fr](https://www.datafirefly.com/documentation/ai-visual-search-shop-the-look/index.md), [en](https://www.datafirefly.com/en/documentation/ai-visual-search-shop-the-look/index.md), [es](https://www.datafirefly.com/es/documentation/ai-visual-search-shop-the-look/index.md), [de](https://www.datafirefly.com/de/documentation/ai-visual-search-shop-the-look/index.md), [pl](https://www.datafirefly.com/pl/documentation/ai-visual-search-shop-the-look/index.md), [pt](https://www.datafirefly.com/pt/documentation/ai-visual-search-shop-the-look/index.md), [nl](https://www.datafirefly.com/nl/documentation/ai-visual-search-shop-the-look/index.md)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

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.

Compatibile con PrestaShop dalla 1.7.6 alla 9.x, su PHP da 7.4 a 8.3. Nessun override del core, nessuna dipendenza da Composer.

## 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.

Dopo aver salvato fornitore e chiave, usa il pulsante **Prova il fornitore** nel pannello dell'indice per validare la connessione prima di indicizzare.

### 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.

La ricerca per similarità del coseno viene eseguita lato server e resta fluida fino a circa 10.000 prodotti, senza alcun database vettoriale esterno da ospitare.

## 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.

Il rilevamento di più articoli richiede un fornitore vision (OpenAI o Mistral). Con Voyage o Cohere, lo Shop the Look ripiega con eleganza su una similarità dell'intera immagine («look completo»).

## 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.

Ogni fornitore produce uno spazio vettoriale e una dimensione diversi. Dopo aver cambiato il fornitore attivo, reindicizza il catalogo. I vettori degli altri fornitori vengono conservati ma ignorati nella ricerca; il back office mostra il numero di prodotti indicizzati per il fornitore corrente.

## 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.