# Semantyczne Linkowanie Wewnętrzne AI: pełny przewodnik
> Prezentacja DataFirefly Semantyczne Linkowanie Wewnętrzne AI (dfaisemanticlinks) buduje sieć linków wewnętrznych Twojego sklepu PrestaShop na podstawie wektorów embeddingów. Każdy produkt, kategoria i strona CMS jest zamieniana na wektor przez dostawcę…
- Strona:
- Język: pl
- Zaktualizowano: 2026-08-01
- Inne języki: [fr](https://www.datafirefly.com/documentation/dfaisemanticlinks/index.md), [en](https://www.datafirefly.com/en/documentation/dfaisemanticlinks/index.md), [es](https://www.datafirefly.com/es/documentation/dfaisemanticlinks/index.md), [de](https://www.datafirefly.com/de/documentation/dfaisemanticlinks/index.md), [it](https://www.datafirefly.com/it/documentation/dfaisemanticlinks/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfaisemanticlinks/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfaisemanticlinks/index.md)
- Indeks:
## Prezentacja
DataFirefly Semantyczne Linkowanie Wewnętrzne AI (`dfaisemanticlinks`) buduje sieć linków wewnętrznych Twojego sklepu PrestaShop na podstawie **wektorów embeddingów**. Każdy produkt, kategoria i strona CMS jest zamieniana na wektor przez dostawcę AI (Mistral albo OpenAI), wektory są porównywane **podobieństwem kosinusowym**, a moduł proponuje linki kontekstowe z **kotwicami wyciągniętymi dosłownie** z tekstu źródłowego. Sugestie zatwierdzasz pojedynczo albo masowo, a każdy wstawiony link można chirurgicznie wycofać dzięki unikalnemu znacznikowi `data-dfasl`.
Moduł nie wykonuje żadnych wywołań AI na front office: podobieństwa są prekalkulowane, a zatwierdzone linki zapisywane bezpośrednio w opisach. Wpływ na wydajność: zerowy.
## Wymagania
- PrestaShop 8.0 do 9.x (PrestaShop 1.7 nie jest wspierany)
- PHP 8.1, 8.2 albo 8.3
- MySQL 5.7+ / MariaDB 10.3+
- Klucz API **Mistral** (console.mistral.ai) albo **OpenAI** (platform.openai.com)
- Dostęp do CLI zalecany dla katalogów powyżej 1000 encji (cron)
## Instalacja
1. Back office: **Moduły, Menedżer modułów, Zainstaluj moduł**.
2. Wgraj plik `dfaisemanticlinks.zip`, a następnie kliknij **Zainstaluj**.
3. Moduł tworzy 5 tabel z prefiksem `dfasl_` (embedding, queue, suggestion, inserted_link, job) oraz menu **Linkowanie AI** z 4 zakładkami: Pulpit, Sugestie, Wstawione linki, Ustawienia.
Deinstalacja czysto usuwa 5 tabel i wszystkie zmienne konfiguracyjne `DFASL_*`. Wyeksportuj dane wcześniej, jeśli chcesz je zachować.
## Konfiguracja
### 1. Dostawca embeddingów
Zakładka **Ustawienia**, pierwszy blok:
- **Dostawca**: Mistral (mistral-embed, 1024 wymiary, domyślny, hosting w UE) albo OpenAI (text-embedding-3-small, 1536 wymiarów).
- **Klucz API**: wklej klucz wybranego dostawcy.
- **Testuj połączenie**: przycisk wysyła ciąg testowy i wyświetla otrzymaną liczbę wymiarów. Zawsze weryfikuj klucz w tym miejscu przed uruchomieniem indeksacji.
Jeśli zmienisz dostawcę po indeksacji, zmieni się liczba wymiarów wektorowych (1024 wobec 1536). Moduł zaproponuje ponowne **Reindeksuj wszystko**: stare wektory zostaną nadpisane, ale już wstawione linki pozostaną na miejscu.
### 2. Indeksacja
- **Indeksowane typy**: produkty, kategorie, strony CMS, każdy włączany niezależnie.
- **Minimalna długość** (domyślnie 200 znaków): treści zbyt krótkie po oczyszczeniu HTML są pomijane.
- **Rozmiar partii** (domyślnie 20): liczba pozycji wysyłanych w jednym zapytaniu API. Jedno wywołanie embeddingu na partię.
- **Autoreindeksacja** (domyślnie włączona): każda modyfikacja produktu, kategorii albo CMS odkłada encję do kolejki przez hooki. Wyłącz ją tymczasowo na czas masowego importu CSV.
### 3. Sugestie i wstawianie
- **Próg podobieństwa** (domyślnie 0,78): pary poniżej progu są pomijane. Zejdź do 0,72 po więcej sugestii, podnieś do 0,82 po większą restrykcyjność.
- **Maksymalna liczba linków na stronę** (domyślnie 5): zabezpieczenie przed nadoptymalizacją SEO.
- **Strategia kotwiczenia**: zoptymalizowane n-gramy (domyślnie) albo surowy tytuł celu.
## Pierwsza indeksacja
1. Zakładka **Pulpit**, przycisk **Reindeksuj wszystko**: wszystkie aktywne encje włączonych typów trafiają do kolejki, we wszystkich aktywnych językach.
2. Kliknij **Przetwórz partię** tyle razy, ile potrzeba (małe katalogi), albo uruchom workera CLI (patrz niżej).
3. Każda partia: wyciągnięcie i oczyszczenie tekstu, zbiorcze wywołanie embeddingu, zapis wektora, a następnie wyliczenie sugestii podobieństwem kosinusowym.
Pulpit wyświetla na bieżąco: encje łącznie, aktywne embeddingi, sugestie oczekujące, aktywne linki oraz statusy kolejki (Oczekujące, W trakcie, Zakończone, Błąd).
Koszt orientacyjny: 1000 produktów w 3 językach to około 1,5 miliona tokenów, czyli 0,15 euro (Mistral) albo 0,03 dolara (OpenAI). Dzięki wykrywaniu przez hash SHA-256 kolejne reindeksacje obejmują wyłącznie treści rzeczywiście zmienione.
## Zatwierdzanie sugestii
Zakładka **Sugestie**: paginowana tabela zawierająca w każdym wierszu źródło, cel, wynik podobieństwa, proponowaną kotwicę, fragment kontekstu oraz przyciski **Wstaw** i **Odrzuć**.
### Wybór kotwicy
Generator kotwic wyciąga z tytułu docelowego n-gramy (od 2 do 6 słów) występujące dosłownie w treści źródłowej i sortuje je od najdłuższego do najkrótszego. Lista rozwijana pokazuje wszystkich kandydatów, a opcja **Dostosuj** otwiera dowolne pole tekstowe. Domyślna kotwica to najdłuższy znaleziony n-gram, zwykle 3 albo 4 słowa zawierające główne słowa kluczowe celu.
### Wstawianie
Przy wstawianiu moduł podlinkowuje pierwsze wystąpienie kotwicy, które nie znajduje się już w znaczniku `a`, `code` albo `pre` (wzorce PCRE SKIP i FAIL). Jeśli żadne wolne wystąpienie nie istnieje, na końcu opisu dodawany jest akapit awaryjny z klasą `dfasl-related`. Każdy link otrzymuje atrybut `data-dfasl` z unikalnym 36-znakowym identyfikatorem.
### Akcje masowe
Zaznacz kilka wierszy (pole w nagłówku kolumny zaznacza wszystkie), a następnie użyj **Wstaw zaznaczone** albo **Odrzuć zaznaczone**. Paginacja po 50 wierszy.
## Wycofanie linku (rollback)
Zakładka **Wstawione linki**: paginowana lista aktywnych linków ze źródłem, celem, kotwicą, datą i pracownikiem. Przycisk **Usuń** kasuje wyłącznie znacznik `a data-dfasl` z danym identyfikatorem: tekst kotwicy pozostaje nietknięty, żaden inny element HTML nie jest ruszany, a link zostaje oznaczony jako usunięty w bazie.
## Worker CLI i cron
Przy dużych katalogach użyj workera z linii poleceń:
```
php modules/dfaisemanticlinks/bin/analyze.php [opcje]
```
- `--shop=N`: wskazuje konkretny sklep (multistore).
- `--enqueue-all`: ponownie kolejkuje wszystkie aktywne encje przed przetwarzaniem.
- `--loop`: pętla, dopóki zostają pozycje oczekujące.
- `--max-batches=N`: ogranicza liczbę partii na jedno uruchomienie (zabezpieczenie przed niekontrolowanym działaniem).
- `--sleep=N`: przerwa w sekundach między partiami (limity API).
Zalecany cron co 15 minut:
```
*/15 * * * * php /sciezka/do/prestashop/modules/dfaisemanticlinks/bin/analyze.php --loop --max-batches=50 --sleep=1
```
Worker automatycznie resetuje wpisy zablokowane w statusie „W trakcie" od ponad 30 minut (padnięcie poprzedniego uruchomienia), oznacza pozycje nieudane komunikatem błędu API i kontynuuje przetwarzanie reszty partii.
## Autoreindeksacja
Hooki `actionObjectProductUpdateAfter`, `actionObjectCategoryUpdateAfter` i `actionObjectCmsUpdateAfter` odkładają zmodyfikowaną encję do kolejki we wszystkich aktywnych językach. Hooki usuwania czyszczą embeddingi i sugestie kaskadowo. Hash treści SHA-256 eliminuje wywołanie API, jeśli rzeczywisty tekst się nie zmienił (na przykład przy zwykłej modyfikacji stanu magazynowego).
## Multistore i wielojęzyczność
Embeddingi są zakresowane per trójka: encja, język i sklep. Sugestie nigdy nie przekraczają granic językowych ani granic sklepów. Konfiguracja (klucz API, próg, indeksowane typy) może się różnić per sklep przez standardowy selektor kontekstu multistore PrestaShop.
## Rozwiązywanie problemów
### „Klucz API nie jest skonfigurowany" albo błąd przy teście połączenia
Sprawdź, czy klucz odpowiada dostawcy wybranemu na liście rozwijanej (klucz Mistrala nie zadziała z dostawcą OpenAI i odwrotnie) i czy ma dostępne środki. Szczegółowe błędy API są zapisywane w **Ustawienia zaawansowane, Logi** (PrestaShopLogger).
### Pozycje pozostają w statusie „W trakcie"
Worker został prawdopodobnie przerwany. Odczekaj 30 minut (automatyczny reset) albo kliknij **Wyczyść kolejkę** i uruchom ponownie **Reindeksuj wszystko**.
### Mało sugestii albo brak sugestii
Trzy częste przyczyny: zbyt wysoki próg podobieństwa (spróbuj 0,72), zbyt krótkie treści (poniżej minimalnej długości) albo katalog zbyt jednorodny lub zbyt niejednorodny. Sprawdź też, czy pożądane typy encji są włączone w Ustawieniach.
### Proponowana kotwica to surowy tytuł celu
To tryb awaryjny: żaden n-gram tytułu docelowego nie występuje dosłownie w treści źródłowej. Wybierz kotwicę własną albo wzbogać opis źródłowy.
## Architektura techniczna
- PHP 8.1+ ze ścisłymi typami, PSR-4 pod namespace DataFirefly ukośnik AiSemanticLinks mapowanym na katalog `src/`
- Kontrolery admina w legacy `ModuleAdminController` (stabilna zgodność PS8 i PS9)
- Własny mini kontener usług (niezależny od kontenera Symfony)
- Wektory jako BLOB float32 pakowany little-endian plus prekalkulowana norma L2
- 5 tabel: `dfasl_embedding`, `dfasl_queue`, `dfasl_suggestion`, `dfasl_inserted_link`, `dfasl_job`
- Kod źródłowy niezaszyfrowany, gotowy do nadpisania