# 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…
- Strona:
- Język: pl
- Zaktualizowano: 2026-08-01
- Inne języki: [fr](https://www.datafirefly.com/documentation/dfsemanticaudit/index.md), [en](https://www.datafirefly.com/en/documentation/dfsemanticaudit/index.md), [es](https://www.datafirefly.com/es/documentation/dfsemanticaudit/index.md), [de](https://www.datafirefly.com/de/documentation/dfsemanticaudit/index.md), [it](https://www.datafirefly.com/it/documentation/dfsemanticaudit/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfsemanticaudit/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfsemanticaudit/index.md)
- Indeks:
## 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](https://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](https://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.
**Wskazówka**: Dostawcę możesz zmienić w dowolnym momencie. Przy następnym audycie wszystkie treści zostaną automatycznie ponownie zamienione na wektory.
### 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.
**Szybki odczyt**: Jeśli widzisz punkty w danym kolorze zagubione bardzo daleko od swojego centroidu, są to priorytetowi kandydaci do przeniesienia.
### 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.
**Uwaga**: Moduł respektuje oryginalny język każdej treści, bez prób automatycznego tłumaczenia. Uzyskane klastry będą inne dla każdego języka, co jest normalne.
## 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.