Vector Search Native — Vollständige Dokumentation

Überblick

Vector Search Native verwandelt die WooCommerce-Produktsuche in eine semantische Suchmaschine. Statt Schlüsselwörter Buchstabe für Buchstabe abzugleichen, wandelt das Plugin jedes Produkt und jede Anfrage über ein KI-Modell in numerische Vektoren (Embeddings) um und berechnet dann deren Bedeutungsähnlichkeit. Das Ergebnis: Ein Kunde, der „leichte Baumwolljacke für Sommer“ eingibt, findet Ihren „Sommer-Leinen-Blazer“ — auch ohne ein gemeinsames Wort.

Das Plugin unterstützt drei Embedding-Anbieter — OpenAI, Voyage AI und Cohere — per Klick wechselbar, mit inkrementeller Indexierung, die die API nur aufruft, wenn sich der Inhalt eines Produkts tatsächlich geändert hat, und einem automatischen Fallback auf die native Keyword-Suche, wenn die Vektor-Suche nicht ausreicht.

Voraussetzungen

• WordPress 6.2 oder neuer
• WooCommerce 7.0 oder neuer (getestet bis 9.4)
• PHP 8.0 oder neuer
• Ein API-Schlüssel eines der drei Anbieter: OpenAI, Voyage AI oder Cohere
• Funktionierendes WP-Cron (oder ein System-Cron, der wp-cron.php aufruft)

Installation

1. Gehen Sie in Ihrem WordPress-Backend zu Plugins → Installieren → Plugin hochladen.
2. Wählen Sie die Datei vector-search-native.zip und klicken Sie auf Jetzt installieren.
3. Klicken Sie auf Aktivieren. Das Plugin erstellt automatisch seine zwei Tabellen (wp_vsn_embeddings und wp_vsn_index_queue) und plant seine Cron-Aufgabe.
4. Ein neues Menü Vector Search erscheint unter WooCommerce.

Anbieter-Konfiguration

Gehen Sie zu WooCommerce → Vector Search. Der Abschnitt „Embedding provider“ listet die drei verfügbaren Anbieter. Wählen Sie Ihren im Dropdown „Active provider“, fügen Sie Ihren API-Schlüssel im entsprechenden Block ein, wählen Sie ein Modell und klicken Sie auf Test connection. Eine grüne Meldung mit Bestätigung der Vektor-Dimension (z. B. „Connection OK. Embedding dimension: 1536″) validiert die Konfiguration.

Welches Modell wählen

• OpenAI text-embedding-3-small (1536d): das beste Preis-Leistungs-Verhältnis, empfohlener Standard.
• OpenAI text-embedding-3-large (3072d): maximale Qualität, etwa 6-mal teurer.
• Voyage voyage-3 (1024d): hervorragendes Retrieval, für die Suche trainiert.
• Cohere embed-multilingual-v3.0 (1024d): die Wahl für mehrsprachige DE/EN/FR/ES/IT-Kataloge.

Erstindexierung

1. Klicken Sie auf der Vector-Search-Seite auf Queue all products for reindex. Alle veröffentlichten Produkte kommen in die Warteschlange.
2. Klicken Sie auf Auto-process until done. Das Plugin verarbeitet die Warteschlange in Batches (standardmäßig 25 Produkte) bis sie leer ist, live aus Ihrem Browser.
3. Die Zähler „Indexed“, „Queued“ und „Stuck“ aktualisieren sich in Echtzeit.

Sie können die Arbeit auch WP-Cron im Hintergrund überlassen: Die Aufgabe vsn_process_queue läuft im konfigurierten Intervall (standardmäßig 5 Minuten) und leert die Warteschlange schrittweise.

Funktionsweise der Suche

Nach Abschluss der Indexierung wird die WooCommerce-Produktsuche (Frontend und Standard-Widgets) automatisch abgefangen. Das Plugin:

1. Wandelt die Anfrage des Besuchers über den aktiven Anbieter in einen Vektor um (mit 10-Minuten-Cache).
2. Berechnet die Kosinus-Ähnlichkeit gegen alle gespeicherten Produkt-Vektoren.
3. Behält Produkte über dem Mindest-Ähnlichkeits-Schwellenwert (standardmäßig 0,30), bis zur maximalen Kandidatenzahl (standardmäßig 200).
4. Injiziert die nach Relevanz sortierten IDs in die WordPress-Abfrage.

Fällt die Ergebniszahl unter den Fallback-Schwellenwert (standardmäßig 3), tritt das Plugin zurück und lässt die native WooCommerce-Keyword-Suche normal laufen. Ihre Besucher sehen nie eine leere Seite wegen eines KI-seitigen Problems.

Erweiterte Einstellungen

Indexierter Inhalt

Der Abschnitt „Content to index“ erlaubt die Wahl der im Embedding enthaltenen Felder: Kurzbeschreibung, lange Beschreibung, SKU, Kategorien, Schlagwörter und Attribute. Der Produkttitel wird immer indexiert. Weniger Felder können die Relevanz bei manchen Katalogen schärfen; alle einzubeziehen maximiert den Recall.

Schwellenwerte und Kandidaten

• Minimum similarity (0,0 – 1,0): Unter diesem Kosinus-Score wird ein Produkt verworfen. Erhöhen Sie auf 0,4 – 0,5 für aggressive Filterung, senken Sie auf 0,2 zur Erweiterung.
• Max candidates: Anzahl der nach dem Ranking an WooCommerce zurückgegebenen Produkte. Die Paginierung greift danach normal.
• Fallback threshold: Mindestzahl an Vektor-Ergebnissen, bevor auf Keywords umgeschaltet wird.

Warteschlange und Cron

• Cron interval: Verarbeitungsfrequenz der Warteschlange (1, 5, 15 Minuten oder stündlich).
• Batch size (1 – 100): Produkte pro Tick. Vorsichtig erhöhen, um Anbieter-Rate-Limits zu vermeiden.
• Jedes fehlgeschlagene Produkt wird bis zu 5-mal wiederholt, die letzte Fehlermeldung wird in der Datenbank gespeichert. Der Zähler „Stuck“ markiert Produkte, die ihre Versuche ausgeschöpft haben.

REST-API

Fünf Endpoints sind unter /wp-json/vsn/v1/ verfügbar, alle beschränkt auf Benutzer mit der Berechtigung manage_woocommerce:

• POST /reindex — stellt alle Produkte in die Warteschlange.
• POST /process — verarbeitet sofort einen Batch.
• GET /stats — gibt die Zähler zurück (gesamt, indexiert, in Warteschlange, blockiert).
• POST /test — testet einen API-Schlüssel (Parameter: provider, api_key, model).
• POST /clear — leert den Embeddings-Index vollständig.

Beispiel für eine vollständige Neuindexierung aus einem Deployment-Skript:

curl -X POST https://ihr-shop.de/wp-json/vsn/v1/reindex 
  -u admin:ANWENDUNGSPASSWORT

Entwickler-Hooks

vsn_indexed_text

Passt den an den Anbieter gesendeten Text pro Produkt an. Ideal zum Einbinden von ACF-Feldern oder Geschäftsmetadaten:

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

Feinsteuerung, wann die Vektor-Suche greift:

// Vektor-Suche für Ein-Wort-Anfragen deaktivieren.
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 );

Mehrsprachige Shops

Mit WPML oder Polylang ist jede Übersetzung ein eigenes WordPress-Produkt: Jede wird daher separat eingebettet, in ihrer eigenen Sprache. Zwei Empfehlungen:

• Verwenden Sie ein mehrsprachiges Modell (Cohere embed-multilingual-v3.0 oder Voyage voyage-multilingual-2), damit Anfragen und Produktseiten unabhängig von der Sprache in denselben semantischen Raum projiziert werden.
• Nach dem Hinzufügen einer neuen Sprache oder einer großen Übersetzungskampagne starten Sie eine vollständige Neuindexierung, um die neuen Produkte abzudecken.

Fehlerbehebung

Produkte bleiben „Stuck"

Ein Produkt wird nach 5 aufeinanderfolgenden Fehlschlägen „Stuck". Häufige Ursachen: ungültiger oder abgelaufener API-Schlüssel, Anbieter-Rate-Limit oder Netzwerk-Timeout. Prüfen Sie Ihren Schlüssel mit Test connection, beheben Sie das Problem und klicken Sie dann auf Queue all products for reindex — das setzt die Versuchszähler zurück.

Die Suche scheint unverändert

• Prüfen Sie, ob das Kästchen Enabled in den allgemeinen Einstellungen angehakt ist.
• Prüfen Sie, ob der Zähler „Indexed" Ihrer Produktzahl entspricht.
• Wenn Sie ein Dritt-Such-Plugin verwenden (FiboSearch, SearchWP…), kann dieses die Standard-WordPress-Abfrage vor dem Abfangen kurzschließen. Deaktivieren Sie es oder kontaktieren Sie uns für eine Integrationsanpassung.

Die Warteschlange leert sich nicht von selbst

WP-Cron feuert nur bei Besuchen. Konfigurieren Sie auf einer Website mit wenig Traffic einen System-Cron:

*/5 * * * * curl -s https://ihr-shop.de/wp-cron.php > /dev/null 2>&1

Deinstallation

Das Deaktivieren des Plugins pausiert den Cron, behält aber die Daten. Das Löschen des Plugins über die Plugins-Seite löst uninstall.php aus, das beide MySQL-Tabellen, die Einstellungsoption und die geplanten Aufgaben entfernt. Keine Rückstände in der Datenbank.

FAQ

Kann ich das Plugin ohne API-Schlüssel nutzen?

Nein — die semantische Suche benötigt einen Anbieter. Ohne Schlüssel bleibt das Plugin inaktiv und die native WooCommerce-Suche funktioniert normal weiter.

Werden API-Schlüssel clientseitig offengelegt?

Nein. Alle Anbieter-Aufrufe erfolgen serverseitig, aus PHP. Der Schlüssel erscheint nie im HTML oder in Browser-Anfragen.

Welche Kataloggröße wird unterstützt?

Der PHP-Kosinus-Scan bleibt bis etwa 50.000 Produkte auf Standard-Shared-Hosting sehr schnell. Darüber hinaus kontaktieren Sie uns, um eine Integration mit einem dedizierten Approximate-Nearest-Neighbor-Index zu besprechen.