Wyszukiwanie Semantyczne AI dla PrestaShop

Ten moduł dodaje do Twojego sklepu PrestaShop wyszukiwanie semantyczne oparte na sztucznej inteligencji: autouzupełnianie, strona wyników wyszukiwania, blok „Może Ci się także spodobać” na karcie produktu i panel analityczny dzielą ten sam ranking według znaczenia, obliczany za pomocą embeddingów wektorowych.

Wymagania

• PrestaShop od 8.0 do 9.x
• PHP od 7.4 do 8.3 z włączonym rozszerzeniem cURL
• Klucz API dostawcy embeddingów: OpenAI, Mistral AI lub dowolna brama zgodna z OpenAI

Instalacja

1. W panelu administracyjnym otwórz Moduły > Menedżer modułów.
2. Kliknij Prześlij moduł i wgraj plik ZIP.
3. Po instalacji kliknij Konfiguruj.

Moduł tworzy cztery tabele (dfvectorsearch_index, dfvectorsearch_qcache, dfvectorsearch_log, dfvectorsearch_similar) oraz ukrytą zakładkę dla swoich wywołań AJAX. W sklepie nic nie jest widoczne, dopóki indeks nie zostanie zbudowany.

Konfiguracja dostawcy embeddingów

W zakładce Ustawienia wybierz dostawcę i wprowadź swój klucz API.

OpenAI

Wybierz dostawcę OpenAI i wprowadź swój klucz. Zalecany model to text-embedding-3-small (dobry stosunek jakości do ceny). Dla maksymalnej precyzji na wymagającym katalogu możesz użyć text-embedding-3-large.

Mistral AI (hosting europejski)

Wybierz Mistral AI dla przetwarzania danych w Europie, zgodnego z RODO. Model do użycia to mistral-embed.

Brama zgodna z OpenAI

Wybierz Custom, aby użyć własnej bramy (wewnętrzny proxy, Azure OpenAI itp.). Wprowadź wtedy bazowy adres URL API, na przykład https://moja-brama.przyklad.com/v1.

Klucz API jest maskowany po zapisaniu. Pozostaw zamaskowaną wartość bez zmian, aby zachować istniejący klucz; wprowadź nowy klucz tylko wtedy, gdy chcesz go zastąpić.

Wymiary

Pole Wymiary pozwala zmniejszyć rozmiar wektorów, aby przyspieszyć wyszukiwanie w bardzo dużych katalogach. Pozostaw 0, aby użyć domyślnego rozmiaru modelu. Modele OpenAI text-embedding-3 obsługują zmniejszone wymiary (na przykład 512).

Zmiana dostawcy, modelu lub liczby wymiarów czyni cały indeks nieaktualnym: przy zapisie indeks jest automatycznie oznaczany do pełnej odbudowy, a pamięć podręczna zapytań jest czyszczona. Następnie uruchom ponownie indeksowanie.

Budowanie indeksu

Po zapisaniu klucza API przejdź do ramki Indeks embeddingów na górze strony konfiguracji.

1. Kliknij Indeksuj teraz. Moduł przetwarza produkty partiami z paskiem postępu, język po języku i sklep po sklepie.
2. Pozostaw stronę otwartą, aż status pokaże Indeks aktualny.

Rozmiar partii

Ustawienie Rozmiar partii indeksowania kontroluje, ile produktów jest przetwarzanych na wywołanie (od 5 do 100). Zmniejsz je, jeśli serwer napotyka przekroczenia limitu czasu.

Indeksowanie planowane (cron)

Aby indeks był automatycznie synchronizowany z katalogiem, skopiuj Adres URL indeksowania cron wyświetlany w konfiguracji i wywołuj go regularnie (na przykład co 15 minut) z harmonogramu zadań Twojego hostingu.

Adres URL zawiera token bezpieczeństwa. Każde wywołanie pracuje około dwudziestu sekund, a następnie czysto się zatrzymuje, aby pozostać zgodnym z limitami czasu wykonania PHP.

Jak działa reindeksowanie

Przy każdym dodaniu, modyfikacji lub usunięciu produktu odpowiedni wpis jest oznaczany do reindeksowania. Moduł oblicza sumę kontrolną tekstu produktu: jeśli zmieniła się tylko cena lub stan magazynowy, tekst pozostaje identyczny i żadne nowe wywołanie API nie jest uruchamiane. Wyłączone produkty i wyłączone języki są automatycznie usuwane z indeksu.

Wyszukiwanie w sklepie

Autouzupełnianie

Włącz Autouzupełnianie w sklepie, aby dołączyć menu semantycznych podpowiedzi do paska wyszukiwania Twojego motywu. Pole Selektor CSS pola wyszukiwania wskazuje modułowi, do którego pola ma się dołączyć. Wartość domyślna #search_widget input[type="text"] działa z motywami opartymi na classic.

Wyłączenie autouzupełniania motywu

Ustawienie Wyłącz autouzupełnianie motywu (domyślnie włączone) usuwa natywne podpowiedzi wyszukiwania (ps_searchbar i podobne), aby uniknąć podwójnej listy rozwijanej. Moduł wyrejestrowuje natywny skrypt i ukrywa każdą listę wstrzykniętą przez niestandardowy motyw.

Tryb hybrydowy

Z włączonym trybem hybrydowym (zalecane) ranking semantyczny jest na początku, a brakujące natywne wyniki słów kluczowych są dołączane po nim. Nigdy nie otrzymasz mniej wyników niż w oryginalnym wyszukiwaniu.

Próg i liczba wyników

Minimalny wynik podobieństwa (od 0 do 0,99; zalecane: 0,30) odrzuca zbyt odległe wyniki. Maksymalna liczba wyników ogranicza podpowiedzi wyświetlane w autouzupełnianiu.

Strona wyników wyszukiwania

Ustawienie Przejmij stronę wyników wyszukiwania (domyślnie włączone) sprawia, że moduł dostarcza ranking strony poprzez hook productSearchProvider, oficjalny mechanizm PrestaShop używany przez nawigację fasetową. Konkretnie:

• autouzupełnianie i strona pokazują te same produkty, w tej samej kolejności;
• paginacja i sortowanie motywu nadal działają (sortowanie „trafność” zachowuje kolejność semantyczną; cena, nazwa i data są przeliczane wewnątrz rankingu);
• jeśli API embeddingów jest niedostępne, moduł po cichu wraca do wyników natywnych i rejestruje incydent: strona wyszukiwania nigdy się nie psuje.

Moduł uruchamia się tylko przy wyszukiwaniu tekstowym. Kategorie, strony tagów i inne listy zachowują swoje natywne mechanizmy.

Podobne produkty (Może Ci się także spodobać)

Blok podobnych produktów (domyślnie włączony) wyświetla na każdej karcie produktu sekcję „Może Ci się także spodobać”, obliczaną według bliskości semantycznej między wektorami już zapisanymi w Twojej bazie danych. Żadne wywołanie API nie jest wykonywane: blok działa nawet bez klucza API, dopóki istnieje indeks.

• Liczba podobnych produktów: od 2 do 12 (domyślnie 6).
• Minimalny wynik podobnych produktów: dedykowany próg, niezależny od progu wyszukiwania (zalecane: 0,45). Poniżej niego produkt się nie pojawia, nawet jeśli oznacza to mniej kart. Jego zmiana automatycznie czyści pamięć podręczną podobnych produktów.
• Bonus powinowactwa faworyzuje produkty z tej samej kategorii domyślnej i tej samej marki.
• Wyniki są przechowywane w pamięci podręcznej 24 godziny na produkt i automatycznie unieważniane przy reindeksowaniu.
• Renderowanie używa natywnych miniatur Twojego motywu: etykiety, lista życzeń, szybki podgląd i style hover włącznie.

W małym katalogu demonstracyjnym, gdzie wszystkie karty dzielą ten sam tekst marketingowy, podobieństwa są naturalnie luźniejsze. Podnieś próg do 0,55-0,60, aby zachować tylko bliskie dopasowania.

Statystyki i analityka

Strona konfiguracji wyświetla panel obliczany z ostatnich 30 dni: liczba wyszukiwań, odsetek bez wyników, średnia liczba wyników na wyszukiwanie, histogram dziennego wolumenu, top 20 zapytań (liczba, średnie wyniki, najlepszy wynik) i top 20 zapytań bez wyników.

Zapytania bez wyników to kopalnia złota: wskazują dokładnie, czego szukają Twoi klienci, nie znajdując tego, a więc co dodać do katalogu lub synonimów.

• Przycisk Eksportuj CSV pobiera pełny dziennik (separator średnik) ze źródłem każdego wyszukiwania: autouzupełnianie lub strona wyników.
• Dziennik jest automatycznie czyszczony po 365 dniach.

Pamięć podręczna zapytań

Embeddingi zapytań klientów są przechowywane w pamięci podręcznej przez 30 dni. Powtarzane wyszukiwania są natychmiastowe i nie są ponownie rozliczane. Przycisk Wyczyść pamięć podręczną zapytań pozwala ją zresetować w dowolnym momencie.

Aktualizacja modułu

Jeśli aktualizujesz moduł przez zastąpienie jego plików (poza Menedżerem modułów), otwórz raz stronę konfiguracji: moduł automatycznie zarejestruje brakujące hooki, utworzy brakujące tabele i kolumny oraz ustawi nowe wartości domyślne. Pliki CSS i JS frontu zawierają cache-buster, czyszczenie pamięci podręcznej przeglądarki nie jest potrzebne.

Rozwiązywanie problemów

• Nie pojawiają się żadne wyniki: sprawdź, czy indeks jest zbudowany (licznik „Zaindeksowane wektory” > 0) i czy klucz API jest ważny.
• Wyświetlają się dwie listy rozwijane: sprawdź, czy Wyłącz autouzupełnianie motywu jest włączone, a następnie wyczyść raz pamięć podręczną PrestaShop.
• Autouzupełnianie i strona wyników się różnią: otwórz raz stronę konfiguracji modułu (hook strony wyników zostanie zarejestrowany automatycznie) i sprawdź, czy Przejmij stronę wyników wyszukiwania jest włączone.
• Blok Może Ci się także spodobać jest pusty: indeks musi być zbudowany dla bieżącego języka i sklepu; w przeciwnym razie obniż minimalny wynik podobnych produktów.
• Przekroczenia limitu czasu podczas indeksowania: zmniejsz rozmiar partii i preferuj indeksowanie przez cron.
• Niespójne wyniki po zmianie modelu: uruchom pełną odbudowę indeksu.