# Topic Cluster Detector — Dokumentation

> 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…

- Seite: <https://www.datafirefly.com/de/documentation/topic-cluster-detector/>
- Sprache: de
- Aktualisiert am: 2026-06-28
- Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/topic-cluster-detector/index.md), [en](https://www.datafirefly.com/en/documentation/topic-cluster-detector/index.md), [es](https://www.datafirefly.com/es/documentation/topic-cluster-detector/index.md), [it](https://www.datafirefly.com/it/documentation/topic-cluster-detector/index.md), [pl](https://www.datafirefly.com/pl/documentation/topic-cluster-detector/index.md), [nl](https://www.datafirefly.com/nl/documentation/topic-cluster-detector/index.md), [pt](https://www.datafirefly.com/pt/documentation/topic-cluster-detector/index.md)
- Index: <https://www.datafirefly.com/de/documentation/llms.txt>

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)

**Zu beachten.** Das Modul erstellt keine Seiten direkt in PrestaShop. Es liefert Ihnen einen Entwurf zum Kopieren-Einfügen in eine neue CMS-Seite oder Kategorie-Landingpage und belässt die redaktionelle Entscheidung in Ihren Händen.

## Installation

### Voraussetzungen

- PrestaShop **8.0+** oder **9.x**
- PHP **8.0 mindestens** (PHP 8.1 oder 8.2 empfohlen)
- `memory_limit` von mindestens 512 MB (1024 MB empfohlen für große Kataloge)
- Optional: OpenAI- oder Mistral-API-Schlüssel für den Embeddings-Modus

### Installationsprozedur

1. Laden Sie die Datei `dftopicclusters.zip` aus Ihrem DataFirefly-Kundenbereich herunter.
2. Gehen Sie im PrestaShop-Back-Office zu **Module → Module Manager** und klicken Sie auf **Modul hochladen**.
3. Wählen Sie das ZIP aus und bestätigen Sie. Das Modul wird automatisch installiert.
4. 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.

**Tipp.** Der Embeddings-Cache ist automatisch: Wenn Sie einen Lauf auf demselben Katalog wiederholen, ohne die Texte zu ändern, werden die Vektoren aus der Tabelle `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

**Wichtig.** Das Modul setzt während der Laufdauer `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.

1. **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?
2. **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.
3. **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**.
4. **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).

**SEO-Best-Practices.** Eine qualitativ hochwertige Pillar Page hat mindestens 1.500 Wörter, integriert interne Links zu den Produkten des Clusters und verwendet die Top-Begriffe natürlich im Inhalt. Der generierte Entwurf ist ein Ausgangspunkt, kein endgültiges Deliverable.

## 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 Ähnlichkeitsbewertung
- `pillar` — 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_limit` auf 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

**Support.** Bei Fragen oder Bugs wenden Sie sich an [support@datafirefly.com](mailto:support@datafirefly.com). Feedback ist wertvoll für die Ausrichtung der Roadmap.