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) 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, Voyage AI albo Cohere
• Działający WP-Cron (albo cron systemowy wywołujący wp-cron.php)

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.

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

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.