# Audit Semantico — Documentazione
> Installazione Prerequisiti PrestaShop 8.0 a 9.x PHP 7.4 minimo (8.x raccomandato) MySQL 5.7+ o MariaDB 10.3+ Una chiave API OpenAI o Mistral (opzionale — è incluso un modo locale senza…
- Pagina:
- Lingua: it
- Aggiornato il: 2026-06-28
- Altre lingue: [fr](https://www.datafirefly.com/documentation/dfsemanticaudit/index.md), [en](https://www.datafirefly.com/en/documentation/dfsemanticaudit/index.md), [es](https://www.datafirefly.com/es/documentation/dfsemanticaudit/index.md), [de](https://www.datafirefly.com/de/documentation/dfsemanticaudit/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfsemanticaudit/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfsemanticaudit/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfsemanticaudit/index.md)
- Indice:
## Installazione
### Prerequisiti
- PrestaShop 8.0 a 9.x
- PHP 7.4 minimo (8.x raccomandato)
- MySQL 5.7+ o MariaDB 10.3+
- Una chiave API OpenAI o Mistral (opzionale — è incluso un modo locale senza API)
### Installare il modulo
1. Decomprimi il file `dfsemanticaudit.zip` scaricato dal tuo account cliente.
2. Carica la cartella `dfsemanticaudit/` in `/modules/` del tuo PrestaShop via FTP, oppure usa l'installazione tramite ZIP da **Moduli → Module manager → Carica un modulo**.
3. Clicca su **Installa**.
### Attivare il modulo
Il modulo crea automaticamente quattro tabelle SQL (`ps_dfsa_content`, `ps_dfsa_audit`, `ps_dfsa_cluster`, `ps_dfsa_assignment`) e una scheda di amministrazione accessibile dal menu di sinistra.
## Configurazione
Prima del primo audit, vai a **Moduli → DataFirefly → Audit Semantico → Configurazione**.
### Scelta del fornitore di embedding
Sono disponibili tre fornitori. La scelta determina la qualità dei cluster ottenuti.
### OpenAI (raccomandato)
Il fornitore predefinito. Usa il modello `text-embedding-3-small` (1.536 dimensioni). Qualità massima, costo marginale: circa 0,02 € per 1.000 prodotti alla prima indicizzazione.
- **Chiave API**: creala da [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
- **Modello**: lascia `text-embedding-3-small` per impostazione predefinita. `text-embedding-3-large` (3.072 dim) dà una qualità leggermente superiore ma costa 6× di più.
### Mistral
Alternativa europea ospitata in Francia. Usa `mistral-embed` (1.024 dimensioni). Tariffazione comparabile a OpenAI.
- **Chiave API**: creala da [console.mistral.ai](https://console.mistral.ai/)
- **Modello**: `mistral-embed`
### TF-IDF locale
Funziona interamente sul tuo server, senza chiamate API, senza costo ricorrente. Usa i principi statistici classici del trattamento del linguaggio (TF-IDF normalizzato) con una dimensione di 384.
- Qualità sufficiente per cataloghi sotto i 500 prodotti.
- Supporta FR, EN, ES, DE, IT (stopwords integrate).
- Nessuna chiave API richiesta.
**Suggerimento** — Puoi cambiare fornitore in qualsiasi momento. Al prossimo audit, tutti i contenuti verranno ri-embedded automaticamente.
### Parametri di audit
- **k (numero di cluster)**: 8 per impostazione predefinita. Intervallo 2–50.
- **Soglia off-topic**: distanza coseno oltre la quale un contenuto viene segnalato. 0,55 per impostazione predefinita. Intervallo 0,1 a 1,5.
### Auto-reindicizzazione
Attivata per impostazione predefinita. Il modulo registra hook sulla creazione, modifica ed eliminazione di prodotti, categorie e pagine CMS. A ogni cambiamento, il contenuto viene contrassegnato per il re-embedding al prossimo run, senza sforzo manuale.
## Lanciare il tuo primo audit
Tre passi da eseguire in ordine dalla **dashboard**.
### Passo 1 — Reindicizza il contenuto
Clicca su **Reindicizza il contenuto**. Il modulo scorre i tuoi prodotti, categorie attive, pagine CMS e produttori, calcola un hash `SHA1` del titolo + estratto, e contrassegna per l'elaborazione solo i contenuti nuovi o modificati.
Per 1.000 elementi, questo passo dura pochi secondi.
### Passo 2 — Genera gli embedding
Clicca su **Genera gli embedding**. Il modulo invia i contenuti contrassegnati come "dirty" al fornitore selezionato in lotti di 50 (OpenAI/Mistral) o in un singolo passaggio locale (TF-IDF). Una barra di progresso segue l'avanzamento.
Per 1.000 elementi:
- OpenAI: ~30 secondi
- Mistral: ~40 secondi
- TF-IDF locale:
### Passo 3 — Lancia l'audit
Clicca su **Lancia l'audit**. Il clustering k-means coseno raggruppa i contenuti in `k` cluster (inizializzazione k-means++, 50 iterazioni massime), etichetta ogni cluster con i suoi top termini (TF×IDF), calcola la distanza di ogni contenuto al suo centroide e identifica gli outlier.
Questo passo richiede meno di un secondo, anche per 5.000 elementi.
## Comprendere il rapporto
### Dashboard
Quattro KPI chiave in alto:
- **Contenuti indicizzati** — totale di prodotti, categorie, CMS e produttori embedded.
- **Pagine off-topic** — numero assoluto, tasso in percentuale e ripartizione per tipo.
- **Cluster tematici** — numero di gruppi tematici identificati.
- **Distanza mediana** — distanza coseno mediana al centroide. Sotto 0,40 = catalogo molto coerente. Sopra 0,60 = catalogo disperso.
### Cluster
Vista **Cluster**: elenco dettagliato ordinato per dimensione, con etichetta automatica (top 5 termini TF×IDF), punteggio di coesione (0 = disperso, 1 = identico) e dimensione (numero di elementi).
Un cluster con **coesione < 0,40** è troppo eterogeneo — spesso è un segnale che bisognerebbe dividere l'argomento in due sotto-temi, o che `k` è troppo basso.
### Mappa semantica 2D
Proiezione di tutti i contenuti su un piano tramite la tecnica **Johnson-Lindenstrauss** (una proiezione casuale che preserva approssimativamente le distanze).
Ogni punto è un contenuto, ogni colore un cluster. Le croci marcano i centroidi. I punti con **contorno rosso** sono gli off-topic. La legenda a destra permette di nascondere/mostrare ogni cluster individualmente cliccandoci sopra.
**Lettura rapida** — Se vedi punti di un colore persi molto lontano dal loro centroide, sono candidati prioritari allo spostamento.
### Pagine off-topic
Vista **Pagine off-topic**: tabella ordinabile dei contenuti la cui distanza coseno al centroide supera la soglia configurata. Per ogni riga:
- Tipo, titolo, URL pubblico e link diretto alla scheda di modifica
- Cluster attuale (con il suo colore)
- Distanza al centroide (più alta = più distante)
- Cluster suggerito (se pertinente)
- Δ Guadagno: riduzione della distanza se il contenuto venisse spostato
### Pagine senza speranza
In fondo alla vista Off-topic, una sezione speciale elenca i contenuti lontani da **tutti i cluster**. Il modulo non ha trovato una destinazione vitale per loro.
Tre opzioni da considerare:
1. **Eliminare** se la pagina non ha traffico SEO o conversione.
2. **Noindex** per preservare il budget di crawl senza perdere lo storico.
3. **Riscrivere** per allineare il contenuto a un cluster esistente.
### Suggerimenti di ristrutturazione
Vista **Suggerimenti**: equivalente a Pagine off-topic ma centrata sull'azione. Tutti gli spostamenti proposti sono elencati con il guadagno di coerenza atteso. Ordina per guadagno decrescente per trattare prima i casi più impattanti.
Il modulo **non** modifica mai automaticamente la tua struttura ad albero. Le modifiche restano sotto il tuo controllo tramite il back-office standard di PrestaShop.
## Esportazione CSV
Da ogni vista del rapporto, un pulsante **Esporta CSV** permette di scaricare i dati grezzi. Utile per:
- Condividere il rapporto con un consulente SEO esterno
- Trattare i dati in Excel/Sheets
- Archiviare lo stato di un audit prima di modificare l'albero
## Automazione tramite cron
Il modulo espone un URL firmato mostrato nella pagina di configurazione. Attiva in modalità headless la catena completa **indicizzazione → embedding → audit**.
Esempio di cron settimanale (ogni lunedì alle 3):
```
0 3 * * 1 wget -q -O /dev/null "https://tuo-negozio.com/modules/dfsemanticaudit/cron.php?token=TUO_TOKEN"
```
Il token è derivato dalla `_COOKIE_KEY_` del tuo PrestaShop e cambia solo con la reinstallazione. Conservalo con cura.
## Costi API
Stima per un catalogo medio (1.000 prodotti):
- **OpenAI text-embedding-3-small**: ~0,02 € la prima volta, poi quasi zero (solo i contenuti modificati vengono rielaborati)
- **OpenAI text-embedding-3-large**: ~0,13 € la prima volta
- **Mistral mistral-embed**: ~0,10 € la prima volta
- **TF-IDF locale**: 0 €
## Multilingua e multi-negozio
Il modulo è nativamente multilingua e multi-negozio. Ogni audit si esegue su una coppia **lingua × negozio** data, usando la lingua di contesto del back-office.
Per auditare il tuo negozio francese e poi quello inglese, cambia lingua nella barra superiore di PrestaShop, quindi lancia un nuovo audit.
**Nota** — Il modulo rispetta la lingua originale di ogni contenuto, senza tentativo di traduzione automatica. I cluster ottenuti saranno diversi per ogni lingua, il che è normale.
## Risoluzione dei problemi
### Il passo "Genera gli embedding" fallisce con un errore 401
La tua chiave API non è valida o è scaduta. Verificala nella pagina di configurazione e riconfigurala se necessario.
### Il passo "Genera gli embedding" fallisce con un errore 429
Hai raggiunto il limite di velocità del tuo fornitore. Attendi qualche minuto e riprova — il modulo riprenderà da dove si era fermato grazie al suo trattamento per lotti.
### Nessun cluster sembra pertinente
Tre piste:
1. Aumenta il numero di cluster (k). Se il tuo catalogo ha 10 tematiche distinte ma k=4, il clustering non potrà separarle.
2. Passa dalla modalità TF-IDF locale a OpenAI o Mistral. Su cataloghi eterogenei, la qualità semantica fa tutta la differenza.
3. Verifica che i titoli e le descrizioni dei tuoi contenuti siano sufficientemente ricchi. Un prodotto con un titolo di 2 parole e senza descrizione non darà un buon embedding.
### Troppe pagine segnalate come off-topic
Aumenta la soglia off-topic (ad esempio da 0,55 a 0,70). È atteso se il tuo catalogo copre legittimamente diverse tematiche ampie.
### Nessuna pagina segnalata come off-topic ma il catalogo sembra incoerente
Abbassa la soglia (ad esempio da 0,55 a 0,40) per stringere il rilevamento.
## FAQ
### È obbligatoria una chiave API?
No. La modalità TF-IDF locale funziona senza connessione esterna. È leggermente meno precisa di OpenAI/Mistral ma sufficiente per iniziare o per un catalogo omogeneo.
### Il modulo modifica automaticamente la mia struttura ad albero?
No. Il modulo si limita a **raccomandare**. Tutti gli spostamenti di contenuto restano a tuo carico tramite il back-office standard di PrestaShop.
### Come scegliere il numero di cluster (k)?
Regola empirica: `k` ≈ numero di categorie principali di primo livello. Per impostazione predefinita k=8 funziona bene tra 100 e 5.000 prodotti. Lancia 2 o 3 audit con diversi valori di k per confrontare se sei indeciso — gli audit precedenti restano nella cronologia.
### I miei vettori vengono inviati a un server terzo?
Con OpenAI o Mistral: sì, i titoli e gli estratti dei tuoi contenuti vengono inviati alla loro API di embedding. Con la modalità TF-IDF locale: no, nessun dato lascia il tuo server.
### Quanto tempo vengono conservati gli audit?
Indefinitamente, fino all'eliminazione manuale dalla dashboard. Puoi consultare la cronologia completa per misurare l'evoluzione della tua coerenza semantica nel tempo.
### Il modulo funziona in multi-negozio?
Sì. Ogni negozio del multistore può avere i propri audit indipendenti.