PS PrestaShop PrestaShop Mittel

Semantisches KI-Internlinking — Vollständiger Leitfaden

Semantisches internes Linking mit KI-Embeddings installieren, konfigurieren und betreiben: Indexierung, Vorschläge, Anker, Rollback und CLI-Worker.

Aktualisiert Modulversion 1.0.0

Überblick

DataFirefly Semantisches KI-Internlinking (dfaisemanticlinks) baut das interne Linking Ihres PrestaShop-Shops auf Basis von Vektor-Embeddings auf. Jedes Produkt, jede Kategorie und jede CMS-Seite wird von einem KI-Anbieter (Mistral oder OpenAI) in einen Vektor verwandelt, die Vektoren werden über Kosinus-Ähnlichkeit verglichen, und das Modul schlägt kontextuelle Links mit wörtlich aus dem Quelltext extrahierten Ankern vor. Sie validieren Vorschläge einzeln oder in Bulk, und jeder eingefügte Link kann dank einer eindeutigen data-dfasl-Markierung chirurgisch entfernt werden.

Das Modul macht keinen KI-Aufruf im Front-Office: Ähnlichkeiten sind vorberechnet und validierte Links werden direkt in die Beschreibungen geschrieben. Performance-Auswirkung: null.

Voraussetzungen

  • PrestaShop 8.0 → 9.x (PrestaShop 1.7 nicht unterstützt)
  • PHP 8.1, 8.2 oder 8.3
  • MySQL 5.7+ / MariaDB 10.3+
  • Ein Mistral-API-Schlüssel (console.mistral.ai) oder OpenAI-API-Schlüssel (platform.openai.com)
  • CLI-Zugang empfohlen für Kataloge mit über 1.000 Entitäten (Cron)

Installation

  1. Back-Office → Module → Modul-Manager → Modul hochladen.
  2. Laden Sie dfaisemanticlinks.zip hoch und klicken Sie auf Installieren.
  3. Das Modul erstellt 5 Tabellen mit dem Präfix dfasl_ (embedding, queue, suggestion, inserted_link, job) und ein Menü KI-Linking mit 4 Tabs: Dashboard, Vorschläge, Eingefügte Links, Einstellungen.

Die Deinstallation löscht die 5 Tabellen und alle DFASL_*-Konfigurationsvariablen sauber. Exportieren Sie Ihre Daten vorher, wenn Sie sie behalten möchten.

Konfiguration

1. Embedding-Anbieter

Tab Einstellungen, erster Block:

  • Anbieter: Mistral (mistral-embed, 1024 Dimensionen, Standard, EU-Hosting) oder OpenAI (text-embedding-3-small, 1536 Dimensionen).
  • API-Schlüssel: fügen Sie den Schlüssel des ausgewählten Anbieters ein.
  • API-Verbindung testen: der Button sendet einen Teststring und zeigt die empfangenen Dimensionen an. Validieren Sie den Schlüssel immer hier, bevor Sie eine Indexierung starten.

Wenn Sie nach einer Indexierung den Anbieter wechseln, ändern sich die Vektordimensionen (1024 vs. 1536). Das Modul fordert ein Alles reindexieren an — alte Vektoren werden überschrieben, aber bereits eingefügte Links bleiben bestehen.

2. Indexierung

  • Indizierte Typen: Produkte, Kategorien, CMS-Seiten — jeder unabhängig aktivierbar.
  • Mindestlänge (Standard 200 Zeichen): Inhalte, die nach der HTML-Bereinigung zu kurz sind, werden übersprungen.
  • Batch-Größe (Standard 20): Anzahl der pro API-Anfrage gesendeten Items. Ein Embedding-Aufruf pro Batch.
  • Auto-Reindexierung (standardmäßig an): jede Produkt-/Kategorie-/CMS-Änderung stellt die Entität via Hooks wieder in die Warteschlange. Deaktivieren Sie sie vorübergehend während eines großen CSV-Imports.

3. Vorschläge und Einfügen

  • Ähnlichkeitsschwellenwert (Standard 0,78): Paare unter dem Schwellenwert werden ignoriert. Auf 0,72 senken für mehr Vorschläge, auf 0,82 erhöhen für mehr Strenge.
  • Max. Links pro Seite (Standard 5): SEO-Anti-Überoptimierungsschutz.
  • Anker-Strategie: optimierte N-Gramme (Standard) oder roher Zieltitel.

Erste Indexierung

  1. Tab Dashboard → Button Alles reindexieren: alle aktiven Entitäten der aktivierten Typen werden in allen aktiven Sprachen in die Warteschlange gestellt.
  2. Klicken Sie so oft wie nötig auf Batch verarbeiten (kleine Kataloge) oder starten Sie den CLI-Worker (siehe unten).
  3. Jeder Batch: Textextraktion + Bereinigung, Batch-Embedding-Aufruf, Vektorspeicherung, dann Vorschlagsberechnung über Kosinus-Ähnlichkeit.

Das Dashboard zeigt fortlaufend: gesamte Entitäten, aktive Embeddings, ausstehende Vorschläge, aktive Links und die Warteschlangenstatus (Ausstehend, In Bearbeitung, Erledigt, Fehler).

Kostenindikation: 1.000 Produkte in 3 Sprachen ≈ 1,5 Millionen Tokens ≈ 0,15 EUR (Mistral) oder 0,03 USD (OpenAI). Die SHA-256-Hash-Erkennung sorgt dafür, dass nachfolgende Reindexierungen nur für tatsächlich geänderten Inhalt bezahlen.

Vorschläge validieren

Tab Vorschläge: paginierte Tabelle mit, pro Zeile, Quelle, Ziel, Ähnlichkeitsscore, vorgeschlagenem Anker, einem Kontext-Snippet und den Buttons Einfügen / Ablehnen.

Anker auswählen

Der Anker-Generator extrahiert N-Gramme (2 bis 6 Wörter) aus dem Zieltitel, die wörtlich im Quellkörper vorkommen, sortiert vom längsten zum kürzesten. Das Dropdown listet alle Kandidaten; die Option Benutzerdefiniert öffnet ein freies Feld. Der Standard-Anker ist das längste gefundene N-Gramm — normalerweise 3 oder 4 Wörter mit den Hauptkeywords des Ziels.

Einfügen

Beim Einfügen verlinkt das Modul das erste Vorkommen des Ankers, das nicht bereits in einem a-, code– oder pre-Tag steht (SKIP/FAIL-PCRE-Muster). Wenn kein freies Vorkommen existiert, wird ein Fallback-Absatz mit der Klasse dfasl-related am Ende der Beschreibung angehängt. Jeder Link erhält ein data-dfasl-Attribut mit einem eindeutigen 36-Zeichen-Identifikator.

Bulk-Aktionen

Mehrere Zeilen ankreuzen (Kopfzeilen-Checkbox zum Auswählen aller) und dann Auswahl einfügen oder Auswahl ablehnen. Paginierung mit 50 Zeilen.

Einen Link entfernen (Rollback)

Tab Eingefügte Links: paginierte Liste der aktiven Links mit Quelle, Ziel, Anker, Datum, Mitarbeiter. Der Button Entfernen löscht nur das a data-dfasl-Tag mit diesem Identifikator — der Ankertext bleibt intakt, kein anderes HTML-Element wird berührt, und der Link wird in der Datenbank als entfernt markiert.

CLI-Worker und Cron

Für große Kataloge verwenden Sie den Befehlszeilen-Worker:

php modules/dfaisemanticlinks/bin/analyze.php [Optionen]
  • --shop=N: einen bestimmten Shop anvisieren (Multishop).
  • --enqueue-all: alle aktiven Entitäten vor dem Verarbeiten erneut einreihen.
  • --loop: schleifen, solange ausstehende Items vorhanden sind.
  • --max-batches=N: die Batch-Anzahl pro Lauf begrenzen (Anti-Runaway-Sicherheit).
  • --sleep=N: Pause in Sekunden zwischen Batches (API-Rate-Limits).

Empfohlener Cron alle 15 Minuten:

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

Der Worker setzt automatisch Einträge zurück, die seit über 30 Minuten in „In Bearbeitung“ feststecken (Absturz eines vorherigen Laufs), markiert fehlgeschlagene Items mit der API-Fehlermeldung und verarbeitet den Rest des Batches weiter.

Auto-Reindexierung

Die Hooks actionObjectProductUpdateAfter, actionObjectCategoryUpdateAfter und actionObjectCmsUpdateAfter stellen die geänderte Entität in allen aktiven Sprachen wieder in die Warteschlange. Lösch-Hooks entfernen Embeddings und Vorschläge kaskadiert. Der SHA-256-Inhalts-Hash vermeidet jeden API-Aufruf, wenn sich der tatsächliche Text nicht geändert hat (z. B. eine bloße Bestandsänderung).

Multishop und Mehrsprachigkeit

Embeddings sind nach dem Tripel (Entität, Sprache, Shop) gescoped. Vorschläge überschreiten niemals Sprach- oder Shop-Grenzen. Die Konfiguration (API-Schlüssel, Schwellenwert, indizierte Typen) kann pro Shop über den Standard-Multishop-Kontextwähler von PrestaShop unterschiedlich sein.

Fehlerbehebung

„API-Schlüssel nicht konfiguriert“ oder Fehler beim Verbindungstest

Prüfen Sie, dass der Schlüssel zum im Dropdown ausgewählten Anbieter passt (ein Mistral-Schlüssel funktioniert nicht mit dem OpenAI-Anbieter und umgekehrt) und dass er über Guthaben verfügt. Detaillierte API-Fehler werden in Erweiterte Einstellungen → Logs protokolliert (PrestaShopLogger).

Items verbleiben im Status „In Bearbeitung“

Wahrscheinlich wurde ein Worker unterbrochen. Warten Sie 30 Minuten (Auto-Reset) oder klicken Sie Warteschlange leeren und starten Sie Alles reindexieren erneut.

Wenige oder keine Vorschläge generiert

Drei häufige Ursachen: Ähnlichkeitsschwellenwert zu hoch (versuchen Sie 0,72), zu kurze Inhalte (unter der Mindestlänge) oder ein zu homogener/heterogener Katalog. Prüfen Sie auch, dass die gewünschten Entitätstypen in den Einstellungen aktiviert sind.

Der vorgeschlagene Anker ist der rohe Zieltitel

Das ist der Fallback-Modus: kein N-Gramm des Zieltitels kommt wörtlich im Quellkörper vor. Wählen Sie einen benutzerdefinierten Anker oder erweitern Sie die Quellbeschreibung.

Technische Architektur

  • Striktes PHP 8.1+, PSR-4 unter dem Namespace DataFirefly/AiSemanticLinks/ gemappt auf src/
  • Legacy-ModuleAdminController-Admin-Controller (stabile PS8/PS9-Kompatibilität)
  • Winziger hauseigener Service-Container (unabhängig vom Symfony-Container)
  • Vektoren als little-endian gepacktes float32 BLOB + vorberechnete L2-Norm
  • 5 Tabellen: dfasl_embedding, dfasl_queue, dfasl_suggestion, dfasl_inserted_link, dfasl_job
  • Unverschlüsselter Quellcode, bereit zum Überschreiben
War diese Seite hilfreich?

Immer noch nicht weiter? Support kontaktieren