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

- Pagina: <https://www.datafirefly.com/it/documentation/topic-cluster-detector/>
- Lingua: it
- Aggiornato il: 2026-06-28
- Altre lingue: [fr](https://www.datafirefly.com/documentation/topic-cluster-detector/index.md), [en](https://www.datafirefly.com/en/documentation/topic-cluster-detector/index.md), [es](https://www.datafirefly.com/es/documentation/topic-cluster-detector/index.md), [de](https://www.datafirefly.com/de/documentation/topic-cluster-detector/index.md), [pl](https://www.datafirefly.com/pl/documentation/topic-cluster-detector/index.md), [nl](https://www.datafirefly.com/nl/documentation/topic-cluster-detector/index.md), [pt](https://www.datafirefly.com/pt/documentation/topic-cluster-detector/index.md)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

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)

**Da ricordare.** Il modulo non crea pagine direttamente in PrestaShop. Vi fornisce una bozza da copiare-incollare in una nuova pagina CMS o landing di categoria, mantenendo la decisione editoriale nelle vostre mani.

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

| Chiave | Default | Descrizione |
| --- | --- | --- |
| `DFTC_MODE` | `tfidf` | Modalità di clustering: `tfidf` (locale), `openai` o `mistral` |
| `DFTC_K_AUTO` | abilitato | Se abilitato, calcola automaticamente k = ceil(√(N/2)) limitato a [5, 30] |
| `DFTC_K_MANUAL` | 12 | Valore di k usato se `DFTC_K_AUTO` è disabilitato |
| `DFTC_MAX_ITER` | 60 | Numero massimo di iterazioni del k-means |
| `DFTC_MIN_CLUSTER_SIZE` | 3 | Dimensione minima di un cluster; al di sotto, scartato |

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

| Chiave | Default | Descrizione |
| --- | --- | --- |
| `DFTC_MIN_DOC_FREQ` | 2 | Termine ignorato se appare in meno di N prodotti |
| `DFTC_MAX_DOC_FREQ_RATIO` | 0.50 | Termine ignorato se appare in più del X% del catalogo |
| `DFTC_NGRAM_MAX` | 2 | 1 = unigrammi, 2 = unigrammi + bigrammi |
| `DFTC_TOP_TERMS_COUNT` | 8 | Numero di termini mostrati per cluster |

### API di embeddings

| Chiave | Descrizione |
| --- | --- |
| `DFTC_OPENAI_API_KEY` | Bearer token OpenAI (sk-...) |
| `DFTC_OPENAI_MODEL` | Modello (default `text-embedding-3-small`) |
| `DFTC_MISTRAL_API_KEY` | Chiave API Mistral |
| `DFTC_MISTRAL_MODEL` | Modello (default `mistral-embed`) |
| `DFTC_BATCH_SIZE` | Numero di prodotti per chiamata API (default 32) |

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

**Suggerimento.** La cache embeddings è automatica: se rilanciate un'esecuzione sullo stesso catalogo senza modificare i testi, i vettori vengono recuperati dalla tabella `df_topicclusters_embedding_cache` senza nuova chiamata API.

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

**Importante.** Il modulo imposta `set_time_limit(0)` e `memory_limit=1024M` per la durata dell'esecuzione. Su hosting molto vincolati, queste direttive possono essere ignorate. Preferite un'esecuzione notturna o usate il limite prodotti per suddividere.

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

**Best practice SEO.** Una pillar page di qualità ha almeno 1.500 parole, integra link interni ai prodotti del cluster, e usa i top-termini naturalmente nel contenuto. La bozza generata è un punto di partenza, non un deliverable finale.

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

**Supporto.** Per qualsiasi domanda o bug, contattate [support@datafirefly.com](mailto:support@datafirefly.com). I feedback sono preziosi per orientare la roadmap.