Wyszukiwanie Wizualne po Zdjęciu i Shop the Look AI: kompletny przewodnik

Ten moduł dodaje do Twojego sklepu wyszukiwanie produktów po zdjęciu: klient przeciąga fotografię i otrzymuje artykuły z katalogu najbliższe wizualnie, uszeregowane według wyniku podobieństwa. Tryb Shop the Look wykrywa każdy artykuł widoczny na całej scenie i proponuje odpowiadające produkty. Silnik jest niezależny: wybierasz dostawcę AI (Voyage, Cohere, OpenAI lub Mistral) i używasz własnego klucza. Ten przewodnik obejmuje instalację, konfigurację, indeksowanie katalogu i działanie wyszukiwania.

Instalacja

1. Pobierz archiwum dfvisualsearch.zip ze swojego konta DataFirefly.
2. Panel administracyjny PrestaShop → Moduły → Wgraj moduł → wyślij plik ZIP.
3. Moduł tworzy własną tabelę indeksu, rejestruje hooki i dodaje dedykowaną zakładkę administracyjną.

Konfiguracja ogólna

Przejdź do Moduły → Wyszukiwanie Wizualne i Shop the Look AI → Konfiguruj.

Wybór dostawcy

Wybierz silnik z listy, a następnie podaj odpowiadający mu klucz API. Za AI płacisz według zużycia bezpośrednio u dostawcy, bez abonamentu dokładanego przez moduł.

• Voyage i Cohere: bezpośrednie multimodalne embeddingi obrazu.
• OpenAI i Mistral: analiza vision, a następnie embedding, co dodatkowo odblokowuje Shop the Look.
• Klucz API: przechowywany po stronie serwera, nigdy nie jest udostępniany w front office. Każdy dostawca ma własny model i konfigurowalny wymiar wektora.

Zachowanie

• Liczba wyników: ile produktów wyświetlać przy wyszukiwaniu po obrazie.
• Minimalne podobieństwo (0 do 1): wartość 0 pokazuje wszystko, uszeregowane według trafności; podnieś ją (na przykład 0,2 do 0,4), aby odrzucić słabe dopasowania. Do skalibrowania zależnie od dostawcy.
• Włącz Shop the Look oraz liczba produktów na wykryty artykuł.
• Produkty podobne na karcie produktu i ich liczba.
• Wstrzykiwanie przycisku aparatu w nagłówek albo umieszczenie go ręcznie w motywie przez hook displayDfVisualSearchButton.
• Maksymalny rozmiar pliku oraz automatyczne przeindeksowanie przy zapisie produktu.

Indeksowanie katalogu

W panelu Indeks katalogu w konfiguracji:

1. Kliknij Indeksuj lub przeindeksuj katalog: moduł przetwarza produkty partiami, z paskiem postępu, bez ryzyka przekroczenia limitu czasu serwera.
2. Licznik pokazuje produkty zaindeksowane dla aktywnego dostawcy.
3. Wyczyść indeks usuwa wektory bieżącego sklepu.

Indeksowanie zamienia zdjęcie główne każdego produktu w wektor zapisany w bazie danych. Po zaindeksowaniu produkt jest kodowany ponownie tylko wtedy, gdy zmieni się jego zdjęcie.

Jak działa wyszukiwanie

Każdy obraz jest zamieniany na znormalizowany wektor (embedding). Zdjęcie wysłane przez klienta jest kodowane przez tego samego dostawcę, a następnie porównywane z indeksem przez podobieństwo cosinusowe, które na znormalizowanych wektorach sprowadza się do zwykłego iloczynu skalarnego. Produkty są potem szeregowane według malejącego wyniku i filtrowane skonfigurowanym progiem minimalnym.

• Dostawcy Voyage i Cohere kodują obraz bezpośrednio.
• Dostawcy OpenAI i Mistral opisują obraz modelem vision, a następnie kodują ten opis: indeksowanie i zapytanie żyją dzięki temu w tej samej przestrzeni wektorowej.

Shop the Look

Na podstawie zdjęcia całej sceny Shop the Look identyfikuje każdy widoczny artykuł i uruchamia wyszukiwanie dla każdego z nich, prezentując wyniki w osobnych grupach.

Produkty wizualnie podobne

Na karcie produktu automatycznie wyświetla się blok produktów wizualnie podobnych. Wykorzystuje on wektor policzony już podczas indeksowania produktu: do AI nie jest wysyłane żadne dodatkowe zapytanie, więc rekomendacja nie generuje powtarzalnych kosztów.

Widok po stronie klienta

Przycisk aparatu otwiera okno modalne, w którym klient przeciąga i upuszcza zdjęcie albo je wybiera. Wyświetla się podgląd, a następnie wyniki pojawiają się jako karty produktów z wynikiem podobieństwa w procentach. Gdy Shop the Look jest włączony, klient może zaznaczyć opcję, aby otrzymać wyniki pogrupowane według wykrytego artykułu.

Wybór dostawcy

Wszyscy dostawcy zapewniają wyszukiwanie po obrazie. Wybór zależy od Twoich potrzeb:

• Voyage i Cohere: bezpośrednie multimodalne embeddingi, proste i szybkie, bez Shop the Look.
• OpenAI i Mistral: analiza vision, która odblokowuje wykrywanie wielu artykułów w Shop the Look.

Zgodność i uwagi techniczne

• PrestaShop 1.7.6 do 9.x, multisklep i wielojęzyczność; każdy sklep zachowuje własny indeks.
• Kontroler administracyjny legacy (bez kontrolera Symfony) dla zgodności z PS8 i PS9.
• Używane hooki: displayHeader, displayTop, displayDfVisualSearchButton, displayFooterProduct, actionProductSave, actionProductDelete.
• Wektory zapisywane w bazie w postaci znormalizowanej, zakodowane dla odpornego przechowywania; wyszukiwanie przez iloczyn skalarny.
• Ograniczenie antynadużyciowe na sesję chroni Twój limit AI.
• Endpoint wyszukiwania AJAX przez link modułu; odpowiedź w formacie JSON.

FAQ i rozwiązywanie problemów

Przycisk wyszukiwania się nie pojawia. Sprawdź, czy dostawca jest skonfigurowany, a jego klucz prawidłowy (przycisk Testuj dostawcę), oraz czy wstrzykiwanie w nagłówek jest włączone lub hook jest poprawnie umieszczony w motywie.

Wyszukiwanie nie zwraca żadnych wyników. Upewnij się, że katalog został zaindeksowany dla aktywnego dostawcy, i obniż minimalne podobieństwo, jeśli jest zbyt wysokie dla przestrzeni wektorowej tego dostawcy.

Shop the Look zwraca jedną grupę. Aktywny dostawca nie obsługuje wykrywania (Voyage lub Cohere). Przejdź na OpenAI lub Mistral, aby uzyskać wykrywanie wielu artykułów, a następnie przeindeksuj katalog.

Zmieniłem dostawcę i wyniki są niespójne. Uruchom pełne indeksowanie od nowa: wektory muszą zostać przeliczone w przestrzeni nowego dostawcy.