# Vector Search Native: kompletna dokumentacja

> Prezentacja Vector Search Native zamienia wyszukiwanie produktów w WooCommerce w silnik semantyczny. Zamiast porównywać słowa kluczowe litera po literze, wtyczka konwertuje każdy produkt i każde zapytanie na wektory liczbowe (embeddingi)…

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

## Prezentacja

Vector Search Native zamienia wyszukiwanie produktów w WooCommerce w silnik semantyczny. Zamiast porównywać słowa kluczowe litera po literze, wtyczka konwertuje każdy produkt i każde zapytanie na wektory liczbowe (embeddingi) przez model AI, a następnie liczy podobieństwo ich znaczeń. Efekt: klient wpisujący „lekka letnia bawełniana kurtka" znajdzie Twoją „letnią marynarkę lnianą", nawet bez wspólnego słowa.

Wtyczka obsługuje trzech dostawców embeddingów, OpenAI, Voyage AI i Cohere, wymienialnych jednym kliknięciem, z indeksowaniem przyrostowym, które wywołuje API tylko wtedy, gdy treść produktu faktycznie się zmieniła, oraz z automatycznym fallbackiem do natywnego wyszukiwania po słowach kluczowych, gdy wyszukiwanie wektorowe nie wystarczy.

## Wymagania

- WordPress 6.2 lub nowszy
- WooCommerce 7.0 lub nowszy (testowane do 9.4)
- PHP 8.0 lub nowszy
- Klucz API u jednego z trzech dostawców: [OpenAI](https://platform.openai.com/api-keys), [Voyage AI](https://dash.voyageai.com/) albo [Cohere](https://dashboard.cohere.com/api-keys)
- Działający WP-Cron (albo cron systemowy wywołujący wp-cron.php)

Żadne szczególne rozszerzenie MySQL, żaden serwer Redis ani Elasticsearch nie są wymagane. Obliczenie podobieństwa wykonuje się w czystym PHP, dzięki czemu wtyczka działa na dowolnym standardowym hostingu współdzielonym.

## Instalacja

1. W panelu WordPressa przejdź do **Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer**.
2. Wybierz plik `vector-search-native.zip` i kliknij **Zainstaluj teraz**.
3. Kliknij **Włącz**. Wtyczka automatycznie tworzy dwie tabele (`wp_vsn_embeddings` i `wp_vsn_index_queue`) i planuje swoje zadanie cron.
4. Pod WooCommerce pojawia się nowe menu **Vector Search**.

## Konfiguracja dostawcy

Przejdź do **WooCommerce → Vector Search**. Sekcja „Embedding provider" wymienia trzech dostępnych dostawców. Wybierz swojego z listy „Active provider", wklej klucz API w odpowiedni blok, wybierz model i kliknij **Test connection**. Zielony komunikat potwierdzający wymiar wektora (na przykład „Connection OK. Embedding dimension: 1536") potwierdza konfigurację.

### Jaki model wybrać

- **OpenAI text-embedding-3-small** (1536d): najlepszy stosunek jakości do ceny, zalecany domyślnie.
- **OpenAI text-embedding-3-large** (3072d): maksymalna jakość, około 6 razy droższy.
- **Voyage voyage-3** (1024d): świetny retrieval, trenowany pod wyszukiwanie.
- **Cohere embed-multilingual-v3.0** (1024d): wybór dla katalogów wielojęzycznych FR/EN/ES/DE/IT.

Zmiana dostawcy albo modelu sprawia, że istniejące wektory stają się niekompatybilne (inne wymiary). Po zmianie zawsze uruchom pełne reindeksowanie.

## Indeksowanie początkowe

1. Wciąż na stronie Vector Search kliknij **Queue all products for reindex**. Wszystkie opublikowane produkty trafiają do kolejki.
2. Kliknij **Auto-process until done**. Wtyczka przetwarza kolejkę partiami (domyślnie 25 produktów) aż do wyczerpania, na żywo z Twojej przeglądarki.
3. Liczniki „Indexed", „Queued" i „Stuck" aktualizują się w czasie rzeczywistym.

Możesz też pozwolić WP-Cronowi wykonać pracę w tle: zadanie `vsn_process_queue` działa według skonfigurowanego interwału (domyślnie 5 minut) i stopniowo opróżnia kolejkę.

Koszt orientacyjny: około 0,02 € za 1 000 produktów przy OpenAI text-embedding-3-small. Indeksowanie przyrostowe po hashu SHA-256 gwarantuje, że niezmieniony produkt nigdy nie wywoła zapytania do API, nawet jeśli kolejka przejdzie przez niego ponownie.

## Jak działa wyszukiwanie

Po zakończeniu indeksowania wyszukiwanie produktów WooCommerce (front i standardowe widżety) jest automatycznie przechwytywane. Wtyczka:

1. Konwertuje zapytanie odwiedzającego na wektor przez aktywnego dostawcę (z cache 10-minutowym).
2. Liczy podobieństwo kosinusowe względem wszystkich zapisanych wektorów produktów.
3. Zatrzymuje produkty przekraczające minimalny próg podobieństwa (domyślnie 0,30), w granicach maksymalnej liczby kandydatów (domyślnie 200).
4. Wstrzykuje identyfikatory posortowane według trafności do zapytania WordPressa.

Jeśli liczba wyników jest niższa od progu fallbacku (domyślnie 3), wtyczka usuwa się z drogi i pozwala normalnie zadziałać natywnemu wyszukiwaniu po słowach kluczowych WooCommerce. Twoi odwiedzający nigdy nie zobaczą pustej strony z powodu problemu po stronie AI.

## Ustawienia zaawansowane

### Indeksowana treść

Sekcja „Content to index" pozwala wybrać pola włączane do embeddingu: krótki opis, długi opis, SKU, kategorie, tagi i atrybuty. Tytuł produktu jest indeksowany zawsze. Ograniczenie pól bywa dobre dla trafności w niektórych katalogach; włączenie wszystkich maksymalizuje pokrycie.

### Progi i kandydaci

- **Minimum similarity** (0,0 do 1,0): poniżej tego wyniku kosinusowego produkt nie jest brany. Podnieś do 0,4 do 0,5, aby filtrować agresywnie, zejdź do 0,2, aby poszerzyć.
- **Max candidates**: liczba produktów zwracanych do WooCommerce po sortowaniu. Paginacja działa potem normalnie.
- **Fallback threshold**: minimalna liczba wyników wektorowych przed przejściem na słowa kluczowe.

### Kolejka i cron

- **Cron interval**: częstotliwość przetwarzania kolejki (1, 5, 15 minut albo co godzinę).
- **Batch size** (1 do 100): produkty przetwarzane na tick. Zwiększaj ostrożnie, aby uniknąć limitów zapytań u dostawcy.
- Każdy nieudany produkt jest ponawiany do 5 razy, z zachowaniem ostatniego komunikatu błędu w bazie. Licznik „Stuck" wskazuje produkty, które wyczerpały próby.

## REST API

Pięć endpointów udostępnianych pod `/wp-json/vsn/v1/`, wszystkie zarezerwowane dla użytkowników ze zdolnością `manage_woocommerce`:

- `POST /reindex` — dodaje wszystkie produkty do kolejki.
- `POST /process` — przetwarza partię natychmiast.
- `GET /stats` — zwraca liczniki (łącznie, zaindeksowane, w kolejce, zablokowane).
- `POST /test` — testuje klucz API (parametry: `provider`, `api_key`, `model`).
- `POST /clear` — całkowicie czyści indeks embeddingów.

Przykład pełnego reindeksowania ze skryptu wdrożeniowego:

```
curl -X POST https://twoj-sklep.pl/wp-json/vsn/v1/reindex
  -u admin:HASLO_APLIKACJI
```

## Hooki dla deweloperów

### vsn_indexed_text

Personalizuje tekst wysyłany do dostawcy dla każdego produktu. Idealne do wstrzykiwania pól ACF albo meta biznesowych:

```
add_filter( 'vsn_indexed_text', function ( $text, $product ) {
    $material = get_post_meta( $product->get_id(), 'material', true );
    if ( $material ) {
        $text .= "nMaterial: " . $material;
    }
    return $text;
}, 10, 2 );
```

### vsn_should_engage

Precyzyjnie kontroluje, kiedy wyszukiwanie wektorowe się włącza:

```
// Disable vector search for single-word queries.
add_filter( 'vsn_should_engage', function ( $engage, $query ) {
    $s = (string) $query->get( 's' );
    if ( str_word_count( $s ) < 2 ) {
        return false;
    }
    return $engage;
}, 10, 2 );
```

## Sklepy wielojęzyczne

Przy WPML albo Polylangu każde tłumaczenie jest odrębnym produktem WordPressa: każde jest więc embeddowane osobno, we własnym języku. Dwie rekomendacje:

- Użyj modelu wielojęzycznego (Cohere `embed-multilingual-v3.0` albo Voyage `voyage-multilingual-2`), aby zapytania i karty produktów trafiały do tej samej przestrzeni semantycznej niezależnie od języka.
- Po dodaniu nowego języka albo masowej kampanii tłumaczeniowej uruchom pełne reindeksowanie, aby objąć nowe produkty.

## Rozwiązywanie problemów

### Produkty pozostają w statusie „Stuck"

Produkt trafia do „Stuck" po 5 kolejnych niepowodzeniach. Częste przyczyny: nieprawidłowy albo wygasły klucz API, limit zapytań u dostawcy, timeout sieciowy. Sprawdź klucz przyciskiem **Test connection**, popraw, a następnie kliknij **Queue all products for reindex**: to zeruje liczniki prób.

### Wyszukiwanie wydaje się niezmienione

- Sprawdź, czy pole **Enabled** jest zaznaczone w ustawieniach ogólnych.
- Sprawdź, czy licznik „Indexed" odpowiada liczbie Twoich produktów.
- Jeśli używasz zewnętrznej wtyczki wyszukiwania (FiboSearch, SearchWP i podobne), może ona przechwytywać standardowe zapytanie WordPressa przed naszym przechwyceniem. Wyłącz ją albo skontaktuj się z nami w sprawie dopasowania integracji.

### Kolejka nie opróżnia się sama

WP-Cron uruchamia się tylko przy wizytach. W witrynie o niskim ruchu skonfiguruj cron systemowy:

```
*/5 * * * * curl -s https://twoj-sklep.pl/wp-cron.php > /dev/null 2>&1
```

## Deinstalacja

Wyłączenie wtyczki zawiesza crona, ale zachowuje dane. Usunięcie wtyczki ze strony Wtyczki uruchamia `uninstall.php`, który kasuje dwie tabele MySQL, opcję ustawień i zaplanowane zadania. Żadnych pozostałości w bazie.

## FAQ

### Czy mogę używać wtyczki bez klucza API?

Nie, wyszukiwanie semantyczne wymaga dostawcy. Bez klucza wtyczka pozostaje bezczynna, a natywne wyszukiwanie WooCommerce działa dalej normalnie.

### Czy klucze API są widoczne po stronie klienta?

Nie. Wszystkie wywołania do dostawców wykonują się po stronie serwera, z PHP. Klucz nigdy nie pojawia się w HTML-u ani w żądaniach przeglądarki.

### Jaki wolumen katalogu jest obsługiwany?

Skanowanie kosinusowe w PHP pozostaje bardzo wydajne mniej więcej do 50 000 produktów na standardowym hostingu współdzielonym. Powyżej skontaktuj się z nami, aby omówić integrację z dedykowanym indeksem approximate-nearest-neighbor.