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

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.

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.

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

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

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