Semantische Interne Links met AI: volledige gids

Overzicht

DataFirefly Semantische Interne Links met AI (dfaisemanticlinks) bouwt de interne linkstructuur van uw PrestaShop-winkel op uit vectorembeddings. Elk product, elke categorie en elke CMS-pagina wordt door een AI-aanbieder (Mistral of OpenAI) in een vector omgezet, de vectoren worden met cosinusgelijkenis vergeleken, en de module stelt contextuele links voor met ankerteksten die letterlijk uit de brontekst komen. U keurt de voorstellen een voor een of in bulk goed, en elke ingevoegde link kan chirurgisch worden weggehaald dankzij een unieke markering data-dfasl.

Vereisten

• PrestaShop 8.0 tot 9.x (PrestaShop 1.7 wordt niet ondersteund)
• PHP 8.1, 8.2 of 8.3
• MySQL 5.7+ of MariaDB 10.3+
• Een API-sleutel van Mistral (console.mistral.ai) of OpenAI (platform.openai.com)
• CLI-toegang is aan te raden bij catalogi van meer dan 1000 entiteiten (via cron)

Installatie

1. Backoffice → Modules → Modulebeheer → Een module installeren.
2. Upload dfaisemanticlinks.zip en klik op Installeren.
3. De module maakt 5 tabellen aan met het voorvoegsel dfasl_ (embedding, queue, suggestion, inserted_link en job) en een menu AI-linkstructuur met 4 tabbladen: Dashboard, Voorstellen, Ingevoegde links en Instellingen.

Configuratie

1. Aanbieder van de embeddings

Tabblad Instellingen, eerste blok:

• Aanbieder: Mistral (mistral-embed, 1024 dimensies, de standaard, met hosting in de EU) of OpenAI (text-embedding-3-small, 1536 dimensies).
• API-sleutel: plak de sleutel van de gekozen aanbieder.
• De verbinding testen: die knop stuurt een testreeks door en toont hoeveel dimensies er terugkomen. Valideer uw sleutel hier altijd vóór u een indexering start.

2. Indexering

• Geïndexeerde types: producten, categorieën en CMS-pagina’s, elk apart in te schakelen.
• Minimale lengte (standaard 200 tekens): inhoud die na het opschonen van de HTML te kort is, wordt overgeslagen.
• Batchgrootte (standaard 20): het aantal items dat per API-verzoek vertrekt. Eén embeddingaanroep per batch.
• Automatisch opnieuw indexeren (standaard aan): elke wijziging aan een product, categorie of CMS-pagina zet de entiteit via hooks terug in de wachtrij. Zet dat tijdelijk uit tijdens een massale CSV-import.

3. Voorstellen en invoegen

• Gelijkenisdrempel (standaard 0,78): paren onder de drempel worden overgeslagen. Ga naar 0,72 voor meer voorstellen, of naar 0,82 voor meer striktheid.
• Maximaal aantal links per pagina (standaard 5): een bescherming tegen SEO-overoptimalisatie.
• Ankerstrategie: geoptimaliseerde n-grammen (de standaard) of de ruwe titel van het doel.

De eerste indexering

1. Tabblad Dashboard → de knop Alles opnieuw indexeren: alle actieve entiteiten van de ingeschakelde types komen in de wachtrij, in alle actieve talen.
2. Klik zo vaak als nodig op Een batch verwerken (bij kleine catalogi), of start de CLI-worker (zie verderop).
3. Elke batch: het extraheren en opschonen van de tekst, de embeddingaanroep in batch, het bewaren van de vector, en daarna het berekenen van de voorstellen met cosinusgelijkenis.

Het dashboard toont doorlopend: het totale aantal entiteiten, de actieve embeddings, de wachtende voorstellen, de actieve links en de statussen van de wachtrij (In afwachting, Bezig, Klaar en Fout).

De voorstellen goedkeuren

Tabblad Voorstellen: een gepagineerde tabel met per regel de bron, het doel, de gelijkenisscore, het voorgestelde anker, een fragment met de context, en de knoppen Invoegen en Weigeren.

Het anker kiezen

De ankergenerator haalt de n-grammen (2 tot 6 woorden) uit de doeltitel die letterlijk in de brontekst voorkomen, gerangschikt van het langste naar het kortste. De keuzelijst toont alle kandidaten; met de optie Aanpassen opent een vrij veld. Het standaardanker is het langste gevonden n-gram, doorgaans 3 of 4 woorden met de belangrijkste zoekwoorden van het doel.

Invoegen

Bij het invoegen linkt de module het eerste voorkomen van het anker dat niet al in een a-, code– of pre-tag zit (met de PCRE-patronen SKIP en FAIL). Is er geen vrij voorkomen, dan komt er onder aan de beschrijving een terugvalparagraaf met de klasse dfasl-related. Elke link krijgt een attribuut data-dfasl met een unieke identificatie van 36 tekens.

Bulkacties

Vink meerdere regels aan (met het vakje in de kolomkop selecteert u alles) en klik daarna op De selectie invoegen of De selectie weigeren. De paginering toont 50 regels.

Een link weghalen (rollback)

Tabblad Ingevoegde links: een gepagineerde lijst met de actieve links, met de bron, het doel, het anker, de datum en de medewerker. De knop Weghalen wist alleen de a data-dfasl-tag met die identificatie: de ankertekst blijft intact, geen enkel ander HTML-element wordt geraakt, en de link wordt in de database als weggehaald gemarkeerd.

CLI-worker en cron

Gebruik bij grote catalogi de worker op de opdrachtregel:

php modules/dfaisemanticlinks/bin/analyze.php [opties]

• --shop=N: richt zich op één bepaalde winkel (multistore).
• --enqueue-all: zet alle actieve entiteiten opnieuw in de wachtrij vóór het verwerken.
• --loop: blijft lopen zolang er items wachten.
• --max-batches=N: begrenst het aantal batches per run (een beveiliging tegen ontsporen).
• --sleep=N: een pauze in seconden tussen de batches (voor de rate limits van de API).

Een aanbevolen cron om het kwartier:

*/15 * * * * php /pad/naar/prestashop/modules/dfaisemanticlinks/bin/analyze.php --loop --max-batches=50 --sleep=1

Automatisch opnieuw indexeren

De hooks actionObjectProductUpdateAfter, actionObjectCategoryUpdateAfter en actionObjectCmsUpdateAfter zetten de gewijzigde entiteit in alle actieve talen terug in de wachtrij. De verwijderhooks wissen de embeddings en de voorstellen in cascade. De SHA-256-inhoudshash voorkomt elke API-aanroep als de werkelijke tekst niet is veranderd (bijvoorbeeld bij een eenvoudige voorraadwijziging).

Multistore en meertaligheid

De embeddings worden per drietal (entiteit, taal, winkel) afgebakend. De voorstellen overschrijden nooit de taal- of winkelgrenzen. De configuratie (API-sleutel, drempel, geïndexeerde types) kan per winkel verschillen, via de gewone multistore-contextkiezer van PrestaShop.

Problemen oplossen

« API-sleutel niet ingesteld » of een fout bij de verbindingstest

Controleer of de sleutel wel bij de aanbieder in de keuzelijst hoort (een Mistral-sleutel werkt niet met de OpenAI-provider en omgekeerd) en of er nog krediet is. De gedetailleerde API-fouten komen via PrestaShopLogger in Geavanceerde parameters → Logboeken terecht.

Er blijven items op de status « Bezig » staan

Waarschijnlijk is een worker onderbroken. Wacht 30 minuten (dan volgt de automatische reset) of klik op De wachtrij legen en start daarna Alles opnieuw indexeren.

Weinig of geen voorstellen

Er zijn drie veelvoorkomende oorzaken: een te hoge gelijkenisdrempel (probeer 0,72), te korte inhoud (onder de minimale lengte), of een catalogus die te homogeen of te heterogeen is. Controleer ook of de gewenste soorten entiteiten in de Instellingen aanstaan.

Het voorgestelde anker is de ruwe titel van het doel

Dat is de terugvalmodus: geen enkel n-gram uit de doeltitel komt letterlijk in de brontekst voor. Kies een eigen anker of verrijk de bronbeschrijving.

Technische architectuur

• PHP 8.1+ met strikte types, PSR-4 onder de namespace DataFirefly/AiSemanticLinks/ die naar src/ wijst
• Legacy beheercontrollers ModuleAdminController (voor stabiele compatibiliteit met PS8 en PS9)
• Een eigen minicontainer voor de services (los van de Symfony-container)
• Vectoren als BLOB met float32 in little-endian, plus een vooraf berekende L2-norm
• 5 tabellen: dfasl_embedding, dfasl_queue, dfasl_suggestion, dfasl_inserted_link en dfasl_job
• Onversleutelde broncode, klaar om te overschrijven