KI-Semantische Suche für PrestaShop

Dieses Modul fügt Ihrem PrestaShop-Shop eine KI-gestützte semantische Suche hinzu. Statt Keywords wörtlich abzugleichen, versteht es die Bedeutung der Kundenanfrage über Vektor-Embeddings und zeigt relevante Produkte an, auch ohne exakte Übereinstimmung.

Voraussetzungen

• PrestaShop 8.0 bis 9.x
• PHP 7.4 bis 8.3 mit aktivierter cURL-Erweiterung
• Ein API-Schlüssel eines Embedding-Anbieters: OpenAI, Mistral AI oder ein beliebiges OpenAI-kompatibles Gateway

Installation

1. Öffnen Sie im Backoffice Module > Modul-Manager.
2. Klicken Sie auf Modul hochladen und laden Sie die ZIP-Datei hoch.
3. Klicken Sie nach der Installation auf Konfigurieren.

Das Modul legt drei Tabellen an (dfvectorsearch_index, dfvectorsearch_qcache, dfvectorsearch_log) sowie einen versteckten Tab für seine AJAX-Aufrufe. Im Storefront ist nichts sichtbar, solange der Index nicht aufgebaut ist.

Embedding-Anbieter konfigurieren

Wählen Sie im Tab Einstellungen Ihren Anbieter und geben Sie Ihren API-Schlüssel ein.

OpenAI

Wählen Sie den Anbieter OpenAI und geben Sie Ihren Schlüssel ein. Das empfohlene Modell ist text-embedding-3-small (gutes Preis-Leistungs-Verhältnis). Für maximale Präzision bei einem anspruchsvollen Katalog können Sie text-embedding-3-large verwenden.

Mistral AI (europäisches Hosting)

Wählen Sie Mistral AI für eine Datenverarbeitung in Europa, DSGVO-konform. Das zu verwendende Modell ist mistral-embed.

OpenAI-kompatibles Gateway

Wählen Sie Custom, um Ihr eigenes Gateway zu verwenden (interner Proxy, Azure OpenAI usw.). Geben Sie dann die Basis-URL der API ein, zum Beispiel https://mein-gateway.beispiel.com/v1.

Der API-Schlüssel wird nach dem Speichern maskiert. Lassen Sie den maskierten Wert unverändert, um den vorhandenen Schlüssel zu behalten; geben Sie nur dann einen neuen Schlüssel ein, wenn Sie ihn ersetzen möchten.

Dimensionen

Das Feld Dimensionen ermöglicht es, die Vektorgröße zu reduzieren, um die Suche bei sehr großen Katalogen zu beschleunigen. Belassen Sie 0, um die Standardgröße des Modells zu verwenden. Die OpenAI-text-embedding-3-Modelle unterstützen reduzierte Dimensionen (zum Beispiel 512).

Ein Wechsel von Anbieter, Modell oder Anzahl der Dimensionen macht den gesamten Index veraltet: Beim Speichern wird der Index automatisch für einen vollständigen Neuaufbau markiert und der Query-Cache geleert. Führen Sie danach die Indexierung erneut aus.

Den Index aufbauen

Gehen Sie nach dem Speichern des API-Schlüssels zum Kasten Embedding-Index oben auf der Konfigurationsseite.

1. Klicken Sie auf Jetzt indexieren. Das Modul verarbeitet die Produkte in Batches mit einem Fortschrittsbalken, Sprache für Sprache und Shop für Shop.
2. Lassen Sie die Seite geöffnet, bis der Status Index aktuell anzeigt.

Die Zähler zeigen die Anzahl der indexierbaren Einträge (Produkte × Sprachen), die bereits indexierten Vektoren, die ausstehenden Einträge und die Anzahl der zwischengespeicherten Query-Embeddings.

Batch-Größe

Die Einstellung Indexierungs-Batch-Größe steuert, wie viele Produkte pro Aufruf verarbeitet werden (5 bis 100). Verringern Sie sie, wenn Ihr Server auf Timeouts stößt.

Geplante Indexierung (Cron)

Um den Index automatisch mit den Katalogaktualisierungen synchron zu halten, kopieren Sie die in der Konfiguration angezeigte Cron-Indexierungs-URL und rufen Sie sie regelmäßig auf (zum Beispiel alle 15 Minuten) über den Aufgabenplaner Ihres Hostings.

Die URL enthält ein Sicherheitstoken. Jeder Aufruf arbeitet etwa zwanzig Sekunden und stoppt dann sauber, um mit den PHP-Ausführungszeitlimits kompatibel zu bleiben.

Wie die Neuindexierung funktioniert

Jedes Mal, wenn ein Produkt hinzugefügt, geändert oder gelöscht wird, wird der entsprechende Eintrag zur Neuindexierung markiert. Das Modul berechnet eine Prüfsumme (Checksum) des Produkttextes: Wenn sich nur der Preis oder der Bestand geändert hat, bleibt der Text identisch und es wird kein neuer API-Aufruf ausgelöst. Deaktivierte oder vom Shop getrennte Produkte sowie deaktivierte Sprachen werden automatisch aus dem Index bereinigt.

Suche im Storefront

Aktivieren Sie Frontend-Autovervollständigung, um ein Menü mit semantischen Vorschlägen an die Suchleiste Ihres Themes anzuhängen.

CSS-Selektor

Das Feld CSS-Selektor des Suchfelds teilt dem Modul mit, an welches Feld es sich anhängen soll. Der Standardwert #search_widget input[type="text"] funktioniert mit classic-basierten Themes. Passen Sie diesen Selektor bei einem individuellen Theme an das Suchfeld Ihres Themes an.

Hybridmodus

Mit aktiviertem Hybridmodus (empfohlen) kombiniert das Modul den semantischen Score mit einem Keyword-Abgleich am Produktnamen. So werden exakte Namenstreffer bevorzugt, ohne die semantische Relevanz zu opfern.

Schwellenwert und Ergebnisanzahl

Der minimale Ähnlichkeitswert (zwischen 0 und 0,99; empfohlen: 0,30) verwirft zu weit entfernte Ergebnisse. Das Feld maximale Ergebnisanzahl begrenzt die Anzahl der angezeigten Vorschläge.

Suchen analysieren

Jede Suche wird protokolliert (Anfrage, Sprache, Shop, Anzahl der Ergebnisse, bester Score). Diese Daten helfen Ihnen zu verstehen, wonach Ihre Kunden wirklich suchen, und ergebnislose Anfragen zu erkennen, um Ihren Katalog anzureichern.

Query-Cache

Die Embeddings der Kundenanfragen werden 30 Tage lang zwischengespeichert. Wiederholte Suchen sind so sofort verfügbar und werden vom Anbieter nicht erneut abgerechnet. Die Schaltfläche Query-Cache leeren ermöglicht es, ihn jederzeit zurückzusetzen.

Fehlerbehebung

• Es erscheinen keine Ergebnisse: Prüfen Sie, dass der Index aufgebaut ist (der Zähler „Indexierte Vektoren“ ist > 0) und dass der API-Schlüssel gültig ist.
• Die Autovervollständigung wird nicht angezeigt: Prüfen Sie den CSS-Selektor und dass die Autovervollständigung aktiviert ist. Detaillierte Fehlermeldungen werden in den PrestaShop-Protokollen aufgezeichnet.
• Timeouts während der Indexierung: Verringern Sie die Batch-Größe und bevorzugen Sie die Cron-Indexierung.
• Inkonsistente Ergebnisse nach einem Modellwechsel: Führen Sie einen vollständigen Neuaufbau des Index durch.