Rilevatore di Topic Cluster — Documentazione

Questa documentazione descrive l’installazione, la configurazione e l’utilizzo del modulo Rilevatore di Topic Cluster su PrestaShop 8 e 9. Il modulo rileva automaticamente i raggruppamenti tematici del vostro catalogo tramite clustering semantico e suggerisce le pillar page mancanti con una bozza SEO completa per ogni opportunità.

Presentazione

Il Rilevatore di Topic Cluster analizza il vostro catalogo prodotti per far emergere i topic cluster realmente presenti nella vostra offerta, e poi rileva le pillar page mancanti: quei temi trasversali fortemente coperti dai vostri prodotti ma senza una pagina-madre strutturante (CMS o categoria).

Per ogni gap rilevato, il modulo genera una bozza completa:

• Titolo H1 ottimizzato SEO
• Slug URL-safe
• Meta descrizione
• Piano H2 markdown completo
• Lista di parole chiave target
• Punteggio di priorità (dimensione × coesione)

Installazione

Prerequisiti

• PrestaShop 8.0+ o 9.x
• PHP 8.0 minimo (PHP 8.1 o 8.2 consigliato)
• memory_limit di almeno 512 MB (1024 MB consigliato per cataloghi grandi)
• Opzionale: chiave API OpenAI o Mistral per la modalità embeddings

Procedura di installazione

1. Scaricate il file dftopicclusters.zip dalla vostra area cliente DataFirefly.
2. Nel back-office PrestaShop, andate a Moduli → Module Manager e cliccate su Carica un modulo.
3. Selezionate il ZIP e confermate. Il modulo si installa automaticamente.
4. Una volta installato, cliccate su Configura.

All’installazione, il modulo crea automaticamente:

• Le 5 tabelle SQL con prefisso df_topicclusters_
• La tab padre DataFirefly sotto il menu Migliora (se non esiste già)
• La tab figlia Topic Clusters sotto questo padre
• Le 19 chiavi di configurazione predefinite

Primo accesso

Una volta installato, il modulo è accessibile tramite Migliora → DataFirefly → Topic Clusters. La dashboard vi presenta il modulo di lancio di una nuova analisi e la cronologia delle esecuzioni precedenti (vuota al primo accesso).

Configurazione

Cliccate sul pulsante Impostazioni in alto a destra della dashboard per accedere alla pagina di configurazione. Le impostazioni sono raggruppate in cinque sezioni.

Generale

Estrazione del testo

Permette di scegliere quali campi del prodotto sono iniettati nell’analisi. La ponderazione per campo è fissa (nome × 3, meta × 2, descrizione breve × 2, categorie × 2, tag × 2, descrizione lunga × 1, caratteristiche × 1).

• DFTC_INCLUDE_DESCRIPTION — Includere la descrizione lunga (consigliato: abilitato)
• DFTC_INCLUDE_CATEGORIES — Includere i nomi delle categorie (consigliato: abilitato)
• DFTC_INCLUDE_TAGS — Includere i tag PrestaShop (consigliato: abilitato)
• DFTC_INCLUDE_FEATURES — Includere le caratteristiche prodotto (consigliato: disabilitato salvo caratteristiche molto descrittive)

Impostazioni TF-IDF

API di embeddings

Rilevamento delle pillar page

• DFTC_PILLAR_MATCH_THRESHOLD — Soglia di match (default 0.45). Al di sotto, il cluster è contrassegnato come pillar gap. Aumentate la soglia per essere più severi, abbassatela per essere più tolleranti.

Le tre modalità in dettaglio

Modalità TF-IDF (consigliata per iniziare)

Il TF-IDF (Term Frequency × Inverse Document Frequency) è un metodo statistico classico in NLP. Il modulo costruisce un vocabolario a partire da tutti i testi dei prodotti, filtra i termini troppo rari o troppo frequenti, e rappresenta poi ogni prodotto come un vettore sparso in questo spazio.

Vantaggi: 100% locale, istantaneo, gratuito, nessuna dipendenza esterna. Eccellente per cataloghi lessicalmente omogenei (un dominio, un vocabolario coerente).

Limiti: non comprende i sinonimi (due prodotti che usano termini diversi per lo stesso concetto saranno raggruppati male).

Modalità embeddings OpenAI

Utilizza l’API OpenAI text-embedding-3-small per default. Ogni prodotto è rappresentato da un vettore denso di 1536 dimensioni che cattura la sua semantica.

Vantaggi: comprende sinonimi, varianti lessicali e contesto. Eccellente per cataloghi diversificati o con descrizioni narrative.

Costo indicativo: circa 0,02 USD per milione di token, cioè meno di 0,10 USD per un catalogo di 1.000 prodotti.

Modalità embeddings Mistral

Utilizza l’API Mistral mistral-embed per default. Modello multilingue performante, particolarmente buono in francese.

Vantaggi: ospitato in Europa (conformità GDPR facilitata), eccellente sui contenuti francofoni, prezzo competitivo.

Lanciare un’analisi

Dalla dashboard, il modulo Lancia una nuova analisi propone sei parametri:

• Lingua — la lingua in cui i testi prodotto saranno estratti e analizzati. Lanciate un’esecuzione distinta per ogni lingua attiva del vostro shop.
• Modalità — TF-IDF, OpenAI o Mistral (sovrascrive l’impostazione predefinita solo per questa esecuzione).
• Numero di cluster (k) — Lasciate 0 per l’auto-k. Altrimenti, forzate un valore tra 2 e 100.
• Dimensione minima — Cluster più piccoli scartati (default 3).
• Soglia pillar — Soglia di match al di sotto della quale un cluster è contrassegnato come gap (default 0.45).
• Limite prodotti — Limita il numero di prodotti analizzati (utile per debug o test rapido). Lasciate 0 per analizzare tutto il catalogo.

Cliccate su Lancia analisi. L’esecuzione inizia immediatamente. Per un catalogo di 1.000 prodotti:

• Modalità TF-IDF: 5 a 15 secondi
• Modalità embeddings (prima esecuzione): 30 secondi a 2 minuti a seconda del batch size
• Modalità embeddings (esecuzioni successive con cache calda): equivalente al TF-IDF

Leggere i risultati

Una volta completata l’esecuzione, accedete alla pagina di dettaglio. Ogni cluster è visualizzato come una scheda con quattro sezioni.

Intestazione del cluster

L’intestazione combina un badge di stato, un numero di cluster e un’etichetta generata. Il badge è:

• PILLAR GAP (arancione) — Nessuna pillar page esistente copre questo argomento. Forte opportunità.
• OK (verde) — Una pagina CMS o categoria copre già questo argomento (il modulo l’ha matchato).

L’etichetta è composta dai 3 top-termini del cluster uniti da ·. Esempio: “sneakers · pelle premium · scarpe”.

Statistiche

• Prodotti — Numero di prodotti nel cluster
• Coesione — Similarità media dei membri al centroide (0 a 100%). Più è alta, più il cluster è omogeneo.
• Match — Punteggio di match con la migliore pillar page esistente. Se al di sotto della soglia → gap.

Top termini

I termini più rappresentativi del cluster. In modalità TF-IDF, sono i termini con la componente più forte nel centroide. In modalità embeddings, il modulo calcola un TF interno al cluster ponderato per l’IDF globale per far emergere i termini distintivi.

Suggerimento di pillar page

Presente solo se il cluster è contrassegnato come gap. Contiene:

• Titolo — Titolo H1 ottimizzato SEO in linguaggio naturale
• Slug — URL-safe, in kebab-case
• Meta descrizione — 150-160 caratteri
• Priorità — Punteggio combinato dimensione (0.6) × coesione (0.4)
• Piano suggerito — Piano H2 in markdown con sezioni classiche (intro, cosa è, come scegliere, comparativa, migliori prodotti, casi d’uso, errori da evitare, FAQ, CTA)

Prodotti del cluster

Lista dei prodotti raggruppati con il loro punteggio di similarità al centroide, ordinati per similarità decrescente. Cliccate sull’ID del prodotto per aprire la scheda direttamente in una nuova finestra.

Workflow consigliato

Ecco un utilizzo tipico del modulo in 4 passi.

1. Primo audit — Lanciate un’esecuzione TF-IDF nella vostra lingua principale con i parametri predefiniti. Esaminate i cluster contrassegnati come gap: sono editorialmente rilevanti?
2. Triage — Per ogni gap, usate il pulsante Ignora se il cluster non merita una pillar page (per esempio un raggruppamento accidentale di prodotti eterogenei). I gap rimanenti sono le vostre priorità.
3. Redazione — Per ogni gap mantenuto, create una nuova pagina CMS in PrestaShop con il titolo, slug e meta della bozza. Usate il piano H2 come scheletro di redazione. Cliccate su Contrassegna Fatto una volta pubblicato.
4. Rilancio — Dopo la pubblicazione delle nuove pagine, rilanciate un’esecuzione. I gap precedenti dovrebbero ora essere OK (il modulo rileverà le nuove pillar page).

Esportazione

Dalla pagina di dettaglio di un’esecuzione, due pulsanti in alto a destra permettono di esportare:

• CSV — Tabella con una riga per cluster, colonne: id_cluster, label, n_members, coesione, pillar_gap, match_score, suggested_title, suggested_slug, suggested_meta, priority_score, target_keywords. Codifica UTF-8 con BOM (compatibile Excel).
• JSON — Esportazione completa che include la lista dei prodotti per cluster e il piano markdown integrale. Ideale per automazione o integrazione esterna.

Architettura tecnica

Database

Il modulo crea 5 tabelle con prefisso df_topicclusters_:

• run — Metadati di ogni esecuzione (modalità, lingua, stato, durata, contatori)
• cluster — Cluster individuali (label, top termini JSON, coesione, flag pillar_gap, match_score)
• cluster_product — Appartenenza prodotto → cluster con punteggio di similarità
• pillar — Suggerimenti di pillar page (titolo, slug, meta, outline, priorità, stato)
• embedding_cache — Cache dei vettori di embeddings indicizzata per hash del testo

PSR-4 e autoload

Il namespace radice è DataFirefly/TopicClusters/. Un autoload manuale è registrato tramite spl_autoload_register nel file principale del modulo, quindi nessuna dipendenza Composer è richiesta.

Controllers e compatibilità PS 8 / PS 9

Il modulo utilizza un ModuleAdminController legacy (e non un controller Symfony) per garantire la compatibilità con entrambe le versioni principali. Le query SQL sono scritte per rispettare gli schemi di entrambe le versioni, in particolare la rimozione della colonna meta_keywords in PS 9.

Prestazioni e limiti

• Cataloghi fino a 1.000 prodotti — Esecuzioni in pochi secondi. Nessuna preoccupazione particolare.
• 1.000 a 10.000 prodotti — Modalità TF-IDF rimane veloce (10-60 s). Modalità embeddings: prevedere 1 a 5 minuti per la prima esecuzione, istantaneo dopo grazie alla cache.
• Più di 10.000 prodotti — Privilegiare il parametro Limite prodotti per suddividere, o aumentare memory_limit a 2 GB.

La complessità del k-means è O(n × k × iter × d) dove n è il numero di prodotti, k il numero di cluster, iter il numero di iterazioni (tipicamente 10-30) e d la dimensione dei vettori (variabile in TF-IDF, 1536 in OpenAI).

Risoluzione dei problemi

Nessun cluster rilevato

Verificate che i vostri prodotti abbiano contenuto testuale nella lingua analizzata (almeno un nome e idealmente una descrizione). Se DFTC_MIN_DOC_FREQ è troppo alto per il vostro catalogo, abbassatelo a 1.

Tutti i cluster sono contrassegnati come pillar gap

La soglia DFTC_PILLAR_MATCH_THRESHOLD è probabilmente troppo alta. Provate 0.30 invece di 0.45 se il vostro shop ha poche pagine CMS. Verificate anche che le vostre pagine CMS e categorie siano attive.

Errore “Unknown column meta_keywords”

Questo errore si verifica su PrestaShop 9 con una versione precedente del modulo. Aggiornate alla versione 1.0.0 o superiore, che rimuove tutti i riferimenti a meta_keywords (colonna rimossa in PS 9).

Errore “Compile Error: Access level to processExport() must be public”

Questo errore si verificava in una versione pre-1.0.0. Il nome del metodo è ora doExport() per evitare la collisione con AdminControllerCore. Aggiornate il modulo.

L’esecuzione fallisce con errore API

Verificate che la chiave API inserita nella configurazione sia valida e abbia crediti. Testate con curl in CLI per confermare che il server possa raggiungere api.openai.com o api.mistral.ai.

Prossime evoluzioni

• Creazione diretta di pagine CMS dalla bozza (in un clic)
• Confronto di esecuzioni (prima/dopo la pubblicazione delle pillar page)
• Visualizzazione grafica della rete semantica inter-cluster
• Supporto degli embeddings Cohere e Voyage AI
• Cron automatico per riesecuzioni periodiche