Semantische audit — Documentatie

Installatie

Vereisten

• PrestaShop 8.0 tot 9.x
• Minimaal PHP 7.4 (8.x aanbevolen)
• MySQL 5.7+ of MariaDB 10.3+
• Een OpenAI- of Mistral API-sleutel (optioneel: een lokale modus zonder API is inbegrepen)

De module installeren

1. Pak het bestand dfsemanticaudit.zip uit dat u via uw klantaccount hebt gedownload.
2. Upload de map dfsemanticaudit/ naar /modules/ van uw PrestaShop via FTP, of gebruik de ZIP-installatie via Modules → Modulebeheer → Een module uploaden.
3. Klik op Installeren.

De module activeren

De module maakt automatisch vier SQL-tabellen aan (ps_dfsa_content, ps_dfsa_audit, ps_dfsa_cluster, ps_dfsa_assignment) en een beheertabblad bereikbaar via het linkermenu.

Configuratie

Ga vóór de eerste audit naar Modules → DataFirefly → Semantische audit → Configuratie.

Keuze van de embeddingprovider

Drie providers zijn beschikbaar. De keuze bepaalt de kwaliteit van de verkregen clusters.

OpenAI (aanbevolen)

De standaardprovider. Gebruikt het model text-embedding-3-small (1536 dimensies). Maximale kwaliteit, marginale kosten: ongeveer 0,02 € voor 1000 producten bij de eerste indexering.

• API-sleutel: aan te maken via platform.openai.com/api-keys
• Model: laat standaard text-embedding-3-small staan. text-embedding-3-large (3072 dim) geeft een iets hogere kwaliteit maar kost 6× meer.

Mistral

Europees alternatief, gehost in Frankrijk. Gebruikt mistral-embed (1024 dimensies). Vergelijkbare prijsstelling als OpenAI.

• API-sleutel: aan te maken via console.mistral.ai
• Model: mistral-embed

Lokale TF-IDF

Werkt volledig op uw server, zonder API-aanroepen, zonder terugkerende kosten. Gebruikt de klassieke principes van statistische taalverwerking (genormaliseerde TF-IDF) met een dimensie van 384.

• Voldoende kwaliteit voor catalogi met minder dan 500 producten.
• Ondersteunt FR, EN, ES, DE, IT (ingebouwde stopwoorden).
• Geen API-sleutel nodig.

Auditparameters

• k (aantal clusters): standaard 8. Bereik 2–50.
• Off-topicdrempel: cosinusafstand vanaf welke een inhoud wordt gemarkeerd. Standaard 0,55. Bereik 0,1 tot 1,5.

Auto-reindex

Standaard ingeschakeld. De module registreert hooks op het aanmaken, wijzigen en verwijderen van producten, categorieën en CMS-pagina’s. Bij elke wijziging wordt de inhoud gemarkeerd voor re-embedding bij de volgende run, zonder handmatige inspanning.

Uw eerste audit starten

Drie stappen, in volgorde uit te voeren vanaf het dashboard.

Stap 1 — Inhoud herindexeren

Klik op Inhoud herindexeren. De module doorloopt uw producten, actieve categorieën, CMS-pagina’s en fabrikanten, berekent een SHA1-hash van de titel + het uittreksel, en markeert alleen nieuwe of gewijzigde inhouden voor verwerking.

Voor 1000 inhouden duurt deze stap enkele seconden.

Stap 2 — Embeddings genereren

Klik op Embeddings genereren. De module stuurt de als “dirty” gemarkeerde inhouden naar de geselecteerde provider in batches van 50 (OpenAI/Mistral) of in één lokale pass (TF-IDF). Een voortgangsbalk volgt de voortgang.

Voor 1000 inhouden:

• OpenAI: ~30 seconden
• Mistral: ~40 seconden
• Lokale TF-IDF: <1 seconde

Stap 3 — De audit starten

Klik op Audit starten. De cosinus k-means-clustering groepeert de inhouden in k clusters (k-means++-initialisatie, maximaal 50 iteraties), labelt elke cluster met zijn topbegrippen (TF×IDF), berekent de afstand van elke inhoud tot zijn centroïde en identificeert de outliers.

Deze stap duurt minder dan een seconde, zelfs voor 5000 inhouden.

Het rapport begrijpen

Dashboard

Vier belangrijke KPI’s bovenaan:

• Geïndexeerde inhouden: totaal van ge-embedde producten, categorieën, CMS-pagina’s en fabrikanten.
• Off-topicpagina’s: absoluut aantal, percentage en verdeling per type.
• Thematische clusters: aantal geïdentificeerde thematische groepen.
• Mediaanafstand: mediane cosinusafstand tot de centroïde. Onder 0,40 = zeer coherente catalogus. Boven 0,60 = verspreide catalogus.

Clusters

Weergave Clusters: gedetailleerde lijst gesorteerd op grootte, met automatisch label (top 5 TF×IDF-begrippen), cohesiescore (0 = verspreid, 1 = identiek) en grootte (aantal inhouden).

Een cluster met een cohesie < 0,40 is te heterogeen: vaak een teken dat het onderwerp in twee subthema’s moet worden gesplitst, of dat k te laag is.

2D semantische kaart

Projectie van alle inhouden op een vlak via de techniek Johnson-Lindenstrauss (een willekeurige projectie die de afstanden bij benadering behoudt).

Elk punt is een inhoud, elke kleur een cluster. De kruisjes markeren de centroïden. De punten met een rode rand zijn de off-topics. Met de legenda rechts kunt u elke cluster afzonderlijk verbergen/tonen door erop te klikken.

Off-topicpagina’s

Weergave Off-topicpagina’s: sorteerbare tabel van inhouden waarvan de cosinusafstand tot de centroïde de geconfigureerde drempel overschrijdt. Voor elke regel:

• Type, titel, publieke URL en directe link naar het bewerkingsformulier
• Huidige cluster (met kleur)
• Afstand tot de centroïde (hoe hoger, hoe verder de inhoud afstaat)
• Voorgestelde cluster (indien relevant)
• Δ Winst: afstandsvermindering als de inhoud zou worden verplaatst

Onherstelbare pagina’s

Onderaan de off-topicweergave toont een speciale sectie de inhouden die van alle clusters ver verwijderd zijn. De module heeft voor hen geen haalbare bestemming gevonden.

Drie acties om te overwegen:

1. Verwijderen als de pagina geen SEO-verkeer en geen conversie heeft.
2. Noindex om het crawlbudget te sparen zonder de historiek te verliezen.
3. Herschrijven om de inhoud uit te lijnen met een bestaande cluster.

Herstructureringssuggesties

Weergave Suggesties: gelijkwaardig aan Off-topicpagina’s maar gericht op actie. Alle voorgestelde verplaatsingen worden getoond met de verwachte coherentiewinst. Sorteer op aflopende winst om de meest impactvolle gevallen eerst te behandelen.

De module wijzigt uw boomstructuur nooit automatisch. De wijzigingen blijven onder uw controle via de standaard PrestaShop-backoffice.

CSV-export

Vanuit elke rapportweergave laat een knop CSV exporteren u de ruwe gegevens downloaden. Handig om:

• Het rapport te delen met een externe SEO-consultant
• De gegevens te verwerken in Excel/Sheets
• De staat van een audit te archiveren voordat u de boomstructuur wijzigt

Automatisering via cron

De module stelt een ondertekende URL beschikbaar die op de configuratiepagina wordt getoond. Ze triggert headless de volledige keten indexering → embeddings → audit.

Voorbeeld van een wekelijkse crontaak (elke maandag om 3 uur):

0 3 * * 1 wget -q -O /dev/null "https://uw-winkel.com/modules/dfsemanticaudit/cron.php?token=UW_TOKEN"

Het token wordt afgeleid van de _COOKIE_KEY_ van uw PrestaShop en wijzigt alleen bij een herinstallatie. Bewaar het zorgvuldig.

API-kosten

Schatting voor een gemiddelde catalogus (1000 producten):

• OpenAI text-embedding-3-small: ~0,02 € de eerste keer, daarna vrijwel nul (alleen gewijzigde inhouden worden opnieuw verwerkt)
• OpenAI text-embedding-3-large: ~0,13 € de eerste keer
• Mistral mistral-embed: ~0,10 € de eerste keer
• Lokale TF-IDF: 0 €

Meertalig en multistore

De module is native meertalig en multistore. Elke audit draait op een gegeven combinatie taal × winkel, met de contexttaal van de backoffice.

Om uw winkel eerst in het Frans en dan in het Engels te auditen, wisselt u van taal in de bovenbalk van PrestaShop en start u een nieuwe audit.

Probleemoplossing

De stap “Embeddings genereren” faalt met een 401-fout

Uw API-sleutel is ongeldig of verlopen. Controleer haar op de configuratiepagina en configureer haar indien nodig opnieuw.

De stap “Embeddings genereren” faalt met een 429-fout

U hebt de rate limit van uw provider bereikt. Wacht enkele minuten en start opnieuw: de module gaat dankzij de batchverwerking verder waar ze was gestopt.

Geen enkele cluster lijkt relevant

Drie sporen:

1. Verhoog het aantal clusters (k). Als uw catalogus 10 verschillende thema’s heeft maar k=4, kan de clustering ze niet scheiden.
2. Stap over van de lokale TF-IDF-modus naar OpenAI of Mistral. Op heterogene catalogi maakt de semantische kwaliteit het hele verschil.
3. Controleer of de titels en beschrijvingen van uw inhouden voldoende rijk zijn. Een product met een titel van 2 woorden en geen beschrijving levert geen goede embedding op.

Te veel pagina’s gemarkeerd als off-topic

Verhoog de off-topicdrempel (bijvoorbeeld van 0,55 naar 0,70). Dat is te verwachten als uw catalogus legitiem meerdere brede thema’s bestrijkt.

Geen enkele pagina gemarkeerd als off-topic maar de catalogus lijkt incoherent

Verlaag de drempel (bijvoorbeeld van 0,55 naar 0,40) om de detectie aan te scherpen.

FAQ

Is een API-sleutel verplicht?

Nee. De lokale TF-IDF-modus werkt zonder externe verbinding. Hij is iets minder nauwkeurig dan OpenAI/Mistral maar volstaat om te starten of voor een homogene catalogus.

Wijzigt de module automatisch mijn boomstructuur?

Nee. De module doet uitsluitend aanbevelingen. Alle inhoudsverplaatsingen blijven uw verantwoordelijkheid via de standaard PrestaShop-backoffice.

Hoe kies ik het aantal clusters (k)?

Vuistregel: k ≈ aantal hoofdcategorieën van het eerste niveau. Standaard werkt k=8 goed tussen 100 en 5000 producten. Voer bij twijfel 2 of 3 audits uit met verschillende k-waarden om te vergelijken: eerdere audits blijven in de historiek.

Worden mijn vectoren naar een server van derden verstuurd?

Met OpenAI of Mistral: ja, de titels en uittreksels van uw inhouden worden naar hun embedding-API verstuurd. Met de lokale TF-IDF-modus: nee, geen enkel gegeven verlaat uw server.

Hoelang worden de audits bewaard?

Onbeperkt, tot handmatige verwijdering vanaf het dashboard. U kunt de volledige historiek raadplegen om de evolutie van uw semantische coherentie in de tijd te meten.

Werkt de module in multistore?

Ja. Elke winkel van de multistore kan haar eigen onafhankelijke audits hebben.