Dokumentation · Technische Dokumentation

Technische Hinweise zum AI Assistant

Dieses Dokument beschreibt die optionale AI Assistant-Funktion, die SEO-orientierte Fahrzeugbeschreibungen, Bild-Alt-Texte, SEO-Metadaten und Ausstattungs-Highlights aus importierten Fahrzeugdaten generiert.

Die KI-Funktionen nutzen die verwaltete Google Gemini-Konfiguration im ADP Car Market Hub. Im WordPress-Backend ist keine Auswahl des Anbieters, des Modells oder die Eingabe eines API-Schlüssels erforderlich. Die kundenspezifische KI-Bereitstellung wird nach der Installation durch AD Promotion abgeschlossen.

Wann Sie dieses Dokument lesen sollten

Lesen Sie dieses Dokument, wenn Sie:

Entscheiden müssen, ob Sie den AI Assistant für Ihre Website aktivieren möchten.
Verstehen wollen, wie die Hintergrund-Warteschlange und die Generierung pro Import mit dem WP-Cron interagieren.
Das Sicherheitsmodell rund um die verwaltete Gemini-Konfiguration und die Admin-Trigger überprüfen möchten.

Übersicht

Der AI Assistant ist in AS24CI\Ai_Assistant implementiert. Wenn er aktiviert ist, kann er:

Automatisch eine Beschreibung als Teil des Import-Ablaufs generieren (eingehängt an as24ci_vehicle_imported).
Eine Warteschlange ausstehender Generierungen im Hintergrund über WP-Cron verarbeiten (as24ci_process_ai_queue).
Redaktoren ermöglichen, eine Beschreibung manuell über die Fahrzeug-Bearbeitungsmaske zu generieren oder neu zu generieren, sowohl über eine AJAX-Aktion als auch über eine einmalige Admin-Post-Aktion.

Die Funktion ist Opt-in: Sie tut nichts, bis as24ci_ai_assistant_enabled auf '1' gesetzt ist und die verwaltete Gemini-Konfiguration bereitgestellt wurde. Der Cron-Callback ist bedingungslos registriert, sodass alle zuvor geplanten Jobs aus einer früheren Konfiguration noch abgearbeitet werden können.

Verwaltete KI-Konfiguration

Das Plugin verwendet eine einzige verwaltete KI-Konfiguration, die von AS24CI\Ai_Config bereitgestellt wird. Die zuvor fest codierten Gemini-Schlüssel-/Modell-Konstanten in Ai_Config wurden entfernt; die Klasse ist nun eine schlanke Fassade über AS24CI\Ai_Credential_Manager:

Ai_Config::get_effective_model() — gibt das feste Gemini-Laufzeitmodell zurück, immer Ai_Credential_Manager::PRIMARY_MODEL (derzeit gemini-3.5-flash). Jeder über die API bereitgestellte Modellwert dient nur als Metadaten und steuert niemals die Auswahl zur Laufzeit.
Ai_Config::get_managed_gemini_api_key() — gibt den Gemini-Kundenschlüssel zurück, der aus dem verschlüsselten Anmeldedaten-Umschlag stammt, welcher Server-zu-Server von der API-Plattform synchronisiert wird. Gibt einen leeren String zurück, wenn die KI nicht ausgeführt werden kann (keine Berechtigung für die Lizenz ai_allowed oder keine gespeicherten Anmeldedaten). Wird niemals in der Admin-Benutzeroberfläche, in Diagnosen, Logs oder auf einer für Benutzer sichtbaren Oberfläche offengelegt.
Ai_Config::is_configured() — gibt nur dann true zurück, wenn ein verwendbarer verwalteter Gemini-Schlüssel verfügbar ist.

Die Legacy-Hilfsfunktionen von Ai_Assistant (get_api_key_for_provider(), get_model() usw.) bleiben aus Gründen der Abwärtskompatibilität erhalten und verweisen auf die verwalteten Gemini-Werte. Es gibt keinen Anbieter-Wechsel, kein feld für den API-Schlüssel pro Anbieter und keine Modellauswahl im WordPress-Backend.

Verfügbare Ausgabesprachen (de, en, fr, it), Tonalitäten (professional, emotional, technical) und Ziellängen (short, medium, long) sind als Klassenkonstanten in Ai_Assistant definiert.

Hintergrund-Warteschlange

Cron-Hook: as24ci_process_ai_queue.
Benutzerdefinierter Zeitplan: as24ci_every_5_minutes.
Batch-Grösse pro Durchlauf: bis zu 3 Fahrzeuge.
Maximale Versuche pro Fahrzeug: 3.
Begrenzung des Textauszugs: 160 Zeichen.

Die Warteschlange ermöglicht es dem Plugin, die KI-Generierung über Importe hinweg zu verteilen, ohne den Frontend-Request zu blockieren, der sie ausgelöst hat.

Schritt-für-Schritt-Anleitung

So aktivieren und konfigurieren Sie den AI Assistant:

Öffnen Sie den Admin-Tab AI Assistant.
Aktivieren Sie die Einstellung AI Assistant aktivieren (as24ci_ai_assistant_enabled = '1').
Wählen Sie eine Sprache, eine Tonalität, eine Ziellänge und (optional) einen benutzerdefinierten Prompt.
Entscheiden Sie, ob Automatisch beim Import generieren (as24ci_ai_assistant_auto_generate) aktiviert werden soll.
Speichern Sie und führen Sie einen Import aus oder lösen Sie eine einzelne Generierung in einer Fahrzeug-Bearbeitungsmaske aus, um die Verbindung zu überprüfen.

Die verwaltete Gemini-Konfiguration ist bereits eingerichtet — in der Admin-Benutzeroberfläche werden keine Felder für Anbieter, Modell oder API-Schlüssel angezeigt.

Manuelle Generierung

Es gibt zwei Admin-Pfade:

AJAX (as24ci_generate_ai_assistant) — wird von der Meta-Box auf der Fahrzeug-Bearbeitungsmaske verwendet. Erfordert die Berechtigung manage_as24_imports und die Nonce as24ci_ai_generate.
Admin-Post (as24ci_manual_ai_generate) — verarbeitet eine einmalige manuelle Generierung über die Schaltfläche Generieren. Erfordert die Post-spezifische Nonce as24ci_manual_ai_generate_<post_id> und die Berechtigung edit_post für das jeweilige Fahrzeug.

Beide Abläufe rufen letztendlich die verwaltete Gemini-Routine auf und schreiben das Ergebnis zurück in den Beitrag.

Admin-Hintergrund-Trigger

Das Plugin stellt die AJAX-Aktion as24ci_trigger_ai_queue_now bereit, die sofort einen Batch der KI-Warteschlange verarbeitet. Sie ist durch manage_as24_imports und die Nonce as24ci_trigger_ai_queue_now geschützt und gibt HTTP 400 zurück, wenn der AI Assistant deaktiviert ist.

Konfigurationsreferenz

Optionsschlüssel	Zweck
`as24ci_ai_assistant_enabled`	Hauptschalter. `'1'` aktiviert die Funktion.
`as24ci_ai_assistant_language`	Ausgabesprache (`de`, `en`, `fr`, `it`).
`as24ci_ai_assistant_tone`	Tonalität des Texts (`professional`, `emotional`, `technical`).
`as24ci_ai_assistant_max_length`	Ziellänge (`short`, `medium`, `long`).
`as24ci_ai_assistant_auto_generate`	Generieren während des Import-Ablaufs, wenn `'1'`.
`as24ci_ai_assistant_custom_prompt`	Optionale Prompt-Vorlage.

Die vollständige Liste der Plugin-Optionen finden Sie unter Speicherung von Optionen und Einstellungen.

Betriebliche Hinweise

Datenfluss an Drittanbieter: Wenn der AI Assistant aktiviert ist, verlassen Fahrzeugdaten und Prompt-Kontext den WordPress-Server und werden an den verwalteten Google Gemini-Endpunkt gesendet. Überprüfen Sie die geltenden Datenverarbeitungs- und Vertragsbedingungen für das verwaltete KI-Setup, bevor Sie KI-Funktionen in der Produktionsumgebung aktivieren.
Kosten und Kontingente: Die KI-Nutzung läuft über die von AD Promotion bereitgestellte verwaltete Gemini-Konfiguration. Das Plugin zeigt keine Preise pro Aufruf an.
Ratenbegrenzungen (Rate Limits): Gemini erzwingt Anfrage- und Token-Limits unabhängig vom Plugin. Fehlgeschlagene Generierungen werden bis zu 3-mal pro Fahrzeug wiederholt; dauerhaft fehlschlagende Fahrzeuge werden übersprungen, um Endlosschleifen zu vermeiden.
Die automatische Generierung wird nur bei Importen ausgelöst, wenn sowohl der Hauptschalter als auch die Option Automatisch generieren aktiviert sind. Die manuelle Generierung funktioniert immer (unabhängig von Automatisch generieren), wenn der Hauptschalter aktiviert ist.
Handhabung des verwalteten Schlüssels: Der verwaltete Gemini-Schlüssel wird Server-zu-Server von der API-Plattform bereitgestellt und von Ai_Credential_Manager verschlüsselt aufbewahrt. Er wird niemals im Klartext in wp_options geschrieben, in der Admin-Benutzeroberfläche angezeigt oder in Diagnosen oder Logs ausgegeben.
Das Deaktivieren der Funktion stoppt neue Generierungen, aber der registrierte Cron-Hook bleibt bestehen, damit bereits in der Warteschlange befindliche Jobs abgearbeitet werden können. Stellen Sie sicher, dass die Warteschlange leer ist, bevor Sie sich darauf verlassen, dass die Funktion vollständig ausgeschaltet ist.

Fehlerbehebung

Beim Import wird keine Beschreibung generiert — Überprüfen Sie, ob as24ci_ai_assistant_enabled auf '1' steht, Automatisch generieren aktiviert ist und Ai_Config::is_configured() den Wert true zurückgibt (verwalteter Schlüssel bereitgestellt). Suchen Sie im Plugin-Log nach Gemini-Fehlermeldungen.
Die manuelle Schaltfläche Generieren tut nichts — Überprüfen Sie den Netzwerk-Tab des Browsers. Ein Status 403 weist auf eine fehlende Berechtigung oder Nonce hin, ein Status 400 bedeutet, dass der AI Assistant deaktiviert ist.
Die Warteschlange wird nie abgearbeitet — WP-Cron erfordert regelmässigen Website-Traffic, um geplante Ereignisse auszulösen. Richten Sie einen externen Cronjob ein oder lösen Sie die Warteschlange manuell über die Admin-Aktion KI-Warteschlange jetzt auslösen aus. Siehe Cron-Ereignisse und Scheduler.
Dasselbe Fahrzeug erhält auch nach mehreren Versuchen keine Beschreibung — Der Versuchszähler pro Fahrzeug hat 3 erreicht. Untersuchen Sie den zugrunde liegenden Gemini-Fehler im Log, bevor Sie den Zähler zurücksetzen.