Audyt Semantyczny: dokumentacja

Instalacja

Wymagania

• PrestaShop 8.0 do 9.x
• PHP minimum 7.4 (zalecane 8.x)
• MySQL 5.7+ albo MariaDB 10.3+
• Klucz API OpenAI albo Mistral (opcjonalny, tryb lokalny bez API jest w zestawie)

Instalacja modułu

1. Rozpakuj plik dfsemanticaudit.zip pobrany ze swojego konta klienta.
2. Wgraj katalog dfsemanticaudit/ do /modules/ swojego PrestaShopa przez FTP albo skorzystaj z instalacji z pliku ZIP w Moduły > Menedżer modułów > Wgraj moduł.
3. Kliknij Zainstaluj.

Aktywacja modułu

Moduł automatycznie tworzy cztery tabele SQL (ps_dfsa_content, ps_dfsa_audit, ps_dfsa_cluster, ps_dfsa_assignment) oraz zakładkę administracyjną dostępną z menu po lewej stronie.

Konfiguracja

Przed pierwszym audytem przejdź do Moduły > DataFirefly > Audyt Semantyczny > Konfiguracja.

Wybór dostawcy embeddingów

Dostępnych jest trzech dostawców. Wybór decyduje o jakości uzyskanych klastrów.

OpenAI (zalecany)

Dostawca domyślny. Używa modelu text-embedding-3-small (1 536 wymiarów). Maksymalna jakość, koszt krańcowy: około 0,02 euro za 1 000 produktów przy pierwszej indeksacji.

• Klucz API: utwórz go na platform.openai.com/api-keys
• Model: zostaw domyślny text-embedding-3-small. text-embedding-3-large (3 072 wym.) daje nieco wyższą jakość, ale kosztuje 6 razy więcej.

Mistral

Europejska alternatywa hostowana we Francji. Używa mistral-embed (1 024 wymiary). Cennik porównywalny z OpenAI.

• Klucz API: utwórz go na console.mistral.ai
• Model: mistral-embed

Lokalny TF-IDF

Działa w całości na Twoim serwerze, bez wywołań API i bez kosztów cyklicznych. Wykorzystuje klasyczne zasady statystycznego przetwarzania języka (znormalizowany TF-IDF) przy wymiarze 384.

• Jakość wystarczająca dla katalogów poniżej 500 produktów.
• Obsługuje FR, EN, ES, DE, IT (wbudowane listy stopwords).
• Nie wymaga żadnego klucza API.

Parametry audytu

• k (liczba klastrów): domyślnie 8. Zakres od 2 do 50.
• Próg off-topic: odległość kosinusowa, od której treść jest sygnalizowana. Domyślnie 0,55. Zakres od 0,1 do 1,5.

Automatyczna reindeksacja

Włączona domyślnie. Moduł rejestruje hooki na tworzeniu, modyfikacji i usuwaniu produktów, kategorii i stron CMS. Przy każdej zmianie treść jest oznaczana do ponownego embeddingu przy następnym uruchomieniu, bez żadnej pracy ręcznej.

Uruchomienie pierwszego audytu

Trzy etapy do wykonania po kolei z poziomu pulpitu.

Etap 1: reindeksacja treści

Kliknij Reindeksuj treści. Moduł przechodzi przez Twoje produkty, aktywne kategorie, strony CMS i producentów, wylicza hash SHA1 tytułu i zajawki i oznacza do przetworzenia wyłącznie treści nowe albo zmodyfikowane.

Dla 1 000 treści ten etap trwa kilka sekund.

Etap 2: generowanie embeddingów

Kliknij Wygeneruj embeddingi. Moduł wysyła treści oznaczone jako „dirty” do wybranego dostawcy w partiach po 50 (OpenAI, Mistral) albo przetwarza je jednym przebiegiem lokalnie (TF-IDF). Pasek postępu pokazuje zaawansowanie.

Dla 1 000 treści:

• OpenAI: około 30 sekund
• Mistral: około 40 sekund
• Lokalny TF-IDF: poniżej 1 sekundy

Etap 3: uruchomienie audytu

Kliknij Uruchom audyt. Klastrowanie k-means kosinus grupuje treści w k klastrów (inicjalizacja k-means++, maksymalnie 50 iteracji), etykietuje każdy klaster jego najważniejszymi terminami (TF×IDF), wylicza odległość każdej treści do jej centroidu i identyfikuje outliery.

Ten etap zajmuje mniej niż sekundę, nawet przy 5 000 treści.

Zrozumieć raport

Pulpit

Cztery kluczowe KPI u góry:

• Zindeksowane treści: łączna liczba produktów, kategorii, stron CMS i producentów zamienionych na wektory.
• Strony off-topic: liczba bezwzględna, odsetek i podział według typu.
• Klastry tematyczne: liczba zidentyfikowanych grup tematycznych.
• Mediana odległości: mediana odległości kosinusowej do centroidu. Poniżej 0,40 katalog jest bardzo spójny. Powyżej 0,60 katalog jest rozproszony.

Klastry

Widok Klastry: szczegółowa lista posortowana według wielkości, z automatyczną etykietą (5 najważniejszych terminów TF×IDF), score spójności (0 rozproszony, 1 identyczny) i wielkością (liczba treści).

Klaster o spójności poniżej 0,40 jest zbyt niejednorodny. To zwykle sygnał, że temat należałoby rozbić na dwa podtematy albo że k jest zbyt niskie.

Semantyczna mapa 2D

Projekcja wszystkich treści na płaszczyznę techniką Johnsona-Lindenstraussa (projekcja losowa, która w przybliżeniu zachowuje odległości).

Każdy punkt to treść, każdy kolor to klaster. Krzyżyki oznaczają centroidy. Punkty z czerwonym obrysem to treści off-topic. Legenda po prawej pozwala ukrywać i pokazywać poszczególne klastry po kliknięciu.

Strony off-topic

Widok Strony off-topic: sortowalna tabela treści, których odległość kosinusowa do centroidu przekracza skonfigurowany próg. Dla każdego wiersza:

• Typ, tytuł, publiczny adres i bezpośredni link do karty edycji
• Bieżący klaster (wraz z jego kolorem)
• Odległość do centroidu (im wyższa, tym treść jest bardziej oddalona)
• Sugerowany klaster (jeśli istotny)
• Δ Zysk: redukcja odległości, gdyby treść została przeniesiona

Strony nie do odzyskania

Na dole widoku off-topic osobna sekcja wymienia treści oddalone od wszystkich klastrów. Moduł nie znalazł dla nich sensownego miejsca docelowego.

Trzy działania do rozważenia:

1. Usuń, jeśli strona nie ma ruchu SEO ani konwersji.
2. Ustaw noindex, aby chronić budżet crawl bez utraty historii.
3. Przepisz, aby dopasować treść do istniejącego klastra.

Sugestie restrukturyzacji

Widok Sugestie: odpowiednik widoku Strony off-topic, ale nastawiony na działanie. Wszystkie proponowane przeniesienia są wypisane wraz z oczekiwanym zyskiem spójności. Posortuj malejąco po zysku, aby najpierw zająć się przypadkami o największym wpływie.

Moduł nigdy nie modyfikuje Twojego drzewa kategorii automatycznie. Zmiany pozostają pod Twoją kontrolą, w standardowym zapleczu PrestaShop.

Eksport CSV

W każdym widoku raportu przycisk Eksportuj CSV pozwala pobrać surowe dane. Przydatne, aby:

• Podzielić się raportem z zewnętrznym konsultantem SEO
• Przetworzyć dane w Excelu albo Arkuszach Google
• Zarchiwizować stan audytu przed zmianą drzewa kategorii

Automatyzacja przez cron

Moduł udostępnia podpisany adres wyświetlany na stronie konfiguracji. Uruchamia on w trybie headless pełną sekwencję indeksacja, embeddingi, audyt.

Przykład cotygodniowego zadania cron (w każdy poniedziałek o 3):

0 3 * * 1 wget -q -O /dev/null "https://twoj-sklep.pl/modules/dfsemanticaudit/cron.php?token=TWOJ_TOKEN"

Token jest wyprowadzony z _COOKIE_KEY_ Twojego PrestaShopa i zmienia się wyłącznie przy ponownej instalacji. Zanotuj go starannie.

Koszty API

Szacunek dla średniego katalogu (1 000 produktów):

• OpenAI text-embedding-3-small: około 0,02 euro za pierwszym razem, potem niemal zero (przetwarzane są tylko zmodyfikowane treści)
• OpenAI text-embedding-3-large: około 0,13 euro za pierwszym razem
• Mistral mistral-embed: około 0,10 euro za pierwszym razem
• Lokalny TF-IDF: 0 euro

Wielojęzyczność i multisklep

Moduł jest natywnie wielojęzyczny i wielosklepowy. Każdy audyt wykonuje się na zadanej parze język × sklep, wykorzystując język kontekstu zaplecza.

Aby zaudytować sklep najpierw po polsku, a potem po angielsku, zmień język w górnym pasku PrestaShopa i uruchom nowy audyt.

Rozwiązywanie problemów

Etap „Wygeneruj embeddingi” kończy się błędem 401

Twój klucz API jest nieprawidłowy albo wygasł. Sprawdź go na stronie konfiguracji i w razie potrzeby skonfiguruj ponownie.

Etap „Wygeneruj embeddingi” kończy się błędem 429

Osiągnąłeś limit przepustowości swojego dostawcy. Odczekaj kilka minut i uruchom ponownie: moduł podejmie pracę od miejsca zatrzymania dzięki przetwarzaniu partiami.

Żaden klaster nie wydaje się trafny

Trzy tropy:

1. Zwiększ liczbę klastrów (k). Jeśli Twój katalog ma 10 odrębnych tematyk, a k=4, klastrowanie nie będzie w stanie ich rozdzielić.
2. Przejdź z lokalnego trybu TF-IDF na OpenAI albo Mistral. Przy niejednorodnych katalogach jakość semantyczna robi całą różnicę.
3. Sprawdź, czy tytuły i opisy Twoich treści są wystarczająco bogate. Produkt z dwuwyrazowym tytułem i bez opisu nie da dobrego embeddingu.

Zbyt wiele stron oznaczonych jako off-topic

Podnieś próg off-topic (na przykład z 0,55 na 0,70). To normalne, jeśli Twój katalog zasadnie obejmuje kilka szerokich tematyk.

Żadna strona nie jest oznaczona jako off-topic, a katalog wydaje się niespójny

Obniż próg (na przykład z 0,55 na 0,40), aby zacieśnić wykrywanie.

FAQ

Czy klucz API jest obowiązkowy?

Nie. Lokalny tryb TF-IDF działa bez żadnego połączenia zewnętrznego. Jest nieco mniej precyzyjny niż OpenAI i Mistral, ale wystarcza na start albo dla jednorodnego katalogu.

Czy moduł automatycznie modyfikuje moje drzewo kategorii?

Nie. Moduł jedynie rekomenduje. Wszystkie przeniesienia treści pozostają po Twojej stronie, w standardowym zapleczu PrestaShop.

Jak wybrać liczbę klastrów (k)?

Zasada praktyczna: k w przybliżeniu równe liczbie głównych kategorii pierwszego poziomu. Domyślne k=8 sprawdza się dobrze między 100 a 5 000 produktów. Jeśli się wahasz, uruchom 2 albo 3 audyty z różnymi wartościami k i porównaj: wcześniejsze audyty pozostają w historii.

Czy moje wektory są wysyłane na serwer zewnętrzny?

Przy OpenAI albo Mistralu tak: tytuły i zajawki Twoich treści są wysyłane do ich API embeddingów. W trybie lokalnym TF-IDF nie: żadne dane nie opuszczają Twojego serwera.

Jak długo przechowywane są audyty?

Bezterminowo, aż do ręcznego usunięcia z poziomu pulpitu. Możesz przeglądać pełną historię, aby mierzyć ewolucję spójności semantycznej w czasie.

Czy moduł działa w trybie multisklep?

Tak. Każdy sklep w multistore może mieć własne, niezależne audyty.