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

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

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

Embeddings-API’s

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.

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

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

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