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 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ść)

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

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

API embeddingów

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.

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

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).

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