Fehlerbehebung

Diese Seite fasst die Probleme zusammen, die uns am häufigsten begegnen, und wie sie sich beheben lassen. Für eine tiefergehende Diagnose wird jeder KI-Aufruf im API-Protokoll (KI-Assistent → API-Protokolle) mit der vollständigen Anfrage, Antwort, den Token, der Dauer und dem Fehler erfasst.

Das Menü „KI-Assistent“ erscheint nach der Installation nicht

Vergewissern Sie sich, dass das Plugin unter Erweiterungen → Meine Erweiterungen aktiviert ist.
Leeren Sie den Administrations-Cache: bin/console cache:clear.
Laden Sie die Administration neu (Strg+Umschalt+R), damit der Browser das neue Bundle abruft.
Wenn Sie die Administration selbst bauen, führen Sie bin/build-administration.sh erneut aus.
Prüfen Sie, ob Ihre Benutzerrolle Zugriff auf die neuen ACL-Schlüssel hat.

„Invalid API key“ beim Testen einer Verbindung

Kopieren Sie den Schlüssel erneut aus dem OpenAI-Dashboard. Die meisten Fehlschläge entstehen durch unsichtbaren Leerraum am Ende.
Wenn Sie OpenAI über ein Gateway leiten, prüfen Sie die Base URL doppelt und stellen Sie sicher, dass Ihr Gateway den Header Authorization weiterleitet.

Aufträge bleiben im Zustand „running“ stecken

Prüfen Sie, ob bin/console messenger:consume async tatsächlich läuft und sich nicht in einer Absturzschleife befindet.
Wenn ein Worker mitten in einem Auftrag abgestürzt ist, reiht das Plugin solche Aufträge alle paar Minuten automatisch neu ein. Warten Sie einen Zyklus ab und prüfen Sie erneut.
Wenn ein Auftrag sich immer wieder erholt, aber nie abschließt, öffnen Sie das API-Protokoll gefiltert nach der ID dieses Auftrags — ein echter Fehler wird wiederholt.

Aufträge im Status „suspended“

Ausgesetzte Aufträge stecken nicht fest — sie wurden pausiert, weil der Anbieter einen behebbaren Fehler zurückgegeben hat (am häufigsten: Kontingent überschritten, Zahlung erforderlich, Rate-Limit). Der Auftrag merkt sich das nächste unverarbeitete Element, sodass Sie keinen Fortschritt verlieren.

Öffnen Sie den API-Protokolleintrag am Auftrag, um die genaue Anbieter-Meldung zu sehen.
Laden Sie Ihr KI-Konto auf, erhöhen Sie das Kontingent oder stellen Sie den Auftrag auf eine andere KI-Verbindung um.
Klicken Sie beim Auftrag auf Fortsetzen. Der Worker macht dort weiter, wo er aufgehört hat.

Inline-Bearbeitungen oder Aufträge erzeugen leere Ausgabe

Öffnen Sie den API-Protokolleintrag für den betroffenen Aufruf. Der vollständige Antwort-Body steht dort.
Häufige Ursache: Der Prompt forderte eine JSON-Struktur an, das Modell lieferte aber Fließtext. Bearbeiten Sie den User-Prompt des Prompts, um das Modell an das Schema zu erinnern (und führen Sie vor dem Speichern einen Test am Produkt aus).
Eine weitere häufige Ursache: Das Quellfeld (Beschreibung, Name) ist leer. Das Modell hat nichts, womit es arbeiten kann.

„URL fetch failed“ in `describe_from_url`

Die URL muss aus dem ausgehenden Netzwerk des Shopware-Hosts erreichbar sein.
Das Plugin extrahiert nur dann Inhalte, wenn für den Host der URL eine passende Fetch-Domain-Konfiguration existiert. So erstellen Sie eine:
1. Führen Sie die Inline-Aktion Suggest fetch domain config gegen die URL aus — das Modell schlägt CSS-Selektoren vor.
2. Speichern Sie den Vorschlag unter KI-Assistent → Fetch-Domain-Konfiguration.
3. Führen Sie die ursprüngliche Aktion erneut aus.

Cache zeigt veralteten Prompt-Inhalt

Aufgelöste Prompt-Vorlagen werden pro Worker-Prozess zwischengespeichert. Nach dem Bearbeiten eines Prompts:

Warten Sie auf die Cache-TTL, oder
Starten Sie die Worker neu: bin/console messenger:stop-workers und lassen Sie sie vom Supervisor neu starten, oder
Klicken Sie auf Am Produkt testen — der Testpfad umgeht den Cache für diese Vorlage.

Vorschlag kann nicht angewendet werden / „version conflict“

Das Produkt wurde zwischen dem KI-Aufruf und der Anwendung bearbeitet (oder es wurde eine neue Version erstellt). Öffnen Sie das Produkt erneut, aktualisieren Sie und wenden Sie es erneut an.

Wachstum des API-Protokolls / Speicherplatzverbrauch

Jeder KI-Aufruf wird mit seiner vollständigen Anfrage und Antwort protokolliert, sodass das Protokoll in stark frequentierten Shops schnell wächst. Das Plugin bereinigt alte Einträge automatisch einmal täglich, um es begrenzt zu halten. Wenn Sie unkontrolliertes Wachstum feststellen, prüfen Sie, ob der Runner für geplante Aufgaben von Shopware aktiviert ist — ohne ihn läuft weder die automatische Protokollbereinigung noch die Wiederherstellung hängender Aufträge.

Wo Sie zuerst nachsehen

API-Protokolle — jeder Aufruf mit seinen vollständigen Nutzdaten und seinem Ergebnis. Filtern Sie nach Datum, Typ oder Verbindung.
Auftragsdetailseite — bei Stapelproblemen verrät Ihnen der Status pro Element, welcher Schritt fehlgeschlagen ist.
Kostendiagramm — unerwartete Kostenspitzen deuten in der Regel auf eine unbeabsichtigte Aktivierung einer Funktion hin.

Wenn Sie die Ursache dennoch nicht finden, ist die API-Protokollzeile des fehlgeschlagenen Aufrufs das Artefakt, das Sie mit dem Support teilen sollten.