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

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: <1 secondo

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.

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.

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.