Topic Cluster Detector — Dokumentation
Installation, Konfiguration der 3 Clustering-Modi (TF-IDF, OpenAI, Mistral), Ergebnisse lesen, Pillar Gaps verwalten und empfohlener SEO-Workflow.
Diese Dokumentation beschreibt die Installation, Konfiguration und Verwendung des Moduls Topic Cluster Detector auf PrestaShop 8 und 9. Das Modul erkennt automatisch die thematischen Gruppierungen Ihres Katalogs durch semantisches Clustering und schlägt fehlende Pillar Pages mit einem vollständigen SEO-Entwurf für jede Chance vor.
Übersicht
Der Topic Cluster Detector analysiert Ihren Produktkatalog, um die tatsächlich vorhandenen Topic Cluster in Ihrem Angebot aufzudecken, und erkennt dann fehlende Pillar Pages: jene übergreifenden Themen, die von Ihren Produkten stark abgedeckt werden, aber keine strukturierende Mutterseite (CMS oder Kategorie) haben.
Für jeden erkannten Gap generiert das Modul einen vollständigen Entwurf:
- SEO-optimierter H1-Titel
- URL-sicherer Slug
- Meta-Beschreibung
- Vollständige H2-Markdown-Gliederung
- Liste der Ziel-Keywords
- Prioritätswert (Größe × Kohäsion)
Installation
Voraussetzungen
- PrestaShop 8.0+ oder 9.x
- PHP 8.0 mindestens (PHP 8.1 oder 8.2 empfohlen)
memory_limitvon mindestens 512 MB (1024 MB empfohlen für große Kataloge)- Optional: OpenAI- oder Mistral-API-Schlüssel für den Embeddings-Modus
Installationsprozedur
- Laden Sie die Datei
dftopicclusters.zipaus Ihrem DataFirefly-Kundenbereich herunter. - Gehen Sie im PrestaShop-Back-Office zu Module → Module Manager und klicken Sie auf Modul hochladen.
- Wählen Sie das ZIP aus und bestätigen Sie. Das Modul wird automatisch installiert.
- Nach der Installation klicken Sie auf Konfigurieren.
Bei der Installation erstellt das Modul automatisch:
- Die 5 SQL-Tabellen mit Präfix
df_topicclusters_ - Den übergeordneten Tab DataFirefly unter dem Menü Verbessern (falls noch nicht vorhanden)
- Den untergeordneten Tab Topic Clusters unter diesem Elternteil
- Die 19 Standard-Konfigurationsschlüssel
Erster Zugriff
Nach der Installation ist das Modul über Verbessern → DataFirefly → Topic Clusters zugänglich. Das Dashboard zeigt Ihnen das Formular zum Starten einer neuen Analyse und die Historie früherer Läufe (beim ersten Zugriff leer).
Konfiguration
Klicken Sie oben rechts im Dashboard auf die Schaltfläche Einstellungen, um zur Konfigurationsseite zu gelangen. Die Einstellungen sind in fünf Abschnitte gruppiert.
Allgemein
| Schlüssel | Standard | Beschreibung |
|---|---|---|
DFTC_MODE |
tfidf |
Clustering-Modus: tfidf (lokal), openai oder mistral |
DFTC_K_AUTO |
aktiviert | Wenn aktiviert, berechnet automatisch k = ceil(√(N/2)) begrenzt auf [5, 30] |
DFTC_K_MANUAL |
12 | k-Wert verwendet, wenn DFTC_K_AUTO deaktiviert ist |
DFTC_MAX_ITER |
60 | Maximale Anzahl der k-means-Iterationen |
DFTC_MIN_CLUSTER_SIZE |
3 | Mindestgröße eines Clusters; darunter verworfen |
Textextraktion
Ermöglicht die Auswahl, welche Produktfelder in die Analyse eingespeist werden. Die Gewichtung pro Feld ist fest (Name × 3, Meta × 2, Kurzbeschreibung × 2, Kategorien × 2, Tags × 2, Langbeschreibung × 1, Eigenschaften × 1).
DFTC_INCLUDE_DESCRIPTION— Langbeschreibung einbeziehen (empfohlen: aktiviert)DFTC_INCLUDE_CATEGORIES— Kategorienamen einbeziehen (empfohlen: aktiviert)DFTC_INCLUDE_TAGS— PrestaShop-Tags einbeziehen (empfohlen: aktiviert)DFTC_INCLUDE_FEATURES— Produkteigenschaften einbeziehen (empfohlen: deaktiviert, außer bei sehr beschreibenden Eigenschaften)
TF-IDF-Einstellungen
| Schlüssel | Standard | Beschreibung |
|---|---|---|
DFTC_MIN_DOC_FREQ |
2 | Begriff verworfen, wenn er in weniger als N Produkten vorkommt |
DFTC_MAX_DOC_FREQ_RATIO |
0.50 | Begriff verworfen, wenn er in mehr als X% des Katalogs vorkommt |
DFTC_NGRAM_MAX |
2 | 1 = Unigramme, 2 = Unigramme + Bigramme |
DFTC_TOP_TERMS_COUNT |
8 | Anzahl der pro Cluster angezeigten Begriffe |
Embeddings-APIs
| Schlüssel | Beschreibung |
|---|---|
DFTC_OPENAI_API_KEY |
OpenAI Bearer Token (sk-…) |
DFTC_OPENAI_MODEL |
Modell (Standard text-embedding-3-small) |
DFTC_MISTRAL_API_KEY |
Mistral-API-Schlüssel |
DFTC_MISTRAL_MODEL |
Modell (Standard mistral-embed) |
DFTC_BATCH_SIZE |
Anzahl der Produkte pro API-Aufruf (Standard 32) |
Pillar-Page-Erkennung
DFTC_PILLAR_MATCH_THRESHOLD— Match-Schwellenwert (Standard 0.45). Darunter wird der Cluster als Pillar Gap markiert. Erhöhen Sie den Schwellenwert, um strenger zu sein, senken Sie ihn, um toleranter zu sein.
Die drei Modi im Detail
TF-IDF-Modus (empfohlen für den Start)
TF-IDF (Term Frequency × Inverse Document Frequency) ist eine klassische statistische NLP-Methode. Das Modul baut ein Vokabular aus allen Produkttexten auf, filtert zu seltene oder zu häufige Begriffe heraus und stellt dann jedes Produkt als spärlichen Vektor in diesem Raum dar.
Vorteile: 100% lokal, sofort, kostenlos, keine externe Abhängigkeit. Hervorragend für lexikalisch homogene Kataloge (eine Domäne, ein konsistentes Vokabular).
Grenzen: versteht keine Synonyme (zwei Produkte, die unterschiedliche Begriffe für dasselbe Konzept verwenden, werden schlecht gruppiert).
OpenAI-Embeddings-Modus
Verwendet standardmäßig die OpenAI-API text-embedding-3-small. Jedes Produkt wird durch einen dichten 1536-dimensionalen Vektor dargestellt, der seine Semantik erfasst.
Vorteile: versteht Synonyme, lexikalische Varianten und Kontext. Hervorragend für diversifizierte Kataloge oder solche mit erzählerischen Beschreibungen.
Richtkosten: ca. 0,02 USD pro Million Token, also weniger als 0,10 USD für einen Katalog mit 1.000 Produkten.
df_topicclusters_embedding_cache abgerufen, ohne neuen API-Aufruf.
Mistral-Embeddings-Modus
Verwendet standardmäßig die Mistral-API mistral-embed. Leistungsstarkes mehrsprachiges Modell, besonders gut im Französischen.
Vorteile: in Europa gehostet (erleichterte DSGVO-Konformität), hervorragend bei französischen Inhalten, wettbewerbsfähige Preise.
Eine Analyse starten
Im Dashboard bietet das Formular Neue Analyse starten sechs Parameter:
- Sprache — die Sprache, in der die Produkttexte extrahiert und analysiert werden. Starten Sie einen separaten Lauf für jede aktive Sprache Ihres Shops.
- Modus — TF-IDF, OpenAI oder Mistral (überschreibt die Standardeinstellung nur für diesen Lauf).
- Anzahl der Cluster (k) — Lassen Sie 0 für Auto-k. Andernfalls erzwingen Sie einen Wert zwischen 2 und 100.
- Mindestgröße — Kleinere Cluster verworfen (Standard 3).
- Pillar-Schwellenwert — Match-Schwellenwert, unter dem ein Cluster als Gap markiert wird (Standard 0.45).
- Produktlimit — Begrenzt die Anzahl der analysierten Produkte (nützlich für Debugging oder schnelle Tests). Lassen Sie 0, um den gesamten Katalog zu analysieren.
Klicken Sie auf Analyse starten. Der Lauf beginnt sofort. Für einen Katalog mit 1.000 Produkten:
- TF-IDF-Modus: 5 bis 15 Sekunden
- Embeddings-Modus (erster Lauf): 30 Sekunden bis 2 Minuten je nach Batch-Größe
- Embeddings-Modus (folgende Läufe mit warmem Cache): äquivalent zu TF-IDF
set_time_limit(0) und memory_limit=1024M. Auf stark eingeschränkten Hostings können diese Direktiven ignoriert werden. Bevorzugen Sie einen nächtlichen Lauf oder verwenden Sie das Produktlimit zum Aufteilen.
Die Ergebnisse lesen
Nach Abschluss des Laufs gelangen Sie auf die Detailseite. Jeder Cluster wird als Karte mit vier Abschnitten dargestellt.
Cluster-Kopfzeile
Die Kopfzeile kombiniert ein Status-Badge, eine Cluster-Nummer und ein generiertes Label. Das Badge ist:
- PILLAR GAP (orange) — Keine bestehende Pillar Page deckt dieses Thema ab. Starke Chance.
- OK (grün) — Eine CMS-Seite oder Kategorie deckt dieses Thema bereits ab (das Modul hat es gematcht).
Das Label besteht aus den 3 Top-Begriffen des Clusters, verbunden durch ·. Beispiel: „Sneakers · Premium-Leder · Schuhe“.
Statistiken
- Produkte — Anzahl der Produkte im Cluster
- Kohäsion — Durchschnittliche Ähnlichkeit der Mitglieder zum Zentroid (0 bis 100%). Je höher, desto homogener der Cluster.
- Match — Match-Score mit der besten bestehenden Pillar Page. Wenn unter dem Schwellenwert → Gap.
Top-Begriffe
Die repräsentativsten Begriffe des Clusters. Im TF-IDF-Modus sind dies die Begriffe mit der stärksten Komponente im Zentroid. Im Embeddings-Modus berechnet das Modul einen cluster-internen TF, gewichtet mit dem globalen IDF, um die distinktiven Begriffe hervorzuheben.
Pillar-Page-Vorschlag
Nur vorhanden, wenn der Cluster als Gap markiert ist. Enthält:
- Titel — SEO-optimierter H1-Titel in natürlicher Sprache
- Slug — URL-sicher, im Kebab-Case
- Meta-Beschreibung — 150-160 Zeichen
- Priorität — Kombinierter Score Größe (0.6) × Kohäsion (0.4)
- Vorgeschlagene Gliederung — H2-Markdown-Gliederung mit klassischen Abschnitten (Einleitung, was ist, wie wählen, Vergleich, beste Produkte, Anwendungsfälle, zu vermeidende Fehler, FAQ, CTA)
Cluster-Produkte
Liste der gruppierten Produkte mit ihrer Ähnlichkeitsbewertung zum Zentroid, sortiert nach absteigender Ähnlichkeit. Klicken Sie auf die Produkt-ID, um das Produktblatt direkt in einem neuen Fenster zu öffnen.
Empfohlener Workflow
Hier ist eine typische Verwendung des Moduls in 4 Schritten.
- Erstes Audit — Starten Sie einen TF-IDF-Lauf in Ihrer Hauptsprache mit den Standardparametern. Prüfen Sie die als Gap markierten Cluster: Sind sie redaktionell relevant?
- Triage — Verwenden Sie für jeden Gap die Schaltfläche Verwerfen, wenn der Cluster keine Pillar Page verdient (z.B. eine zufällige Gruppierung heterogener Produkte). Die verbleibenden Gaps sind Ihre Prioritäten.
- Redaktion — Erstellen Sie für jeden beibehaltenen Gap eine neue CMS-Seite in PrestaShop mit dem Titel, Slug und Meta des Entwurfs. Verwenden Sie die H2-Gliederung als Schreibgerüst. Klicken Sie nach der Veröffentlichung auf Erledigt markieren.
- Neustart — Nach der Veröffentlichung der neuen Seiten starten Sie einen weiteren Lauf. Die früheren Gaps sollten jetzt OK sein (das Modul erkennt die neuen Pillar Pages).
Export
Auf der Detailseite eines Laufs ermöglichen zwei Schaltflächen oben rechts den Export:
- CSV — Tabelle mit einer Zeile pro Cluster, Spalten: id_cluster, label, n_members, Kohäsion, pillar_gap, match_score, suggested_title, suggested_slug, suggested_meta, priority_score, target_keywords. UTF-8-Kodierung mit BOM (Excel-kompatibel).
- JSON — Vollständiger Export mit der Produktliste pro Cluster und der vollständigen Markdown-Gliederung. Ideal für Automatisierung oder externe Integration.
Technische Architektur
Datenbank
Das Modul erstellt 5 Tabellen mit dem Präfix df_topicclusters_:
run— Metadaten jeder Ausführung (Modus, Sprache, Status, Dauer, Zähler)cluster— Einzelne Cluster (Label, Top-Begriffe JSON, Kohäsion, pillar_gap-Flag, match_score)cluster_product— Produkt → Cluster-Zugehörigkeit mit Ähnlichkeitsbewertungpillar— Pillar-Page-Vorschläge (Titel, Slug, Meta, Gliederung, Priorität, Status)embedding_cache— Embeddings-Vektor-Cache indiziert nach Text-Hash
PSR-4 und Autoload
Der Root-Namespace ist DataFirefly/TopicClusters/. Ein manueller Autoload wird über spl_autoload_register in der Hauptdatei des Moduls registriert, sodass keine Composer-Abhängigkeit erforderlich ist.
Controllers und PS 8 / PS 9-Kompatibilität
Das Modul verwendet einen Legacy-ModuleAdminController (und nicht einen Symfony-Controller), um die Kompatibilität mit beiden Hauptversionen zu garantieren. SQL-Abfragen sind so geschrieben, dass sie die Schemata beider Versionen respektieren, insbesondere die Entfernung der Spalte meta_keywords in PS 9.
Leistung und Grenzen
- Kataloge bis zu 1.000 Produkten — Läufe in Sekunden. Keine besondere Sorge.
- 1.000 bis 10.000 Produkte — TF-IDF-Modus bleibt schnell (10-60 s). Embeddings-Modus: rechnen Sie mit 1 bis 5 Minuten für den ersten Lauf, danach sofort dank des Caches.
- Mehr als 10.000 Produkte — Bevorzugen Sie den Parameter Produktlimit zum Aufteilen oder erhöhen Sie
memory_limitauf 2 GB.
Die k-means-Komplexität ist O(n × k × iter × d), wobei n die Anzahl der Produkte, k die Anzahl der Cluster, iter die Anzahl der Iterationen (typischerweise 10-30) und d die Vektordimension ist (variabel in TF-IDF, 1536 in OpenAI).
Fehlerbehebung
Keine Cluster erkannt
Überprüfen Sie, ob Ihre Produkte textuellen Inhalt in der analysierten Sprache haben (mindestens einen Namen und idealerweise eine Beschreibung). Wenn DFTC_MIN_DOC_FREQ für Ihren Katalog zu hoch ist, senken Sie es auf 1.
Alle Cluster sind als Pillar Gap markiert
Der Schwellenwert DFTC_PILLAR_MATCH_THRESHOLD ist wahrscheinlich zu hoch. Probieren Sie 0.30 statt 0.45, wenn Ihr Shop wenige CMS-Seiten hat. Überprüfen Sie auch, ob Ihre CMS-Seiten und Kategorien aktiv sind.
Fehler „Unknown column meta_keywords“
Dieser Fehler tritt auf PrestaShop 9 mit einer früheren Modulversion auf. Aktualisieren Sie auf Version 1.0.0 oder höher, die alle Verweise auf meta_keywords entfernt (Spalte in PS 9 entfernt).
Fehler „Compile Error: Access level to processExport() must be public“
Dieser Fehler trat in einer Pre-1.0.0-Version auf. Der Methodenname ist jetzt doExport(), um die Kollision mit AdminControllerCore zu vermeiden. Aktualisieren Sie das Modul.
Der Lauf schlägt mit API-Fehler fehl
Überprüfen Sie, ob der in der Konfiguration eingegebene API-Schlüssel gültig ist und Guthaben hat. Testen Sie mit curl in der CLI, um zu bestätigen, dass der Server api.openai.com oder api.mistral.ai erreichen kann.
Demnächst
- Direkte CMS-Seitenerstellung aus dem Entwurf (mit einem Klick)
- Lauf-Vergleich (vor/nach Pillar-Page-Veröffentlichung)
- Grafische Visualisierung des Inter-Cluster-Semantik-Netzwerks
- Unterstützung für Cohere- und Voyage-AI-Embeddings
- Automatischer Cron für periodische Wiederholungen