Wszystko, co warto wiedzieć, zanim zainstalujesz.
Szczegółowe spojrzenie na to, jak działa DataFirefly Semantyczne Linkowanie Wewnętrzne AI: wektory embeddingów, podobieństwo kosinusowe i półautomatyczne wstawianie z inteligentnymi kotwicami dla PrestaShop 8 i 9 (Mistral, OpenAI), dlaczego zbudowaliśmy go w ten sposób i jaka myśl stoi za powyższymi funkcjami.
Dlaczego linkowanie semantyczne bije linkowanie po słowach kluczowych
Klasyczne moduły linkowania wewnętrznego działają na regułach: słowo kluczowe prowadzi do adresu URL. Wpisujesz dywan berberyjski i przypisujesz adres kategorii dywany-berberyjskie. Silnik robi potem znajdź i zamień w kodzie HTML Twoich artykułów, produktów albo stron. To podejście ma dwa poważne ograniczenia. Jest sztywne: uruchamia link tylko wtedy, gdy pojawia się dokładne słowo kluczowe, co wyklucza wszystkie strony, gdzie temat jest opisany inaczej (dywan marokański, kilim, dywan tradycyjny). I jest ślepe na kontekst semantyczny: silnik nie wie, czy strona docelowa jest naprawdę trafna dla treści źródłowej, robi po prostu dopasowanie ciągu znaków. Linkowanie semantyczne działa inaczej: każda treść jest reprezentowana przez wektor o setkach wymiarów, który koduje jej znaczenie, czy to produkt, kategoria, strona CMS czy blog. Dwie treści są łączone, jeśli są blisko siebie w tej przestrzeni wektorowej, niezależnie od użytych słów. Moduł wychwytuje w ten sposób okazje do linkowania, których silnik oparty na słowach kluczowych nigdy by nie zobaczył, i unika fałszywych trafień, gdzie słowo kluczowe pojawia się w nietrafnym kontekście.
Embeddingi AI: jak to działa w praktyce
Przy pierwszej indeksacji moduł przechodzi przez wszystkie aktywne encje Twojego sklepu dla włączonych typów (produkty, kategorie, strony CMS). Dla każdej encji treść tekstowa jest wyciągana i czyszczona: tytuł, meta_title, meta_description, opis skrócony i opis długi (HTML jest usuwany czysto). Oczyszczony tekst jest następnie wysyłany partiami do skonfigurowanego dostawcy AI (Mistral albo OpenAI), który zwraca po jednym wektorze embeddingu na pozycję, czyli listę liczb zmiennoprzecinkowych reprezentującą semantykę tekstu. Wektor jest zapisywany w bazie jako BLOB float32 pakowany little-endian, wraz z prekalkulowaną normą L2, aby przyśpieszyć późniejsze obliczenia podobieństwa. Podobieństwo między dwiema treściami jest potem liczone w PHP przez znormalizowany iloczyn skalarny (podobieństwo kosinusowe), operację wyjątkowo szybką po prekalkulacji norm. Na katalogu 5000 encji pełne wyliczenie wszystkich par w jednym języku zajmuje zaledwie kilka sekund.
Dlaczego dwaj dostawcy, a nie jeden
Każdy dostawca ma swoje mocne strony. Mistral mistral-embed to domyślna, rekomendowana opcja: 1024 wymiary, bardzo niskie opóźnienie, hosting w Europie (suwerenność UE dla sklepów wrażliwych na ten aspekt), koszt około 10 centów za milion tokenów, czyli mniej niż jedno euro za indeksację katalogu liczącego kilka tysięcy wielojęzycznych encji. OpenAI text-embedding-3-small to alternatywa: 1536 wymiarów (bogatsza przestrzeń wektorowa), świetne wyniki na językach spoza Europy Zachodniej, koszt około 2 centów za milion tokenów. Moduł ujednolica obu dostawców za wspólnym interfejsem: ten sam format zwrotu, ten sam mechanizm partii, ta sama obsługa błędów przez PrestaShopLogger. Dostawcę możesz zmienić listą rozwijaną w konfiguracji, a moduł wykryje zmianę liczby wymiarów i zaproponuje reindeksację (jedno kliknięcie w Reindeksuj wszystko).
Generator kotwic, prawdziwe serce modułu
To punkt, który odróżnia ten moduł od zwykłego generatora surowych sugestii. Dla każdej pary źródło i cel powyżej progu podobieństwa generator kotwic stosuje następujący algorytm: wyciąga tytuł celu, dzieli go na n-gramy od 2 do 6 słów, usuwa stopwordy (francuskie i angielskie), a następnie szuka każdego z tych n-gramów dosłownie w treści źródła. Znalezione n-gramy są sortowane malejąco po długości (dłuższe są bardziej rozróżniające i lepiej zoptymalizowane pod SEO) i prezentowane na liście rozwijanej w back office. Domyślnie wybrana kotwica to najdłuższa znaleziona, co daje zwykle kotwicę 3- albo 4-wyrazową zawierającą główne słowa kluczowe tytułu docelowego. Jeśli żaden n-gram tytułu docelowego nie występuje w źródle, moduł proponuje surowy tytuł celu (tryb awaryjny). Oczywiście zachowujesz kontrolę: edytowalna lista rozwijana i opcja Dostosuj do wpisania dowolnego tekstu kotwicy. W momencie wstawiania moduł wybiera pierwsze wystąpienie tekstu kotwicy w treści źródła, które nie znajduje się już w znaczniku a, code albo pre, więc nie ma ryzyka uszkodzenia istniejącego linku ani ponownego podlinkowania tekstu już podlinkowanego.
Chirurgiczne wycofanie przez unikalny znacznik
To funkcja, która uspokaja każdego sprzedawcę ostrożnego wobec swoich opisów. Każdy wstawiony link otrzymuje atrybut HTML data-dfasl z unikalnym 36-znakowym identyfikatorem generowanym losowo przy wstawianiu (format typu UUID). Identyfikator jest też zapisywany w bazie w tabeli dfasl_inserted_link, wraz z encją źródłową, celem, kotwicą, datą wstawienia i identyfikatorem pracownika, który zatwierdził. Aby usunąć link, wchodzisz w zakładkę Wstawione linki i klikasz Usuń obok danego wiersza: moduł wykonuje wyrażenie regularne dopasowujące dokładnie wzorzec kotwicy w znaczniku a z atrybutem data-dfasl i tym unikalnym identyfikatorem, usuwa znacznik a, zachowując tekst kotwicy nietknięty, i oznacza link jako usunięty w bazie. Żaden inny znacznik opisu nie jest ruszany, żaden ręczny link nie jest zagrożony. Spośród 500 linków wstawionych przez moduł w 200 kartach produktów możesz usunąć jeden jednym kliknięciem, nie ruszając pozostałych 499.
Worker CLI i strategia przetwarzania dużych katalogów
Przy katalogu liczącym kilkadziesiąt produktów wszystko można zrobić z back office: Reindeksuj wszystko, a potem Przetwórz partię wystarcza. Powyżej kilku tysięcy encji interfejs staje się powolny, a użytkownik nie ma ochoty trzymać otwartej przeglądarki przez godziny. Moduł udostępnia workera CLI (bin/analyze.php), który uruchamiasz z linii poleceń PHP z czterema opcjami. Opcja shop wskazuje konkretny sklep w środowisku multistore. Opcja enqueue-all ponownie kolejkuje wszystkie aktywne encje przed przetwarzaniem, co jest przydatne przy pełnej reindeksacji po zmianie dostawcy albo modelu. Opcja loop kontynuuje pętlę, dopóki zostają pozycje do przetworzenia. Opcja max-batches ogranicza liczbę partii przetworzonych w jednym uruchomieniu (zabezpieczenie przed niekontrolowanym działaniem). Opcja sleep wstawia przerwę między partiami (przydatne, aby pozostać poniżej limitów API). Typowe polecenie dla crona co 15 minut uruchamia skrypt z opcjami loop, max-batches ustawionym na 50 i sleep ustawionym na 1. Worker automatycznie resetuje wpisy zablokowane w statusie W trakcie od ponad 30 minut (przypadek, gdy poprzedni worker padł), obsługuje błędy API, oznaczając dane pozycje statusem Błąd wraz z komunikatem, i kontynuuje przetwarzanie zdrowych pozycji z partii.
Autoreindeksacja i świeżość indeksu
Indeks, który rozjechał się z katalogiem, nie ma żadnej wartości. Moduł zarządza świeżością przez natywne hooki PrestaShop. Przy każdej modyfikacji produktu, kategorii albo strony CMS (hooki actionObjectProductUpdateAfter, actionObjectCategoryUpdateAfter, actionObjectCmsUpdateAfter) dana encja wraca do kolejki ze statusem Oczekujące, we wszystkich aktywnych językach, a kolejny worker przetworzy ją automatycznie. Przy usunięciu (hooki actionObjectProductDeleteAfter, actionObjectCategoryDeleteAfter, actionObjectCmsDeleteAfter) embeddingi i powiązane sugestie są czyszczone kaskadowo. Moduł zawiera też hash treści (SHA-256 oczyszczonego tekstu): jeśli encja wraca do kolejki, choć jej rzeczywista treść się nie zmieniła (na przykład dlatego, że pracownik ruszył tylko stan magazynowy), partia indeksacyjna wykrywa niezmieniony hash i pomija wywołanie API, oszczędzając tokeny. Autoreindeksacja jest przełączalna w Ustawieniach (opcja DFASL_AUTO_INDEX), co przydaje się do jej wstrzymania na czas masowego importu CSV i wznowienia po zakończeniu importu przyciskiem Reindeksuj wszystko.
Natywny multistore i wielojęzyczność
Moduł jest natywnie multistore i wielojęzyczny. Embeddingi są zakresowane per trójka: encja, język i sklep. Ten sam produkt w dwóch sklepach będzie miał dwa niezależne embeddingi, jeśli opisy się różnią, a ten sam produkt po polsku i po angielsku będzie miał dwa różne embeddingi, choć karta jest ta sama. Sugestie nigdy nie przekraczają granic językowych: produkt polski nigdy nie dostanie sugestii linku do produktu angielskiego (co nie miałoby żadnego sensu w SEO). Granice sklepów są respektowane tak samo. Konfiguracja może się różnić per sklep (klucz API, próg podobieństwa, indeksowane typy, hook wyświetlania), co jest przydatne, gdy masz sklep B2B z treścią techniczną i sklep B2C z treścią dla szerokiego odbiorcy w tej samej infrastrukturze.
Typowe zastosowania
Wielojęzyczny sklep modowy z katalogiem 2000 produktów: linkowanie semantyczne wychwytuje pary produktów bliskich wizualnie albo stylistycznie (na przykład dwie wariacje kroju sukienki), które reguły oparte na słowach kluczowych systematycznie by pomijały. Sklep B2B techniczny z gęstymi opisami: linkowanie semantyczne łączy produkty dzielące ten sam przypadek użycia przemysłowego, nawet gdy słownictwo nie jest identyczne. Blog e-commerce: każdy artykuł może automatycznie odsyłać do najbardziej trafnych znaczeniowo produktów, kategorii i innych artykułów, z kotwicami wyciągniętymi dosłownie z tekstu artykułu (przeciwieństwo mechanicznego znajdź i zamień). Przebudowa katalogu: po masowym imporcie albo reorganizacji jedno Reindeksuj wszystko odbudowuje sieć linków w kilka minut tam, gdzie strategia ręczna zajęłaby tygodnie pracy redakcyjnej. Katalog o silnie specjalistycznym słownictwie (kosmetyki organiczne, sprzęt medyczny, produkty techniczne): moduł wykrywa bliskie związki znaczeniowe, których osoby spoza branży by nie zauważyły, i pozwala zespołowi SEO odkryć nieoczywiste okazje do linkowania.
Architektura wewnętrzna i zgodność z PrestaShop 8 i 9
Moduł jest zbudowany w PHP 8.1+ ze ścisłymi typami, klasami readonly i nowoczesnymi funkcjami (match, enumy). Autoload jest w PSR-4 pod namespace DataFirefly AiSemanticLinks mapowanym na katalog src. Kontrolery admina są w legacy ModuleAdminController (nie w siatkach Symfony), co jest świadomym wyborem gwarantującym stabilną zgodność między PrestaShop 8.0 a 9.x bez utrzymywania dwóch wariantów kodu. Własny mini kontener usług (ServiceContainer) spina repozytoria i usługi biznesowe, co izoluje moduł od różnic w kontenerze Symfony między wersjami PrestaShop i eliminuje zależność, która psułaby się przy każdej dużej aktualizacji. Pięć tabel SQL z prefiksem dfasl_: embedding (wektory i hashe), queue (kolejka pracy), suggestion (proponowane pary), inserted_link (aktywne linki), job (operacje masowe). Deinstalacja czysto usuwa 5 tabel i czyści wszystkie zmienne konfiguracyjne DFASL. Kod źródłowy jest dostarczany niezaszyfrowany i zgodny z PSR, więc możesz go nadpisać, audytować albo rozszerzyć według uznania.
Na razie nie ma opinii o produkcie.