Visuelle Bildersuche & Shop the Look mit KI — Komplettanleitung

Dieses Modul fügt Ihrem Shop die bildbasierte Produktsuche hinzu: Der Kunde zieht ein Foto hinein und erhält die visuell ähnlichsten Artikel Ihres Katalogs, sortiert nach Ähnlichkeitsscore. Der Modus Shop the Look erkennt jeden Artikel einer vollständigen Szene und schlägt die passenden Produkte vor. Die Engine ist anbieterunabhängig: Sie wählen den KI-Anbieter (Voyage, Cohere, OpenAI oder Mistral) und verwenden Ihren eigenen Schlüssel. Dieser Leitfaden behandelt Installation, Konfiguration, Katalog-Indexierung und die Funktionsweise der Suche.

Installation

1. Laden Sie das Archiv dfvisualsearch.zip aus Ihrem DataFirefly-Konto herunter.
2. PrestaShop-Backoffice → Module → Modul hochladen → ZIP senden.
3. Das Modul legt seine Index-Tabelle an, registriert seine Hooks und fügt einen eigenen Admin-Tab hinzu.

Allgemeine Konfiguration

Gehen Sie zu Module → Visuelle Bildersuche & Shop the Look KI → Konfigurieren.

Anbieter wählen

Wählen Sie die Engine aus der Liste und geben Sie den passenden API-Schlüssel ein. Sie zahlen die KI beim Anbieter nach Verbrauch, ohne vom Modul hinzugefügtes Abonnement.

• Voyage und Cohere: direkte multimodale Bild-Embeddings.
• OpenAI und Mistral: Vision-Analyse und anschließendes Embedding, schalten zusätzlich Shop the Look frei.
• API-Schlüssel: serverseitig gespeichert, nie im Front-Office sichtbar. Jeder Anbieter hat sein eigenes konfigurierbares Modell und seine Vektordimension.

Verhalten

• Anzahl der Ergebnisse: wie viele Produkte bei einer Bildsuche angezeigt werden.
• Mindestähnlichkeit (0–1): 0 zeigt alles nach Relevanz sortiert; erhöhen Sie ihn (z. B. 0,2 bis 0,4), um schwache Treffer auszuschließen. Pro Anbieter abstimmen.
• Shop the Look aktivieren und Produkte pro erkanntem Artikel.
• Ähnliche Produkte auf der Produktseite und deren Anzahl.
• Kamera-Button in den Header einfügen oder ihn manuell in Ihrem Theme über den Hook displayDfVisualSearchButton platzieren.
• Maximale Upload-Größe und automatische Neuindexierung beim Speichern eines Produkts.

Den Katalog indexieren

Im Panel Katalog-Index der Konfiguration:

1. Klicken Sie auf Katalog indexieren / neu indexieren: Das Modul verarbeitet die Produkte in Stapeln, mit Fortschrittsbalken, ohne Risiko eines Server-Timeouts.
2. Der Zähler zeigt die Produkte, die für den aktiven Anbieter indexiert sind.
3. Index leeren entfernt die Vektoren des aktuellen Shops.

Die Indexierung wandelt das Titelbild jedes Produkts in einen in der Datenbank gespeicherten Vektor um. Einmal indexiert, wird ein Produkt nur neu kodiert, wenn sich sein Bild ändert.

Wie die Suche funktioniert

Jedes Bild wird in einen normalisierten Vektor (Embedding) umgewandelt. Das vom Kunden gesendete Foto wird vom selben Anbieter kodiert und dann per Kosinus-Ähnlichkeit mit dem Index verglichen — was sich bei normalisierten Vektoren auf ein einfaches Skalarprodukt reduziert. Die Produkte werden nach absteigendem Score sortiert und nach der konfigurierten Mindestschwelle gefiltert.

• Voyage und Cohere kodieren das Bild direkt.
• OpenAI und Mistral beschreiben das Bild mit einem Vision-Modell und kodieren dann diese Beschreibung: Indexierung und Abfrage leben so im selben Vektorraum.

Shop the Look

Aus einem Szenenfoto identifiziert Shop the Look jeden sichtbaren Artikel und startet eine Suche pro Artikel, wobei die Ergebnisse in getrennten Gruppen dargestellt werden.

Visuell ähnliche Produkte

Auf der Produktseite erscheint automatisch ein Block „visuell ähnliche Produkte“. Er verwendet den bereits bei der Indexierung berechneten Vektor wieder: Es wird keine zusätzliche Anfrage an die KI gesendet, sodass die Empfehlung keine laufenden Kosten verursacht.

Anzeige für den Kunden

Der Kamera-Button öffnet ein Fenster, in das der Kunde ein Foto per Drag-and-drop zieht oder auswählt. Eine Vorschau erscheint, dann werden die Ergebnisse als Produktkarten mit ihrem Ähnlichkeitsscore in Prozent angezeigt. Ist Shop the Look aktiviert, kann der Kunde die Option ankreuzen, um die Ergebnisse nach erkanntem Artikel gruppiert zu erhalten.

Einen Anbieter wählen

Alle Anbieter beherrschen die Bildsuche. Die Wahl hängt von Ihren Anforderungen ab:

• Voyage / Cohere: direkte multimodale Embeddings, einfach und schnell, ohne Shop the Look.
• OpenAI / Mistral: Vision-Analyse, die die Mehr-Artikel-Erkennung von Shop the Look freischaltet.

Kompatibilität und technische Hinweise

• PrestaShop 1.7.6 bis 9.x, Multishop und mehrsprachig; jeder Shop führt seinen eigenen Index.
• Legacy-Admin-Controller (kein Symfony-Controller) für die PS8/PS9-Kompatibilität.
• Verwendete Hooks: displayHeader, displayTop, displayDfVisualSearchButton, displayFooterProduct, actionProductSave, actionProductDelete.
• Vektoren normalisiert in der Datenbank gespeichert, für eine robuste Speicherung kodiert; Suche per Skalarprodukt.
• Ein Missbrauchsschutz pro Sitzung schützt Ihr KI-Kontingent.
• AJAX-Such-Endpunkt über den Modul-Link; JSON-Antwort.

FAQ und Fehlerbehebung

Der Such-Button erscheint nicht. Prüfen Sie, ob ein Anbieter konfiguriert und sein Schlüssel gültig ist (Button Anbieter testen), und ob die Header-Einfügung aktiviert oder der Hook in Ihrem Theme platziert ist.

Die Suche liefert keine Ergebnisse. Stellen Sie sicher, dass der Katalog für den aktiven Anbieter indexiert wurde, und senken Sie die Mindestähnlichkeit, falls sie für den Vektorraum des Anbieters zu hoch ist.

Shop the Look liefert nur eine Gruppe. Der aktive Anbieter unterstützt keine Erkennung (Voyage oder Cohere). Wechseln Sie zu OpenAI oder Mistral für die Mehr-Artikel-Erkennung und indexieren Sie neu.

Ich habe den Anbieter gewechselt und die Ergebnisse sind inkonsistent. Führen Sie eine vollständige Neuindexierung durch: Die Vektoren müssen im Raum des neuen Anbieters neu berechnet werden.