Wyszukiwanie Semantyczne AI dla PrestaShop

Ten moduł dodaje do sklepu PrestaShop wyszukiwanie semantyczne oparte na sztucznej inteligencji. Zamiast dosłownie porównywać słowa kluczowe, rozumie sens zapytania klienta dzięki wektorom osadzeń (embeddings) i pokazuje trafne produkty nawet bez dokładnego dopasowania.

Wymagania

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

Instalacja

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

Moduł tworzy trzy tabele (dfvectorsearch_index, dfvectorsearch_qcache, dfvectorsearch_log) oraz ukrytą zakładkę obsługującą wywołania AJAX. Po stronie klienta nic nie jest widoczne, dopóki indeks nie zostanie zbudowany.

Konfiguracja dostawcy embeddingów

W zakładce Ustawienia wybierz dostawcę, a następnie wprowadź swój klucz API.

OpenAI

Wybierz dostawcę OpenAI i wpisz klucz. Zalecany model to text-embedding-3-small, który daje dobry stosunek jakości do ceny. Aby uzyskać maksymalną precyzję przy wymagającym katalogu, możesz użyć text-embedding-3-large.

Mistral AI (hosting europejski)

Wybierz Mistral AI, aby dane były przetwarzane w Europie, zgodnie z RODO. Model do użycia to mistral-embed.

Bramka zgodna z OpenAI

Wybierz Custom, aby korzystać z własnej bramki: wewnętrznego proxy, Azure OpenAI i podobnych. Podaj wtedy bazowy adres URL API, na przykład https://moja-bramka.przyklad.com/v1.

Klucz API jest maskowany po zapisaniu. Pozostaw zamaskowaną wartość bez zmian, aby zachować istniejący klucz. Wpisz 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 akceptują zredukowaną liczbę wymiarów, na przykład 512.

Zmiana dostawcy, modelu lub liczby wymiarów unieważnia cały indeks: przy zapisie indeks zostaje automatycznie oznaczony do pełnej przebudowy, a pamięć podręczna zapytań jest czyszczona. Następnie uruchom indeksowanie ponownie.

Budowanie indeksu

Po zapisaniu klucza API przejdź do panelu 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.

Liczniki pokazują liczbę pozycji możliwych do zaindeksowania (produkty pomnożone przez języki), wektory już zaindeksowane, pozycje oczekujące oraz liczbę embeddingów zapytań w pamięci podręcznej.

Rozmiar partii

Ustawienie Rozmiar partii indeksowania określa liczbę produktów przetwarzanych w jednym wywołaniu, od 5 do 100. Zmniejsz je, jeśli serwer zgłasza przekroczenia limitu czasu.

Indeksowanie zaplanowane (cron)

Aby indeks automatycznie nadążał za zmianami w katalogu, skopiuj adres URL indeksowania cron widoczny w konfiguracji i wywołuj go regularnie, na przykład co 15 minut, z harmonogramu zadań na swoim hostingu.

Adres zawiera token bezpieczeństwa. Każde wywołanie pracuje przez około dwadzieścia sekund, po czym kończy się prawidłowo, aby zmieścić się w limitach czasu wykonania PHP.

Jak działa ponowne indeksowanie

Przy każdym dodaniu, zmianie lub usunięciu produktu odpowiednia pozycja jest oznaczana do ponownego zaindeksowania. 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. Produkty wyłączone lub odłączone od sklepu, a także wyłączone języki, są automatycznie usuwane z indeksu.

Wyszukiwanie po stronie klienta

Włącz Autouzupełnianie w sklepie, aby dodać menu podpowiedzi semantycznych do paska wyszukiwania w Twoim szablonie.

Selektor CSS

Pole Selektor CSS pola wyszukiwania wskazuje modułowi, do którego pola ma się podłączyć. Wartość domyślna #search_widget input[type="text"] działa z szablonami opartymi na classic. W przypadku szablonu niestandardowego dostosuj selektor do pola wyszukiwania w swoim szablonie.

Tryb hybrydowy

Przy włączonym trybie hybrydowym, co jest zalecane, moduł łączy wynik semantyczny z dopasowaniem słów kluczowych do nazwy produktu. Dokładne dopasowania nazwy są dzięki temu premiowane, bez utraty trafności semantycznej.

Próg i liczba wyników

Minimalny wynik podobieństwa, od 0 do 0,99, zalecana wartość 0,30, odrzuca wyniki zbyt odległe od zapytania. Pole maksymalna liczba wyników ogranicza liczbę wyświetlanych podpowiedzi.

Analiza wyszukiwań

Każde wyszukiwanie jest zapisywane w dzienniku: zapytanie, język, sklep, liczba wyników i najlepszy wynik podobieństwa. Te dane pomagają zrozumieć, czego naprawdę szukają klienci, oraz wychwycić zapytania bez wyników, aby uzupełnić katalog.

Pamięć podręczna zapytań

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

Rozwiązywanie problemów

• Brak wyników: sprawdź, czy indeks został zbudowany, czyli czy licznik „Zaindeksowane wektory” jest większy od zera, oraz czy klucz API jest prawidłowy.
• Autouzupełnianie się nie pojawia: sprawdź selektor CSS oraz to, czy autouzupełnianie jest włączone. Szczegółowe komunikaty błędów są zapisywane w dziennikach PrestaShop.
• Przekroczenia limitu czasu podczas indeksowania: zmniejsz rozmiar partii i korzystaj z indeksowania przez cron.
• Niespójne wyniki po zmianie modelu: uruchom pełną przebudowę indeksu.