# Detektor Topic Clusterów: dokumentacja

> Ta dokumentacja opisuje instalację, konfigurację i użytkowanie modułu Detektor Topic Clusterów w PrestaShop 8 i 9. Moduł automatycznie wykrywa grupowania tematyczne w katalogu przez klastrowanie semantyczne i sugeruje brakujące pillar…

- Strona: <https://www.datafirefly.com/pl/documentation/topic-cluster-detector/>
- Język: pl
- Zaktualizowano: 2026-08-01
- Inne języki: [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), [de](https://www.datafirefly.com/de/documentation/topic-cluster-detector/index.md), [it](https://www.datafirefly.com/it/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)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

Ta dokumentacja opisuje instalację, konfigurację i użytkowanie modułu **Detektor Topic Clusterów** w PrestaShop 8 i 9. Moduł automatycznie wykrywa grupowania tematyczne w katalogu przez klastrowanie semantyczne i sugeruje brakujące pillar pages wraz z kompletnym szkicem SEO dla każdej szansy.

## Prezentacja

Detektor Topic Clusterów analizuje katalog produktowy, aby wyłonić **topic clustery realnie obecne** w Twojej ofercie, a następnie wykrywa **brakujące pillar pages**: te przekrojowe tematy silnie pokryte przez produkty, ale pozbawione strukturyzującej strony-matki (CMS lub kategoria).

Dla każdego wykrytego gapu moduł generuje kompletny szkic:

- Tytuł H1 zoptymalizowany pod SEO
- Slug bezpieczny dla URL
- Meta description
- Kompletny plan H2 w markdown
- Lista docelowych słów kluczowych
- Score priorytetu (rozmiar x spójność)

**Do zapamiętania.** Moduł nie tworzy stron bezpośrednio w PrestaShop. Daje Ci szkic do skopiowania na nową stronę CMS lub landing page kategorii, pozostawiając decyzję redakcyjną w Twoich rękach.

## Instalacja

### Wymagania

- PrestaShop **8.0+** lub **9.x**
- PHP **8.0 minimum** (zalecane PHP 8.1 lub 8.2)
- `memory_limit` minimum 512 MB (1024 MB zalecane dla dużych katalogów)
- Opcjonalnie: klucz API OpenAI lub Mistral dla trybu embeddingów

### Procedura instalacji

1. Pobierz plik `dftopicclusters.zip` ze swojego konta klienta DataFirefly.
2. W back-office PrestaShop przejdź do **Moduły / Menedżer modułów**, a następnie kliknij **Wgraj moduł**.
3. Wybierz ZIP i zatwierdź. Moduł instaluje się automatycznie.
4. Po instalacji kliknij **Konfiguruj**.

Podczas instalacji moduł automatycznie tworzy:

- 5 tabel SQL z prefiksem `df_topicclusters_`
- Zakładkę nadrzędną **DataFirefly** w menu Ulepszenia (jeśli jeszcze nie istnieje)
- Zakładkę podrzędną **Topic Clusters** pod tym rodzicem
- 19 domyślnych kluczy konfiguracyjnych

### Pierwsze uruchomienie

Po instalacji moduł jest dostępny przez **Ulepszenia / DataFirefly / Topic Clusters**. Pulpit prezentuje formularz uruchamiania nowej analizy oraz historię poprzednich runów (pustą przy pierwszym otwarciu).

## Konfiguracja

Kliknij przycisk **Ustawienia** w prawym górnym rogu pulpitu, aby przejść do strony konfiguracji. Ustawienia są pogrupowane w pięć sekcji.

### Ogólne

| Klucz | Domyślnie | Opis |
| --- | --- | --- |
| `DFTC_MODE` | `tfidf` | Tryb klastrowania: `tfidf` (lokalny), `openai` lub `mistral` |
| `DFTC_K_AUTO` | włączone | Jeśli włączone, automatycznie oblicza k = ceil(sqrt(N/2)) ograniczone do [5, 30] |
| `DFTC_K_MANUAL` | 12 | Wartość k używana, gdy `DFTC_K_AUTO` jest wyłączone |
| `DFTC_MAX_ITER` | 60 | Maksymalna liczba iteracji k-means |
| `DFTC_MIN_CLUSTER_SIZE` | 3 | Minimalny rozmiar klastra; poniżej tej wartości klaster jest odrzucany |

### Ekstrakcja tekstu

Pozwala wybrać, które pola produktu są wprowadzane do analizy. Ważenie per pole jest stałe (nazwa x 3, meta x 2, krótki opis x 2, kategorie x 2, tagi x 2, długi opis x 1, cechy x 1).

- `DFTC_INCLUDE_DESCRIPTION`: uwzględnij długi opis (zalecane: włączone)
- `DFTC_INCLUDE_CATEGORIES`: uwzględnij nazwy kategorii (zalecane: włączone)
- `DFTC_INCLUDE_TAGS`: uwzględnij tagi PrestaShop (zalecane: włączone)
- `DFTC_INCLUDE_FEATURES`: uwzględnij cechy produktu (zalecane: wyłączone, chyba że Twoje cechy są bardzo opisowe)

### Ustawienia TF-IDF

| Klucz | Domyślnie | Opis |
| --- | --- | --- |
| `DFTC_MIN_DOC_FREQ` | 2 | Termin ignorowany, jeśli występuje w mniej niż N produktach |
| `DFTC_MAX_DOC_FREQ_RATIO` | 0.50 | Termin ignorowany, jeśli występuje w więcej niż X % katalogu |
| `DFTC_NGRAM_MAX` | 2 | 1 = unigramy, 2 = unigramy + bigramy |
| `DFTC_TOP_TERMS_COUNT` | 8 | Liczba terminów wyświetlanych per klaster |

### API embeddingów

| Klucz | Opis |
| --- | --- |
| `DFTC_OPENAI_API_KEY` | Bearer token OpenAI (sk-...) |
| `DFTC_OPENAI_MODEL` | Model (domyślnie `text-embedding-3-small`) |
| `DFTC_MISTRAL_API_KEY` | Klucz API Mistral |
| `DFTC_MISTRAL_MODEL` | Model (domyślnie `mistral-embed`) |
| `DFTC_BATCH_SIZE` | Liczba produktów na wywołanie API (domyślnie 32) |

### Wykrywanie pillar pages

- `DFTC_PILLAR_MATCH_THRESHOLD`: próg dopasowania (domyślnie 0.45). Poniżej tej wartości klaster jest oznaczany jako _pillar gap_. Zwiększ próg, aby być bardziej restrykcyjnym, zmniejsz go, aby być bardziej tolerancyjnym.

## Trzy tryby w szczegółach

### Tryb TF-IDF (zalecany na start)

TF-IDF (Term Frequency x Inverse Document Frequency) to klasyczna metoda statystyczna w NLP. Moduł buduje słownik ze wszystkich tekstów produktowych, filtruje terminy zbyt rzadkie lub zbyt częste, a następnie reprezentuje każdy produkt jako wektor rzadki w tej przestrzeni.

**Zalety:** w 100% lokalny, natychmiastowy, bez kosztów, bez zewnętrznych zależności. Doskonały dla katalogów jednorodnych leksykalnie (jedna domena, spójne słownictwo).

**Ograniczenia:** nie rozumie synonimów (dwa produkty używające różnych terminów dla tego samego pojęcia zostaną źle pogrupowane).

### Tryb embeddingów OpenAI

Używa API OpenAI `text-embedding-3-small` domyślnie. Każdy produkt jest reprezentowany przez gęsty wektor 1536 wymiarów, który oddaje jego semantykę.

**Zalety:** rozumie synonimy, warianty leksykalne i kontekst. Doskonały dla katalogów zróżnicowanych lub o narracyjnych opisach.

**Koszt orientacyjny:** około 0,02 USD za milion tokenów, czyli poniżej 0,10 USD dla katalogu 1000 produktów.

**Wskazówka.** Cache embeddingów działa automatycznie: jeśli ponownie uruchomisz run na tym samym katalogu bez modyfikacji tekstów, wektory są pobierane z tabeli `df_topicclusters_embedding_cache` bez nowego wywołania API.

### Tryb embeddingów Mistral

Używa API Mistral `mistral-embed` domyślnie. Wydajny model wielojęzyczny, szczególnie dobry w języku francuskim.

**Zalety:** hostowany w Europie (ułatwiona zgodność z RODO), doskonały na treściach frankofońskich, konkurencyjna cena.

## Uruchamianie analizy

Z poziomu pulpitu formularz **Uruchom nową analizę** oferuje sześć parametrów:

- **Język**: język, w którym teksty produktowe będą ekstrahowane i analizowane. Uruchom osobny run dla każdego aktywnego języka sklepu.
- **Tryb**: TF-IDF, OpenAI lub Mistral (nadpisuje ustawienie domyślne tylko dla tego runu).
- **Liczba klastrów (k)**: pozostaw 0 dla auto-k. W przeciwnym razie wymuś wartość od 2 do 100.
- **Minimalny rozmiar**: mniejsze klastry są odrzucane (domyślnie 3).
- **Próg pillar**: próg dopasowania, poniżej którego klaster jest oznaczany jako gap (domyślnie 0.45).
- **Limit produktów**: ogranicza liczbę analizowanych produktów (przydatne do debugowania lub szybkiego testu). Pozostaw 0, aby przeanalizować cały katalog.

Kliknij **Uruchom analizę**. Run startuje natychmiast. Dla katalogu 1000 produktów:

- Tryb TF-IDF: 5 do 15 sekund
- Tryb embeddingów (pierwszy run): 30 sekund do 2 minut w zależności od batch size
- Tryb embeddingów (kolejne runy z ciepłym cache): równoważnie z TF-IDF

**Ważne.** Moduł ustawia `set_time_limit(0)` i `memory_limit=1024M` na czas trwania runu. Na bardzo ograniczonych hostingach te dyrektywy mogą być ignorowane. Postaw na run nocny lub użyj limitu produktów, aby podzielić pracę.

## Odczyt wyników

Po zakończeniu runu przechodzisz na stronę szczegółów. Każdy klaster jest wyświetlany jako karta z czterema sekcjami.

### Nagłówek klastra

Nagłówek łączy badge statusu, numer klastra i wygenerowaną etykietę. Badge to:

- **PILLAR GAP** (pomarańczowy): żadna istniejąca pillar page nie pokrywa tego tematu. Silna szansa.
- **OK** (zielony): strona CMS lub kategoria już pokrywa ten temat (moduł ją dopasował).

Etykieta składa się z 3 top-terminów klastra połączonych znakiem `·`. Przykład: „sneakersy · skóra premium · buty".

### Statystyki

- **Produkty**: liczba produktów w klastrze
- **Spójność**: średnie podobieństwo członków do centroidu (0 do 100 %). Im wyższa, tym klaster jest bardziej jednorodny.
- **Dopasowanie**: score dopasowania do najlepszej istniejącej pillar page. Poniżej progu oznacza gap.

### Top terminy

Terminy najbardziej reprezentatywne dla klastra. W trybie TF-IDF są to terminy o najsilniejszej składowej w centroidzie. W trybie embeddingów moduł oblicza wewnętrzne TF klastra ważone globalnym IDF, aby wyłonić terminy wyróżniające.

### Sugestia pillar page

Obecna wyłącznie wtedy, gdy klaster jest oznaczony jako gap. Zawiera:

- **Tytuł**: tytuł H1 zoptymalizowany pod SEO, w naturalnym języku
- **Slug**: bezpieczny dla URL, w kebab-case
- **Meta description**: 150-160 znaków
- **Priorytet**: score łączony rozmiar (0.6) x spójność (0.4)
- **Sugerowany plan**: plan H2 w markdown z klasycznymi sekcjami (wprowadzenie, czym jest, jak wybrać, porównanie, najlepsze produkty, przypadki użycia, błędy do uniknięcia, FAQ, CTA)

### Produkty klastra

Lista pogrupowanych produktów wraz ze score podobieństwa do centroidu, uporządkowana malejąco. Kliknij ID produktu, aby otworzyć kartę bezpośrednio w nowym oknie.

## Zalecany workflow

Oto typowe użycie modułu w 4 krokach.

1. **Pierwszy audyt**: uruchom run TF-IDF na głównym języku, z domyślnymi parametrami. Przeanalizuj klastry oznaczone jako gap: czy są trafne redakcyjnie?
2. **Sortowanie**: dla każdego gapu użyj przycisku **Ignoruj**, jeśli klaster nie zasługuje na pillar page (na przykład przypadkowe grupowanie różnorodnych produktów). Pozostałe gapy to Twoje priorytety.
3. **Redakcja**: dla każdego zachowanego gapu utwórz nową stronę CMS w PrestaShop z tytułem, slugiem i meta ze szkicu. Użyj planu H2 jako szkieletu redakcyjnego. Kliknij **Oznacz jako Zrobione** po publikacji.
4. **Ponowny run**: po opublikowaniu nowych stron uruchom run ponownie. Dawne gapy powinny być teraz OK (moduł wykryje nowe pillar pages).

**Dobre praktyki SEO.** Wartościowa pillar page ma co najmniej 1500 słów, zawiera linki wewnętrzne do produktów klastra i naturalnie używa top-terminów w treści. Wygenerowany szkic to punkt wyjścia, nie finalny materiał.

## Eksport

Ze strony szczegółów runu dwa przyciski w prawym górnym rogu pozwalają na eksport:

- **CSV**: tabela z jednym wierszem per klaster, kolumny: id_cluster, label, n_members, spójność, pillar_gap, match_score, suggested_title, suggested_slug, suggested_meta, priority_score, target_keywords. Kodowanie UTF-8 z BOM (zgodne z Excelem).
- **JSON**: kompletny eksport zawierający listę produktów per klaster i pełny plan w markdown. Idealny do automatyzacji lub integracji zewnętrznej.

## Architektura techniczna

### Baza danych

Moduł tworzy 5 tabel z prefiksem `df_topicclusters_`:

- `run`: metadane każdego wykonania (tryb, język, status, czas trwania, liczniki)
- `cluster`: pojedyncze klastry (etykieta, top terminy w JSON, spójność, flaga pillar_gap, match_score)
- `cluster_product`: przynależność produkt do klastra ze score podobieństwa
- `pillar`: sugestie pillar pages (tytuł, slug, meta, plan, priorytet, status)
- `embedding_cache`: cache wektorów embeddingów indeksowany hashem tekstu

### PSR-4 i autoload

Namespace główny to DataFirefly ukośnik TopicClusters. Ręczny autoload jest rejestrowany przez `spl_autoload_register` w głównym pliku modułu, więc żadna zależność Composer nie jest wymagana.

### Kontrolery i zgodność PS 8 / PS 9

Moduł używa kontrolera legacy `ModuleAdminController` (a nie kontrolera Symfony), aby zagwarantować zgodność z obiema wersjami głównymi. Zapytania SQL są napisane z poszanowaniem schematów obu wersji, w szczególności usunięcia kolumny `meta_keywords` w PS 9.

## Wydajność i ograniczenia

- **Katalogi do 1000 produktów**: runy w kilka sekund. Brak szczególnych zastrzeżeń.
- **1000 do 10 000 produktów**: tryb TF-IDF pozostaje szybki (10-60 s). Tryb embeddingów: przewidzieć 1 do 5 minut na pierwszy run, natychmiastowo później dzięki cache.
- **Powyżej 10 000 produktów**: postaw na parametr **Limit produktów**, aby podzielić pracę, albo zwiększ `memory_limit` do 2 GB.

Złożoność k-means to O(n x k x iter x d), gdzie n to liczba produktów, k liczba klastrów, iter liczba iteracji (typowo 10-30), a d wymiar wektorów (zmienny w TF-IDF, 1536 w OpenAI).

## Rozwiązywanie problemów

### Nie wykryto żadnego klastra

Sprawdź, czy Twoje produkty mają treść tekstową w analizowanym języku (co najmniej nazwę i najlepiej opis). Jeśli `DFTC_MIN_DOC_FREQ` jest zbyt wysoki dla Twojego katalogu, obniż go do 1.

### Wszystkie klastry są oznaczone jako pillar gap

Próg `DFTC_PILLAR_MATCH_THRESHOLD` jest prawdopodobnie zbyt wysoki. Spróbuj 0.30 zamiast 0.45, jeśli Twój sklep ma mało stron CMS. Sprawdź też, czy strony CMS i kategorie są aktywne.

### Błąd „Unknown column meta_keywords"

Ten błąd pojawia się w PrestaShop 9 przy wcześniejszej wersji modułu. Zaktualizuj do wersji 1.0.0 lub wyższej, która usuwa wszelkie odwołania do `meta_keywords` (kolumna usunięta w PS 9).

### Błąd „Compile Error: Access level to processExport() must be public"

Ten błąd występował w wersji sprzed 1.0.0. Nazwa metody to obecnie `doExport()`, aby uniknąć kolizji z `AdminControllerCore`. Zaktualizuj moduł.

### Run kończy się błędem API

Sprawdź, czy klucz API wprowadzony w konfiguracji jest ważny i ma środki. Przetestuj przez `curl` w CLI, aby potwierdzić, że serwer może osiągnąć `api.openai.com` lub `api.mistral.ai`.

## Planowane rozwinięcia

- Bezpośrednie tworzenie stron CMS ze szkicu (jednym kliknięciem)
- Porównywanie runów (przed i po publikacji pillar pages)
- Graficzna wizualizacja sieci semantycznej między klastrami
- Obsługa embeddingów Cohere i Voyage AI
- Automatyczny cron do okresowych ponownych runów

**Wsparcie.** W razie pytań lub błędów skontaktuj się z [support@datafirefly.com](mailto:support@datafirefly.com). Zgłoszenia są cenne dla kierunku rozwoju roadmapy.