# Detector van Topic Clusters: volledige gids

> Deze documentatie beschrijft de installatie, de configuratie en het gebruik van de module Detector van Topic Clusters op PrestaShop 8 en 9. De module vindt automatisch de thematische groeperingen in…

- Pagina: <https://www.datafirefly.com/nl/documentation/topic-cluster-detector/>
- Taal: nl
- Bijgewerkt op: 2026-09-09
- Andere talen: [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), [it](https://www.datafirefly.com/it/documentation/topic-cluster-detector/index.md), [pl](https://www.datafirefly.com/pl/documentation/topic-cluster-detector/index.md), [pt](https://www.datafirefly.com/pt/documentation/topic-cluster-detector/index.md)
- Index: <https://www.datafirefly.com/nl/documentation/llms.txt>

Deze documentatie beschrijft de installatie, de configuratie en het gebruik van de module **Detector van Topic Clusters** op PrestaShop 8 en 9. De module vindt automatisch de thematische groeperingen in uw catalogus via semantische clustering en stelt de ontbrekende pillar pages voor, met voor elke kans een volledig SEO-concept.

## Overzicht

De Detector van Topic Clusters analyseert uw productcatalogus om de **topic clusters die daadwerkelijk in uw aanbod zitten** naar boven te halen, en spoort daarna de **ontbrekende pillar pages** op: die overkoepelende onderwerpen die uw producten sterk afdekken maar waarvoor geen structurerende moederpagina (CMS of categorie) bestaat.

Voor elke gevonden leemte genereert de module een volledig concept:

- SEO-geoptimaliseerde H1-titel
- URL-veilige slug
- Metabeschrijving
- Volledig H2-plan in markdown
- Lijst met doelzoekwoorden
- Prioriteitsscore (omvang × cohesie)

**Onthoud dit.** De module maakt geen pagina's aan in PrestaShop. Hij levert een concept dat u kopieert naar een nieuwe CMS-pagina of categorielandingspagina, zodat de redactionele beslissing bij u blijft.

## Installatie

### Vereisten

- PrestaShop **8.0+** of **9.x**
- PHP **8.0 minimaal** (PHP 8.1 of 8.2 aanbevolen)
- `memory_limit` van minimaal 512 MB (1024 MB aanbevolen voor grote catalogi)
- Optioneel: een API-sleutel van OpenAI of Mistral voor de embeddingsmodus

### Installatieprocedure

1. Download het bestand `dftopicclusters.zip` vanuit uw DataFirefly-klantenzone.
2. Ga in de PrestaShop-backoffice naar **Modules → Modulebeheer** en klik op **Een module uploaden**.
3. Selecteer de ZIP en bevestig. De module installeert zichzelf automatisch.
4. Klik na de installatie op **Configureren**.

Bij de installatie maakt de module automatisch het volgende aan:

- De 5 SQL-tabellen met voorvoegsel `df_topicclusters_`
- Het bovenliggende tabblad **DataFirefly** onder het menu Verbeteren (als dat er nog niet is)
- Het onderliggende tabblad **Topic Clusters** daaronder
- De 19 standaard configuratiesleutels

### Eerste toegang

Na de installatie is de module bereikbaar via **Verbeteren → DataFirefly → Topic Clusters**. Het dashboard toont het formulier om een nieuwe analyse te starten en de historiek van eerdere runs (bij de eerste keer leeg).

## Configuratie

Klik op de knop **Instellingen** rechtsboven op het dashboard om naar de configuratiepagina te gaan. De instellingen zijn in vijf secties gegroepeerd.

### Algemeen

| Sleutel | Standaard | Beschrijving |
| --- | --- | --- |
| `DFTC_MODE` | `tfidf` | Clusteringmodus: `tfidf` (lokaal), `openai` of `mistral` |
| `DFTC_K_AUTO` | aan | Berekent, indien actief, automatisch k = ceil(√(N/2)), begrensd tot [5, 30] |
| `DFTC_K_MANUAL` | 12 | Waarde van k die wordt gebruikt als `DFTC_K_AUTO` uitstaat |
| `DFTC_MAX_ITER` | 60 | Maximaal aantal iteraties van de k-means |
| `DFTC_MIN_CLUSTER_SIZE` | 3 | Minimale omvang van een cluster; daaronder wordt die verworpen |

### Tekstextractie

Hiermee kiest u welke productvelden in de analyse meegaan. De weging per veld ligt vast (naam × 3, meta × 2, korte beschrijving × 2, categorieën × 2, tags × 2, lange beschrijving × 1, kenmerken × 1).

- `DFTC_INCLUDE_DESCRIPTION`: de lange beschrijving meenemen (aanbevolen: aan)
- `DFTC_INCLUDE_CATEGORIES`: de categorienamen meenemen (aanbevolen: aan)
- `DFTC_INCLUDE_TAGS`: de PrestaShop-tags meenemen (aanbevolen: aan)
- `DFTC_INCLUDE_FEATURES`: de productkenmerken meenemen (aanbevolen: uit, tenzij uw kenmerken erg beschrijvend zijn)

### TF-IDF-instellingen

| Sleutel | Standaard | Beschrijving |
| --- | --- | --- |
| `DFTC_MIN_DOC_FREQ` | 2 | Term genegeerd als die in minder dan N producten voorkomt |
| `DFTC_MAX_DOC_FREQ_RATIO` | 0.50 | Term genegeerd als die in meer dan X % van de catalogus voorkomt |
| `DFTC_NGRAM_MAX` | 2 | 1 = unigrammen, 2 = unigrammen + bigrammen |
| `DFTC_TOP_TERMS_COUNT` | 8 | Aantal getoonde termen per cluster |

### Embeddings-API's

| Sleutel | Beschrijving |
| --- | --- |
| `DFTC_OPENAI_API_KEY` | Bearer token van OpenAI (sk-...) |
| `DFTC_OPENAI_MODEL` | Model (standaard `text-embedding-3-small`) |
| `DFTC_MISTRAL_API_KEY` | API-sleutel van Mistral |
| `DFTC_MISTRAL_MODEL` | Model (standaard `mistral-embed`) |
| `DFTC_BATCH_SIZE` | Aantal producten per API-aanroep (standaard 32) |

### Detectie van pillar pages

- `DFTC_PILLAR_MATCH_THRESHOLD`: matchdrempel (standaard 0.45). Daaronder wordt het cluster als _pillar gap_ gemarkeerd. Verhoog de drempel om strenger te zijn, verlaag die om toleranter te zijn.

## De drie modi in detail

### TF-IDF-modus (aanbevolen om te beginnen)

TF-IDF (Term Frequency × Inverse Document Frequency) is een klassieke statistische methode in NLP. De module bouwt een woordenschat op uit alle productteksten, filtert de te zeldzame of te frequente termen eruit en stelt elk product daarna voor als een ijle vector in die ruimte.

**Voordelen:** 100 % lokaal, meteen klaar, geen kosten, geen externe afhankelijkheid. Uitstekend voor catalogi met een lexicaal homogene inhoud (één domein, één samenhangende woordenschat).

**Beperkingen:** begrijpt geen synoniemen (twee producten die andere woorden voor hetzelfde begrip gebruiken, worden slecht gegroepeerd).

### OpenAI-embeddingsmodus

Gebruikt standaard de OpenAI-API `text-embedding-3-small`. Elk product wordt voorgesteld door een dichte vector van 1536 dimensies die de semantiek ervan vastlegt.

**Voordelen:** begrijpt synoniemen, lexicale varianten en context. Uitstekend voor gevarieerde catalogi of verhalende beschrijvingen.

**Indicatieve kosten:** ongeveer 0,02 USD per miljoen tokens, oftewel minder dan 0,10 USD voor een catalogus van 1 000 producten.

**Tip.** De embeddingscache werkt automatisch: start u een run opnieuw op dezelfde catalogus zonder de teksten te wijzigen, dan worden de vectoren uit de tabel `df_topicclusters_embedding_cache` gehaald zonder nieuwe API-aanroep.

### Mistral-embeddingsmodus

Gebruikt standaard de Mistral-API `mistral-embed`. Een sterk meertalig model, bijzonder goed in het Frans.

**Voordelen:** in Europa gehost (wat AVG-conformiteit vergemakkelijkt), uitstekend op Franstalige inhoud, scherp tarief.

## Een analyse starten

Vanaf het dashboard biedt het formulier **Een nieuwe analyse starten** zes parameters:

- **Taal**: de taal waarin de productteksten worden opgehaald en geanalyseerd. Start een aparte run voor elke actieve taal van uw winkel.
- **Modus**: TF-IDF, OpenAI of Mistral (overschrijft de standaardinstelling, alleen voor deze run).
- **Aantal clusters (k)**: laat 0 staan voor auto-k. Forceer anders een waarde tussen 2 en 100.
- **Minimale omvang**: kleinere clusters worden verworpen (standaard 3).
- **Pillardrempel**: de matchdrempel waaronder een cluster als leemte wordt gemarkeerd (standaard 0.45).
- **Productlimiet**: beperkt het aantal geanalyseerde producten (nuttig om te debuggen of snel te testen). Laat 0 staan om de hele catalogus te analyseren.

Klik op **De analyse starten**. De run begint onmiddellijk. Voor een catalogus van 1 000 producten:

- TF-IDF-modus: 5 tot 15 seconden
- Embeddingsmodus (eerste run): 30 seconden tot 2 minuten, afhankelijk van de batchgrootte
- Embeddingsmodus (volgende runs met warme cache): vergelijkbaar met TF-IDF

**Belangrijk.** De module zet voor de duur van de run `set_time_limit(0)` en `memory_limit=1024M`. Op sterk beperkte hostingpakketten kunnen deze directieven worden genegeerd. Kies dan voor een nachtelijke run of gebruik de productlimiet om het werk op te delen.

## De resultaten lezen

Zodra de run klaar is, komt u op de detailpagina. Elk cluster wordt als een kaart met vier secties getoond.

### Kop van het cluster

De kop combineert een statusbadge, een clusternummer en een gegenereerd label. De badge is:

- **PILLAR GAP** (oranje): geen enkele bestaande pillar page dekt dit onderwerp. Sterke kans.
- **OK** (groen): een CMS-pagina of categorie dekt dit onderwerp al (de module heeft die gematcht).

Het label bestaat uit de 3 topternen van het cluster, verbonden door `·`. Bijvoorbeeld: "sneakers · premium leer · schoenen".

### Statistieken

- **Producten**: aantal producten in het cluster
- **Cohesie**: gemiddelde gelijkenis van de leden met het zwaartepunt (0 tot 100 %). Hoe hoger, hoe homogener het cluster.
- **Match**: matchscore met de best passende bestaande pillar page. Onder de drempel wordt het een leemte.

### Toptermen

De meest representatieve termen van het cluster. In de TF-IDF-modus zijn dat de termen met de sterkste component in het zwaartepunt. In de embeddingsmodus berekent de module een TF binnen het cluster, gewogen met de globale IDF, om de onderscheidende termen naar boven te halen.

### Voorstel voor een pillar page

Alleen aanwezig als het cluster als leemte is gemarkeerd. Bevat:

- **Titel**: SEO-geoptimaliseerde H1-titel in natuurlijke taal
- **Slug**: URL-veilig, in kebab-case
- **Metabeschrijving**: 150 tot 160 tekens
- **Prioriteit**: gecombineerde score van omvang (0.6) × cohesie (0.4)
- **Voorgesteld plan**: H2-plan in markdown met klassieke secties (inleiding, wat is het, hoe kiezen, vergelijking, beste producten, gebruikssituaties, valkuilen, FAQ, call to action)

### Producten van het cluster

Lijst van de gegroepeerde producten met hun gelijkenisscore ten opzichte van het zwaartepunt, gerangschikt van hoog naar laag. Klik op de product-ID om de fiche meteen in een nieuw venster te openen.

## Aanbevolen werkwijze

Een typisch gebruik van de module in 4 stappen.

1. **Eerste audit**: start een TF-IDF-run op uw hoofdtaal, met de standaardinstellingen. Bekijk de clusters die als leemte zijn gemarkeerd: zijn ze redactioneel relevant?
2. **Selectie**: gebruik voor elke leemte de knop **Negeren** als het cluster geen pillar page verdient (bijvoorbeeld een toevallige groepering van uiteenlopende producten). De overblijvende leemtes zijn uw prioriteiten.
3. **Redactie**: maak voor elke weerhouden leemte een nieuwe CMS-pagina in PrestaShop met de titel, slug en meta uit het concept. Gebruik het H2-plan als geraamte. Klik na publicatie op **Markeren als gedaan**.
4. **Nieuwe run**: start na publicatie van de nieuwe pagina's opnieuw een run. De oude leemtes horen nu OK te zijn (de module herkent de nieuwe pillar pages).

**Goede SEO-praktijken.** Een degelijke pillar page telt minstens 1 500 woorden, bevat interne links naar de producten van het cluster en gebruikt de toptermen op een natuurlijke manier in de tekst. Het gegenereerde concept is een vertrekpunt, geen eindproduct.

## Export

Op de detailpagina van een run staan rechtsboven twee exportknoppen:

- **CSV**: tabel met één regel per cluster, met de kolommen id_cluster, label, n_members, cohesie, pillar_gap, match_score, suggested_title, suggested_slug, suggested_meta, priority_score en target_keywords. Codering UTF-8 met BOM (geschikt voor Excel).
- **JSON**: volledige export met de lijst van producten per cluster en het integrale markdownplan. Ideaal voor automatisering of externe integratie.

## Technische architectuur

### Database

De module maakt 5 tabellen aan met het voorvoegsel `df_topicclusters_`:

- `run`: metadata van elke uitvoering (modus, taal, status, duur, tellers)
- `cluster`: de afzonderlijke clusters (label, toptermen als JSON, cohesie, vlag pillar_gap, match_score)
- `cluster_product`: koppeling product → cluster met de gelijkenisscore
- `pillar`: voorstellen voor pillar pages (titel, slug, meta, plan, prioriteit, status)
- `embedding_cache`: cache van de embeddingvectoren, geïndexeerd op de hash van de tekst

### PSR-4 en autoload

De hoofdnamespace is `DataFirefly/TopicClusters/`. Een handmatige autoload wordt via `spl_autoload_register` in het hoofdbestand van de module geregistreerd, zodat er geen Composer-afhankelijkheid nodig is.

### Controllers en compatibiliteit met PS 8 en PS 9

De module gebruikt een legacy `ModuleAdminController` (en geen Symfony-controller) om de compatibiliteit met beide hoofdversies te garanderen. De SQL-queries zijn geschreven om de schema's van beide versies te respecteren, met name het verdwijnen van de kolom `meta_keywords` in PS 9.

## Prestaties en grenzen

- **Catalogi tot 1 000 producten**: runs van enkele seconden. Geen bijzondere zorgen.
- **1 000 tot 10 000 producten**: de TF-IDF-modus blijft snel (10 tot 60 s). Embeddingsmodus: reken op 1 tot 5 minuten voor de eerste run, daarna vrijwel meteen dankzij de cache.
- **Meer dan 10 000 producten**: gebruik bij voorkeur de parameter **Productlimiet** om op te delen, of verhoog `memory_limit` naar 2 GB.

De complexiteit van de k-means is O(n × k × iter × d), waarbij n het aantal producten is, k het aantal clusters, iter het aantal iteraties (doorgaans 10 tot 30) en d de dimensie van de vectoren (variabel bij TF-IDF, 1536 bij OpenAI).

## Problemen oplossen

### Geen enkel cluster gevonden

Controleer of uw producten wel tekstuele inhoud in de geanalyseerde taal hebben (minstens een naam en idealiter een beschrijving). Is `DFTC_MIN_DOC_FREQ` te hoog voor uw catalogus, zet die dan op 1.

### Alle clusters worden als pillar gap gemarkeerd

De drempel `DFTC_PILLAR_MATCH_THRESHOLD` staat waarschijnlijk te hoog. Probeer 0.30 in plaats van 0.45 als uw winkel weinig CMS-pagina's heeft. Controleer ook of uw CMS-pagina's en categorieën wel actief zijn.

### Fout "Unknown column meta_keywords"

Deze fout treedt op bij PrestaShop 9 met een oudere versie van de module. Werk bij naar versie 1.0.0 of hoger, die elke verwijzing naar `meta_keywords` weglaat (die kolom is in PS 9 verdwenen).

### Fout "Compile Error: Access level to processExport() must be public"

Deze fout kwam voor in een versie van vóór 1.0.0. De methode heet voortaan `doExport()` om de botsing met `AdminControllerCore` te vermijden. Werk de module bij.

### De run mislukt met een API-fout

Controleer of de API-sleutel in de configuratie geldig is en over krediet beschikt. Test met `curl` in de CLI of de server `api.openai.com` of `api.mistral.ai` kan bereiken.

## Wat er nog aankomt

- CMS-pagina's rechtstreeks vanuit het concept aanmaken (met één klik)
- Runs vergelijken (voor en na publicatie van pillar pages)
- Grafische weergave van het semantische netwerk tussen clusters
- Ondersteuning voor de embeddings van Cohere en Voyage AI
- Automatische cron voor periodieke runs

**Ondersteuning.** Voor vragen of bugs kunt u terecht bij [support@datafirefly.com](mailto:support@datafirefly.com). Uw feedback helpt ons de roadmap te sturen.