# 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…

- Strona: <https://www.datafirefly.com/pl/documentation/ai-visual-search-shop-the-look/>
- Język: pl
- Zaktualizowano: 2026-07-31
- Inne języki: [fr](https://www.datafirefly.com/documentation/ai-visual-search-shop-the-look/index.md), [en](https://www.datafirefly.com/en/documentation/ai-visual-search-shop-the-look/index.md), [es](https://www.datafirefly.com/es/documentation/ai-visual-search-shop-the-look/index.md), [de](https://www.datafirefly.com/de/documentation/ai-visual-search-shop-the-look/index.md), [it](https://www.datafirefly.com/it/documentation/ai-visual-search-shop-the-look/index.md), [pt](https://www.datafirefly.com/pt/documentation/ai-visual-search-shop-the-look/index.md), [nl](https://www.datafirefly.com/nl/documentation/ai-visual-search-shop-the-look/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

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

Zgodny z PrestaShop 1.7.6 do 9.x, na PHP 7.4 do 8.3. Bez żadnego override rdzenia i bez zależności Composera.

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

Po zapisaniu dostawcy i klucza użyj przycisku **Testuj dostawcę** w panelu indeksu, aby zweryfikować połączenie przed indeksowaniem.

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

Wyszukiwanie przez podobieństwo cosinusowe działa po stronie serwera i pozostaje płynne do około 10 000 produktów, bez zewnętrznej bazy wektorowej do hostowania.

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

Wykrywanie wielu artykułów wymaga dostawcy vision (OpenAI lub Mistral). Z Voyage lub Cohere Shop the Look przechodzi płynnie na podobieństwo całego looku, liczone dla pełnego obrazu.

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

Każdy dostawca tworzy inną przestrzeń wektorową i inny wymiar wektora. Po zmianie aktywnego dostawcy uruchom indeksowanie katalogu od nowa. Wektory pozostałych dostawców są zachowywane, ale ignorowane przy wyszukiwaniu; panel administracyjny pokazuje liczbę produktów zaindeksowanych dla bieżącego dostawcy.

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