Markdown (Eisvogel)

itkchatbot-anwenderdokumentation.md

---
title: "ItkChatbot"
subtitle: "Anwenderdokumentation"
author: ["André Fischer"]
date: "30-03-2026"
lang: de
titlepage: true
titlepage-color: "1E3A5F"
titlepage-text-color: "FFFFFF"
titlepage-rule-color: "4A90D9"
titlepage-rule-height: 4
toc: true
toc-own-page: true
numbersections: true
header-left: "ItkChatbot"
header-right: "Anwenderdokumentation"
footer-left: "ITK Computer GmbH"
---

# Zweck und Funktionsumfang

Du betreibst einen Shopware-Shop und willst Besuchern **sofort Antworten** geben – teils automatisch per **KI**, teils persönlich per **Live-Chat** vom Team. Genau dafür ist **ITK Live-Chat & KI-Chatbot** gedacht (technischer Name **ItkChatbot**): ein **einziges Widget** im Storefront, in dem du KI und menschlichen Support kombinieren oder nur eine der beiden Varianten einschalten kannst. Technisch bündelt das Plugin zwei getrennte Funktionen im gleichen Widget:

1. **KI-Chat**: Automatische Antworten über ein externes Sprachmodell (z. B. Ollama lokal oder ein OpenAI-kompatibler Dienst). Kontext kommt aus der **Wissensbasis**, optional aus **semantischer Suche (Embeddings/RAG)**, aus **Shop-Daten** (Produkt-/Kategorielisten oder eingebettete Shop-Daten) und aus der **aktuellen Seite** (z. B. Produktkontext).
2. **Live-Chat**: Echtzeit-Chat zwischen Kunde und Mitarbeitenden im Shopware-Admin, inkl. Sessions, Übernahme („Claim“), interne Notizen, Nachrichtenvorlagen (Presets) und Produktverknüpfung in Nachrichten.

Das Widget erscheint nur, wenn mindestens eine der Optionen **KI-Chat aktivieren** oder **Live-Chat aktivieren** für den jeweiligen **Sales Channel** eingeschaltet ist.

Ergänzend gibt es einen **Bad-Word-Filter** (Moderation), der für Kunden-Nachrichten im Live-Chat greift und optional auch für Mitarbeiter-Nachrichten aktivierbar ist.

---

## Diagramm: Ein Widget zwei Wege

```mermaid
flowchart TB
  W[Storefront Widget]
  W --> K[KI Chat LLM]
  W --> L[Live Chat Mitarbeiter]
  K --> KB[Wissensbasis und Kontext]
  L --> A[Admin Einstellungen]
```

# Wo du alles findest

| Bereich | Ort im Admin |
|--------|----------------|
| Plugin-Konfiguration | **Erweiterungen → Meine Erweiterungen** → **ITK Live-Chat & KI-Chatbot** → **Konfiguration** (pro Sales Channel wählbar) |
| Wissensbasis | Im Menü unter **Einstellungen** |
| Live-Chat Bedienung | Im Menü unter **Einstellungen** |

---

# Konfiguration: LLM-API

Diese Felder steuern, wie der Shop mit dem Sprachmodell spricht.

| Feld | Bedeutung |
|------|-----------|
| **API-URL** | Pflicht. Endpunkt des LLM, z. B. Ollama `http://…:11434/api/generate` oder ein OpenAI-kompatibler Chat-Endpunkt. |
| **API-Key** | Optional, falls der Endpunkt Authentifizierung verlangt. |
| **API-Format** | **Ollama (prompt)** – klassischer Prompt/Response-Flow. **OpenAI-kompatibel (messages)** – Chat-Verlauf als Nachrichtenliste. **Custom (Ollama + CSV-Middleware)** – wie Ollama, aber für eine eigene Middleware, die zusätzlich aufbereiteten Kontext wie z. B. CSV-Daten einblendet. |
| **Modell-Name** | Optional; wird an den Endpunkt übergeben, falls erforderlich. |
| **Timeout (Sekunden)** | Abbruch bei zu langsamer API (Standard 30). |
| **Max Tokens** | Obergrenze für die Antwortlänge (Standard 512). |
| **SSL-Zertifikatsprüfung deaktivieren (nur API)** | Nur für Tests oder interne Dienste mit „falschem“ Zertifikat; in Produktion möglichst aus. |

---

# Konfiguration: Embeddings / RAG (semantische Suche)

Wenn aktiviert, werden Anfragen nicht nur per Stichwort, sondern über **Bedeutungsähnlichkeit** mit Einträgen der Wissensbasis und optional mit **Produkt- und Kategorie-Embeddings** abgeglichen.

| Feld | Bedeutung |
|------|-----------|
| **Semantische Wissenssuche aktivieren** | Schaltet Embedding-Suche für die Wissensbasis ein. Benötigt laufendes Embedding-Modell (z. B. Ollama **nomic-embed-text**). |
| **Embedding-API-URL** | z. B. `http://…:11434/api/embed`. Leer = Ableitung aus der LLM-URL (`…/generate` → `…/embed`). |
| **Embedding-Modell** | Standard **nomic-embed-text**; Modell muss auf dem Embedding-Host geladen sein. |
| **Anzahl relevanter Einträge (Top-K)** | Wie viele Wissens-Abschnitte maximal in den Kontext dürfen. |
| **SSL für Embedding-API deaktivieren** | Wie bei der LLM-API, nur für Embedding-Calls. |
| **Semantische Produktsuche** / **Semantische Kategoriesuche** | Bindet per Embedding passende Produkte/Kategorien ein. **Voraussetzung:** einmalig CLI `itk:chatbot:embeddings:generate-shop` ausführen (und bei großen Änderungen wiederholen). |
| **Max. Produkte im Kontext** / **Max. Kategorien im Kontext** | Top-K für Shop-Embeddings. |

---

# Konfiguration: KI-Chat (Verhalten & UX)

| Feld | Bedeutung |
|------|-----------|
| **KI-Chat aktivieren** | Wenn aus, ist der KI-Teil im Widget deaktiviert (404 auf die Nachrichten-Route). |
| **Name des Chatbots** | Anzeige im Chat-Header; leer = Shopware-Übersetzung. |
| **Start- / Willkommensnachricht** | Erste Nachricht; **HTML erlaubt** (Absätze, Listen, Fettung). |
| **Rate-Limit (Anfragen pro Minute, 0 = aus)** | Standard 20. Schützt vor Missbrauch und vor API-Kosten; basiert auf **Session** (nicht global pro IP). |
| **Neue-Nachricht-Sound** | Optional URL zu MP3 o. Ä., wird bei Bot-Antwort abgespielt. |
| **Chat in Cookie speichern** | Verlauf bleibt über Seitenwechsel erhalten. **Nur sinnvoll mit passender Cookie-Einwilligung.** |
| **Cookie-Consent-Cookie (optional)** | Wenn gesetzt, wird nur gespeichert/wiederhergestellt, wenn dieses Cookie existiert (Name wie euer Consent-Tool). Leer bei aktiviertem Speichern = immer speichern (rechtlich mit Marketing/Consent abstimmen). |
| **Shop-Daten (Produkte/Kategorien) in Kontext einbinden** | Wenn an, fließen strukturierte Shop-Listen in den KI-Kontext (wenn aus, eher nur Wissensbasis + Embeddings). |

---

# Konfiguration: Live-Chat

| Feld | Bedeutung |
|------|-----------|
| **Live-Chat aktivieren** | Zeigt den Wechsel zwischen KI und Live-Support im Widget. |
| **Öffnungszeiten (JSON)** | Array von Objekten mit **day** (0 = Sonntag … 6 = Samstag), **start**, **end** im Format `HH:MM`. Leer = Chat technisch immer „offen“ für neue Nachrichten; außerhalb der Zeiten kann trotzdem geschrieben werden, der Kunde erhält dann die **geschlossene Nachricht** als Info. |
| **Zeitzone** | Auswahl z. B. Europe/Berlin für die Öffnungszeit-Prüfung. |
| **Live-Chat Willkommensnachricht** | HTML erlaubt. |
| **Nachricht außerhalb der Öffnungszeiten** | Wird als **infoMessage** zurückgegeben, wenn der Kunde außerhalb der Zeiten sendet; Nachricht wird **trotzdem gespeichert**. |

**Hinweis für Gäste:** Beim Start eines Live-Chats ohne Login erzeugt das System ein **Session-Token**; der Browser muss es bei Folge-Requests mitsenden, sonst wird die Session abgewiesen (Sicherheit).

---

# Konfiguration: Bad Word Filter

| Feld | Bedeutung |
|------|-----------|
| **Bad Word Filter aktivieren** | Schaltet die Moderation ein. |
| **Liste der zu filternden Wörter** | Komma- oder zeilengetrennt. |
| **Filter-Modus** | Ganze Wörter (empfohlen), Teilwörter (strenger), Regex (nur für Experten). |
| **Groß-/Kleinschreibung beachten** | Standard nein. |
| **Aktion** | Nachricht **blockieren**, **ersetzen** oder **zensieren** (`*******`). |
| **Ersatztext** | Bei Ersetzen/Zensieren. |
| **Fehlermeldung** | Bei Blockieren, wird dem Kunden angezeigt. |
| **Filter auch auf Mitarbeiter** | Standard nein; nur aktivieren, wenn gewollt. |

---

# Wissensbasis pflegen

Jeder Eintrag hat typischerweise **Titel**, **Inhalt**, optional **Sales Channel**, **aktiv**, **Sortierung**. Qualität der KI-Antworten hängt stark davon ab, ob Themen **kleinteilig** und **faktisch** gepflegt sind (ein Eintrag = ein Thema).

Nach Änderungen an der Wissensbasis: bei aktivierter semantischer Suche Embeddings neu erzeugen (`itk:chatbot:embeddings:generate`), sonst findet die Suche alte Vektoren.

---

# Live-Chat im Alltag

- **Liste:** Offene Sessions und von dir übernommene Sessions; **ungelesene Kundennachrichten** werden markiert.
- **Übernehmen:** Erst übernehmen, dann antworten – vermeidet parallele Bearbeitung.
- **Befehle im Eingabefeld:** z. B. **/preset …**, **/product …**, `/close` (siehe Admin-Schulung / Entwicklerdoku).
- **Polling:** Das Admin-UI fragt regelmäßig nach neuen Nachrichten; für sofortige Push-Benachrichtigungen ist das Plugin nicht ausgelegt – Tab offen lassen oder Monitoring extern ergänzen.

---

# CLI-Befehle (Kurzreferenz)

| Befehl | Zweck |
|--------|--------|
| **php bin/console itk:chatbot:products-csv:warmup** | CSV mit Produkten/Kategorien für Middleware/Export vorbereiten (optional mit Sales-Channel-ID). |
| **php bin/console itk:chatbot:knowledge:optimize** | Wissensbasis analysieren/aufräumen (Optionen siehe `--help`). |
| **php bin/console itk:chatbot:embeddings:generate** | Embeddings für Wissenseinträge. |
| **php bin/console itk:chatbot:embeddings:generate-shop** | Embeddings für Produkte und Kategorien (**-f** / `--force` für Neuaufbau). |

---

# Logs und typische Probleme

| Logdatei | Inhalt |
|----------|--------|
| `var/log/itk_chatbot.log` | KI-Anfragen, Fehler, Rate-Limit, Kontext-Debug, allgemeine Plugin-Fehler. |
| `var/log/itk_chatbot_embeddings.log` | Embedding-Generierung und Shop-Embeddings. |

**KI antwortet nicht / 503:** API-URL leer oder Host nicht erreichbar; Firewall, VPN, Timeout prüfen.

**502 mit Fehlertext:** Antwort der LLM-API fehlerhaft oder Parsing schlägt fehl – Log prüfen.

`429:` Rate-Limit pro Session überschritten – warten oder Limit in der Config erhöhen.

**Schwache Antworten:** Wissensbasis ergänzen; Embeddings aktualisieren; **Shop-Daten**-Schalter und **Top-K** prüfen.

**Öffnungszeiten falsch:** Zeitzone in der Config und Serverzeit prüfen; JSON-Syntax der Öffnungszeiten validieren.

---

# FAQ

**Kann ich nur Live-Chat ohne KI?**  
Ja – KI aus, Live-Chat an (und umgekehrt).

**Warum sieht der Kunde das Widget nicht?**  
Mindestens eine der beiden Optionen muss für den **Sales Channel** aktiv sein; Theme/Cache prüfen.

**Muss ich Ollama nutzen?**  
Nein – jeder **OpenAI-kompatible** Chat-Endpunkt oder der **Custom**-Modus mit Middleware ist möglich, sofern das Format passt.

**Wie oft Embeddings neu berechnen?**  
Nach größeren Änderungen an Wissen oder Katalog; sonst „vergisst“ die semantische Suche den neuen Stand.