Semantik-Audit — Dokumentation

Installation

Voraussetzungen

• PrestaShop 8.0 bis 9.x
• PHP 7.4 mindestens (8.x empfohlen)
• MySQL 5.7+ oder MariaDB 10.3+
• Ein OpenAI- oder Mistral-API-Schlüssel (optional — ein lokaler Modus ohne API ist enthalten)

Modul installieren

1. Entpacken Sie die Datei dfsemanticaudit.zip, die Sie aus Ihrem Kundenkonto heruntergeladen haben.
2. Laden Sie den Ordner dfsemanticaudit/ per FTP in /modules/ Ihres PrestaShop hoch, oder verwenden Sie die ZIP-Installation über Module → Module Manager → Modul hochladen.
3. Klicken Sie auf Installieren.

Modul aktivieren

Das Modul erstellt automatisch vier SQL-Tabellen (ps_dfsa_content, ps_dfsa_audit, ps_dfsa_cluster, ps_dfsa_assignment) sowie einen Admin-Tab, der über das linke Menü zugänglich ist.

Konfiguration

Gehen Sie vor dem ersten Audit zu Module → DataFirefly → Semantik-Audit → Konfiguration.

Wahl des Embedding-Anbieters

Drei Anbieter stehen zur Verfügung. Die Wahl bestimmt die Qualität der erhaltenen Cluster.

OpenAI (empfohlen)

Der Standardanbieter. Verwendet das Modell text-embedding-3-small (1.536 Dimensionen). Höchste Qualität, Grenzkosten: etwa 0,02 € pro 1.000 Produkte bei der ersten Indizierung.

• API-Schlüssel: erstellen Sie ihn auf platform.openai.com/api-keys
• Modell: belassen Sie text-embedding-3-small als Standard. text-embedding-3-large (3.072 dim) bietet leicht höhere Qualität, kostet aber 6× mehr.

Mistral

Europäische Alternative, gehostet in Frankreich. Verwendet mistral-embed (1.024 Dimensionen). Preisgestaltung vergleichbar mit OpenAI.

• API-Schlüssel: erstellen Sie ihn auf console.mistral.ai
• Modell: mistral-embed

Lokales TF-IDF

Läuft vollständig auf Ihrem Server, ohne API-Aufrufe, ohne wiederkehrende Kosten. Verwendet klassische statistische NLP-Prinzipien (normalisiertes TF-IDF) mit 384 Dimensionen.

• Ausreichende Qualität für Kataloge unter 500 Produkten.
• Unterstützt FR, EN, ES, DE, IT (integrierte Stopwords).
• Kein API-Schlüssel erforderlich.

Audit-Parameter

• k (Anzahl der Cluster): standardmäßig 8. Bereich 2–50.
• Off-Topic-Schwellenwert: Kosinus-Distanz, ab der ein Inhalt markiert wird. Standardmäßig 0,55. Bereich 0,1 bis 1,5.

Auto-Reindex

Standardmäßig aktiviert. Das Modul registriert Hooks bei der Erstellung, Änderung und Löschung von Produkten, Kategorien und CMS-Seiten. Bei jeder Änderung wird der Inhalt zur Re-Einbettung beim nächsten Lauf markiert, ohne manuellen Aufwand.

Ihr erstes Audit starten

Drei Schritte, die in der Reihenfolge über das Dashboard ausgeführt werden.

Schritt 1 — Inhalt neu indizieren

Klicken Sie auf Inhalt neu indizieren. Das Modul durchläuft Ihre Produkte, aktiven Kategorien, CMS-Seiten und Hersteller, berechnet einen SHA1-Hash von Titel + Auszug und markiert nur neue oder geänderte Inhalte zur Verarbeitung.

Für 1.000 Elemente dauert dieser Schritt einige Sekunden.

Schritt 2 — Embeddings generieren

Klicken Sie auf Embeddings generieren. Das Modul sendet die als „dirty“ markierten Inhalte an den ausgewählten Anbieter in Stapeln von 50 (OpenAI/Mistral) oder in einem einzigen lokalen Durchgang (TF-IDF). Ein Fortschrittsbalken verfolgt den Fortschritt.

Für 1.000 Elemente:

• OpenAI: ~30 Sekunden
• Mistral: ~40 Sekunden
• Lokales TF-IDF: <1 Sekunde

Schritt 3 — Audit starten

Klicken Sie auf Audit starten. Das k-means Kosinus-Clustering gruppiert die Inhalte in k Cluster (k-means++-Initialisierung, 50 maximale Iterationen), beschriftet jedes Cluster mit seinen Top-Begriffen (TF×IDF), berechnet die Distanz jedes Inhalts zu seinem Zentroid und identifiziert Ausreißer.

Dieser Schritt dauert weniger als eine Sekunde, sogar für 5.000 Elemente.

Den Bericht verstehen

Dashboard

Vier wichtige KPIs oben:

• Indizierte Inhalte — Gesamtzahl der eingebetteten Produkte, Kategorien, CMS-Seiten und Hersteller.
• Off-Topic-Seiten — absolute Anzahl, prozentuale Rate und Aufteilung nach Typ.
• Thematische Cluster — Anzahl der identifizierten thematischen Gruppen.
• Median-Distanz — Median der Kosinus-Distanz zum Zentroid. Unter 0,40 = sehr kohärenter Katalog. Über 0,60 = verstreuter Katalog.

Cluster

Ansicht Cluster: detaillierte, nach Größe sortierte Liste mit automatischer Beschriftung (Top 5 TF×IDF-Begriffe), Kohäsions-Score (0 = verstreut, 1 = identisch) und Größe (Anzahl der Elemente).

Ein Cluster mit Kohäsion < 0,40 ist zu heterogen — oft ein Zeichen, dass das Thema in zwei Untertopics aufgeteilt werden sollte oder dass k zu niedrig ist.

2D-Semantikkarte

Projektion aller Inhalte auf eine 2D-Ebene per Johnson-Lindenstrauss-Technik (eine zufällige Projektion, die Distanzen näherungsweise erhält).

Jeder Punkt ist ein Inhalt, jede Farbe ein Cluster. Die Kreuze markieren die Zentroide. Punkte mit rotem Umriss sind Off-Topic. Die Legende rechts ermöglicht das Ein-/Ausblenden jedes Clusters durch Anklicken.

Off-Topic-Seiten

Ansicht Off-Topic-Seiten: sortierbare Tabelle der Inhalte, deren Kosinus-Distanz zum Zentroid den konfigurierten Schwellenwert überschreitet. Für jede Zeile:

• Typ, Titel, öffentliche URL und direkter Link zum Bearbeitungsformular
• Aktuelles Cluster (mit seiner Farbe)
• Distanz zum Zentroid (je höher, desto weiter entfernt)
• Vorgeschlagenes Cluster (falls relevant)
• Δ Gewinn: Distanzreduktion, wenn der Inhalt verschoben würde

Hoffnungslose Seiten

Unten in der Off-Topic-Ansicht listet ein spezieller Abschnitt Inhalte auf, die weit von allen Clustern entfernt sind. Das Modul hat kein lebensfähiges Ziel für sie gefunden.

Drei Optionen zur Erwägung:

1. Löschen, wenn die Seite keinen SEO-Traffic oder Konversion hat.
2. Noindex, um Crawl-Budget zu sparen, ohne den Verlauf zu verlieren.
3. Umschreiben, um den Inhalt an ein bestehendes Cluster anzupassen.

Umstrukturierungsvorschläge

Ansicht Vorschläge: entspricht Off-Topic-Seiten, aber aktionsorientiert. Alle vorgeschlagenen Verschiebungen werden mit dem erwarteten Kohärenzgewinn aufgelistet. Sortieren Sie nach absteigendem Gewinn, um die wirkungsvollsten Fälle zuerst zu bearbeiten.

Das Modul ändert niemals Ihre Baumstruktur automatisch. Änderungen bleiben unter Ihrer Kontrolle über das Standard-PrestaShop-Backoffice.

CSV-Export

In jeder Berichtsansicht ermöglicht eine Schaltfläche CSV exportieren das Herunterladen der Rohdaten. Nützlich für:

• Den Bericht mit einem externen SEO-Berater teilen
• Die Daten in Excel/Sheets verarbeiten
• Den Zustand eines Audits archivieren, bevor die Baumstruktur geändert wird

Automatisierung via Cron

Das Modul stellt eine signierte URL auf der Konfigurationsseite bereit. Sie löst im Headless-Modus die vollständige Kette Indizierung → Embeddings → Audit aus.

Beispiel für einen wöchentlichen Cron-Job (jeden Montag um 3 Uhr):

0 3 * * 1 wget -q -O /dev/null "https://ihr-shop.com/modules/dfsemanticaudit/cron.php?token=IHR_TOKEN"

Der Token wird aus dem _COOKIE_KEY_ Ihres PrestaShop abgeleitet und ändert sich nur bei einer Neuinstallation. Bewahren Sie ihn sorgfältig auf.

API-Kosten

Schätzung für einen durchschnittlichen Katalog (1.000 Produkte):

• OpenAI text-embedding-3-small: ~0,02 € beim ersten Mal, danach nahezu null (nur geänderte Inhalte werden neu verarbeitet)
• OpenAI text-embedding-3-large: ~0,13 € beim ersten Mal
• Mistral mistral-embed: ~0,10 € beim ersten Mal
• Lokales TF-IDF: 0 €

Mehrsprachig und Multi-Shop

Das Modul ist nativ mehrsprachig und multi-shop-fähig. Jedes Audit läuft auf einem bestimmten Sprache × Shop-Paar und verwendet die Kontextsprache des Backoffice.

Um Ihren französischen und dann Ihren englischen Shop zu auditieren, wechseln Sie die Sprache in der oberen Leiste von PrestaShop und starten Sie dann ein neues Audit.

Fehlerbehebung

Der Schritt „Embeddings generieren“ schlägt mit einem 401-Fehler fehl

Ihr API-Schlüssel ist ungültig oder abgelaufen. Überprüfen Sie ihn auf der Konfigurationsseite und konfigurieren Sie ihn ggf. neu.

Der Schritt „Embeddings generieren“ schlägt mit einem 429-Fehler fehl

Sie haben das Ratenlimit Ihres Anbieters erreicht. Warten Sie einige Minuten und versuchen Sie es erneut — das Modul setzt dank seiner Stapelverarbeitung dort fort, wo es aufgehört hat.

Kein Cluster erscheint relevant

Drei Ansätze:

1. Erhöhen Sie die Anzahl der Cluster (k). Wenn Ihr Katalog 10 unterschiedliche Themen hat, aber k=4 ist, kann das Clustering sie nicht trennen.
2. Wechseln Sie vom lokalen TF-IDF-Modus zu OpenAI oder Mistral. Bei heterogenen Katalogen macht die semantische Qualität den ganzen Unterschied.
3. Überprüfen Sie, ob die Titel und Beschreibungen Ihrer Inhalte ausreichend reichhaltig sind. Ein Produkt mit einem Titel aus 2 Wörtern und ohne Beschreibung wird kein gutes Embedding ergeben.

Zu viele Seiten als Off-Topic markiert

Erhöhen Sie den Off-Topic-Schwellenwert (z. B. von 0,55 auf 0,70). Das ist zu erwarten, wenn Ihr Katalog legitim mehrere breite Themen abdeckt.

Keine Off-Topic-Seite markiert, aber der Katalog erscheint inkohärent

Senken Sie den Schwellenwert (z. B. von 0,55 auf 0,40), um die Erkennung zu verschärfen.

FAQ

Ist ein API-Schlüssel zwingend erforderlich?

Nein. Der lokale TF-IDF-Modus funktioniert ohne externe Verbindung. Er ist etwas weniger präzise als OpenAI/Mistral, reicht aber zum Start oder für einen homogenen Katalog aus.

Ändert das Modul automatisch meine Baumstruktur?

Nein. Das Modul empfiehlt nur. Alle Inhaltsverschiebungen bleiben in Ihrer Verantwortung über das Standard-PrestaShop-Backoffice.

Wie wähle ich die Anzahl der Cluster (k)?

Faustregel: k ≈ Anzahl der Hauptkategorien der obersten Ebene. Standardmäßig funktioniert k=8 gut zwischen 100 und 5.000 Produkten. Starten Sie 2 oder 3 Audits mit verschiedenen k-Werten zum Vergleich, wenn Sie unsicher sind — vorherige Audits bleiben im Verlauf.

Werden meine Vektoren an einen Drittserver gesendet?

Mit OpenAI oder Mistral: ja, die Titel und Auszüge Ihrer Inhalte werden an deren Embeddings-API gesendet. Mit dem lokalen TF-IDF-Modus: nein, keine Daten verlassen Ihren Server.

Wie lange werden Audits aufbewahrt?

Unbegrenzt, bis zur manuellen Löschung über das Dashboard. Sie können den vollständigen Verlauf durchsuchen, um die Entwicklung Ihrer semantischen Kohärenz im Zeitverlauf zu messen.

Funktioniert das Modul im Multi-Shop?

Ja. Jeder Shop im Multistore kann seine eigenen unabhängigen Audits haben.