Betrieb & Qualität

KI-Debug & kontinuierliche Verbesserung

Der Bereich „KI-Debug" ist Ihr Selbstbedienungs-Werkzeugkasten für Qualität: Hier finden Sie heraus, warum der Assistent so geantwortet hat, beheben verpasste Antworten selbst und beweisen mit Tests, dass eine Änderung wirklich etwas verbessert hat. Sie erreichen den Bereich über Agenten → [Ihr Agent] → KI-Debug. Die Seite ist in fünf Reiter (Tabs) gegliedert: „Übersicht", „Abruf-Test", „Turn-Traces", „Eval" und „Routing-Beispiele". Dazu kommt der „Entscheidungs-Fluss", den Sie direkt aus jeder Konversation öffnen.

Dieser Abschnitt führt Sie einmal durch die komplette Verbesserungs-Schleife: Gesundheit lesen → verpasste Antwort finden und Schwelle anpassen → eine einzelne Antwort im Detail prüfen → mit Daumen runter bewerten und per Klick als Trainingsbeispiel übernehmen → ein Test-Set aufbauen → mit dem Eval beweisen, dass es jetzt besser ist.

Kurz vorab — was „Distanz" bedeutet: Der Assistent sucht passende Wissens-Abschnitte über eine sogenannte Cosinus-Distanz (0 = inhaltlich identisch, 2 = völlig entgegengesetzt). Ein Abschnitt wird normalerweise nur verwendet, wenn seine Distanz unter der Schwelle (kb_max_distance, Standard 0,5) liegt. Neuerdings arbeitet die Suche „recall-first": Wenn gar nichts die Schwelle unterschreitet, wird trotzdem der beste Beinahe-Treffer verwendet (im Entscheidungs-Fluss gelb als „Recall-Fallback" markiert). So bekommt der Kunde lieber eine großzügige Antwort als gar keine — aber ein hoher Recall-Fallback-Anteil ist ein Signal, dass Ihre Daten oder die Schwelle nachjustiert gehören.

18.1 Reiter „Übersicht" — die Wissens-Gesundheit lesen

Die Übersicht zeigt aggregierte Kennzahlen über alle aufgezeichneten Gespräche eines Zeitraums. Das ist Ihr Startpunkt: ein schneller Gesundheits-Check, bevor Sie ins Detail gehen.

Schritt 1: Zeitraum wählen. Oben gibt es drei Schalter — „7T", „30T" und „90T" (Tage). Voreingestellt sind 30 Tage. Empfehlung: 30 Tage für den Alltag, 7 Tage direkt nach einer Änderung (um die Wirkung schnell zu sehen).

Schritt 2: Die Kennzahlen-Kacheln lesen. Jede Kachel färbt sich grün/gelb/rot, je nachdem ob der Wert gut ist:

„Qualitätsindex" — Gesamtnote von 0 bis 100. Grün ab 70, gelb ab 40, darunter rot. Ihre wichtigste Einzelzahl.
„Wissens-Trefferquote" — Anteil der Turns, bei denen passendes Wissen das Modell erreicht hat. Grün ab 80 %, gelb ab 50 %.
„Kein-Kontext-Quote" — Anteil der Turns ganz ohne Wissens-Kontext. Wird ab 20 % rot. Hohe Werte = Wissenslücken oder zu strenge Schwelle.
„Recall-Fallback-Quote" — Anteil der Wissens-Turns, die nur über den großzügigen Beinahe-Treffer beantwortet wurden. Wird ab 30 % gelb. Hoch = Ihre Inhalte passen nur knapp; ein Zeichen, sauberen Text nachzuladen oder die Schwelle anzuheben.
„Einbettungs-Fehler" — Anteil fehlgeschlagener Frage-Einbettungen (technischer Fehler, z. B. OpenAI-Schlüssel/Rate-Limit). Jeder Wert über 0 ist rot und sollte nicht vorkommen.
„Iterationslimit-Quote" — Anteil der Turns, die das interne Schritt-Limit erreicht haben. Wird ab 10 % gelb.
„Aufgezeichnete Turns" — Gesamtzahl im Zeitraum, mit Hinweis, wie viele davon mit aktiver Wissensdatenbank liefen.
„Abruf p50 (ms)" — typische (mittlere) Suchdauer in Millisekunden, dazu der p95-Wert (die langsamen 5 %).
„Beste Distanz p50" — typische beste Distanz pro Turn. Je kleiner, desto besser passt Ihr Wissen zu den echten Fragen.

Schritt 3: Detail-Listen darunter prüfen.

„Distanz-Verteilung" — ein Balkendiagramm, das zeigt, bei welchen Distanzen Ihre Treffer landen. Grün = hat das Modell erreicht. Viele Balken knapp rechts der Schwelle? Dann verpassen Sie knappe Treffer.
„Häufigkeit der Markierungen" — wie oft technische Markierungen wie no_kb_context oder kb_recall_fallback auftraten.
„Häufigste fehlschlagende Fragen" — die Kundenfragen, die am öftesten ohne Wissen blieben. Diese Liste ist Gold: Kopieren Sie sie direkt in den Abruf-Test (Reiter 2), um den Fehler nachzustellen.
„Abgerufene Dokumente" / tote Dokumente — zeigt, wie viele Ihrer Dokumente überhaupt je genutzt wurden. Ein „totes Dokument" wurde im Zeitraum nie abgerufen — entweder überflüssig, schlecht formuliert oder mit zu niedrigem Qualitäts-Score (unter 50 rot markiert).

Schritt 4 (optional): Report exportieren. Über die Leiste rechts oben können Sie den Bericht als „Markdown kopieren", „JSON kopieren" oder „.md herunterladen" — praktisch, um ihn mit dem Support oder im Team zu teilen.

18.2 Reiter „Abruf-Test" — eine verpasste Antwort finden und beheben

Dies ist das mächtigste Werkzeug im Bereich. Es führt die Wissens-Suche für eine Testfrage aus — ohne den Assistenten/das Modell tatsächlich antworten zu lassen (kostengünstig und ohne Nebenwirkung). Sie sehen genau, welche Abschnitte gefunden wurden, welche knapp daneben lagen und warum.

Oben wählen Sie den Modus: „Einzelne Frage" (Standard) oder „Sammel-Audit".

Einzelne Frage

Schritt 1: Frage eingeben. Tippen Sie eine echte Kundenfrage in das große Textfeld, z. B. „Was kostet die gebratene Ente?". Tipp: Mit ⌘/Strg + Enter starten Sie direkt.

Schritt 2 (optional): Max. Distanz übersteuern. Das Feld „Max. Distanz" lässt Sie testweise eine andere Schwelle ausprobieren. - Was es tut: Begrenzt, wie „weit weg" ein Abschnitt noch verwendet wird. Größer = großzügiger (mehr, aber unsicherere Treffer). - Standard: Leer = es wird die gespeicherte Schwelle des Agenten verwendet, sonst der globale Standard 0,5. Der Platzhalter zeigt Ihnen den aktiven Wert an. - Grenzen: 0,0 bis 2,0; Schrittweite 0,05. - Empfehlung: Lassen Sie es zunächst leer, damit Sie sehen, was der Kunde real erlebt. Erst danach experimentieren.

Schritt 3: „Abruf starten" klicken. Sie erhalten:

Ergebnis-Banner — entweder grün („n Abschnitt(e) haben das Modell erreicht.") oder rot („Für diese Frage hat kein Wissen das Modell erreicht."). Darunter eine Zusammenfassung: geprüfte Kandidaten, beste Distanz, verwendete Schwelle und top_k.
Empfehlungs-Box (blau): Erscheint, wenn ein knapp verpasster Abschnitt mit einer höheren Schwelle gerettet werden könnte — z. B. „Eine Schwelle von 0,61 würde den besten verpassten Abschnitt einbeziehen." Mit zwei Knöpfen:
„Anwenden & neu ausführen" — probiert die empfohlene Schwelle nur testweise aus (noch nicht gespeichert).
„Beim Agenten speichern" — übernimmt die Schwelle dauerhaft für diesen Agenten (Ein-Klick-Fix). Bestätigung: „Schwelle beim Agenten gespeichert."
„Distanz-Verteilung" — dasselbe Histogramm wie in der Übersicht, mit gestrichelter Schwellen-Linie.
Kandidaten-Tabelle — jeder gefundene Abschnitt mit Distanz-Balken (grün = verwendet), einem „Ergebnis"-Etikett (verwendet / Recall-Fallback / über Schwelle / unter top_k) und einer Inhalts-Vorschau. So sehen Sie sofort, welcher Abschnitt fehlte oder warum er rausfiel.
„An das Modell gesendeter Kontextblock" — der exakte Text, den der Assistent zur Antwort bekommen hätte.
Wissensdatenbank-Übersicht — alle Dokumente mit Typ, Status, Qualität, Abschnitts- und Zeichenzahl. Sehr kurze Dokumente (unter 200 Zeichen) und niedrige Qualität werden rot markiert.

Die typische Reparatur-Schleife: Frage testen → kein Treffer → Empfehlung speichern oder (besser bei Dreck-Treffern) das betreffende Dokument als sauberen Text neu hochladen → erneut testen, bis es grün ist.

Sammel-Audit

Statt einer Frage prüfen Sie viele auf einmal — ideal zur Inhalts-Kontrolle.

Schritt 1: Entweder eine Frage pro Zeile eintippen, oder das Feld leer lassen und über „Letzte Nachrichten" die letzten echten Kundennachrichten testen (Standard 20, erlaubt 1–50; das Feld ist gesperrt, sobald Sie eigene Fragen eingeben).

Schritt 2: „Audit starten". Sie erhalten eine Tabelle mit je einer Zeile pro Frage: gefundene Abschnitte (⚠ bei Einbettungs-Fehler), beste Distanz und „Fix bei" (die Schwelle, die diesen Treffer retten würde). Zeilen ganz ohne Treffer sind rot hinterlegt — Ihre To-do-Liste.

18.3 Reiter „Turn-Traces" — vergangene Antworten forensisch prüfen

Hier liegen die gespeicherten Detail-Aufnahmen echter Antworten („Traces"). Jeder Trace hält den exakten Prompt, die Suche, die Zeiten und alle Werkzeug-Aufrufe fest.

Schritt 1: Optional den Schalter „Nur fehlgeschlagene / markierte Turns" aktivieren, um direkt zu den Problemfällen zu springen.

Schritt 2: Die Tabelle zeigt Zeit, Kundennachricht, Wissen (verwendet/gesehen), Tokens, Dauer (ms) und Markierungen. Eine Zeile anklicken öffnet den Detail-Dialog mit: - Kundennachricht und Finale Antwort, - „Phasen-Timings" (Wasserfall: wie lange Suche und LLM-Aufrufe dauerten), - „Abruf-Kandidaten" (dieselbe Distanz-Tabelle wie im Abruf-Test), - aufklappbar: „Zusammengesetzter System-Prompt", „Gesendete Nachrichten" und der rohe JSON-Block (LLM-Aufrufe, Tools, Timings, Fehler). - Auch hier exportieren Sie alles per Markdown/JSON/Download.

Hinweis zum Datenschutz: Traces enthalten Nachrichtentexte, werden daher beim Speichern PII-bereinigt, automatisch nach Ablauf gelöscht und bei einer DSGVO-Löschung des Kontakts mit entfernt.

18.4 Der „Entscheidungs-Fluss" + Daumen-Feedback (in der Konversation)

Den Entscheidungs-Fluss öffnen Sie nicht hier, sondern direkt in einer Konversation: Unter jeder Assistenten-Antwort finden Sie eine kleine Aktionsleiste.

Schritt 1: Bewerten. Klicken Sie Daumen hoch („Gute Antwort") oder Daumen runter („Schlechte Antwort"). Bei Daumen runter klappt automatisch ein Korrektur-Bereich auf.

Schritt 2: „Entscheidung ansehen". Öffnet den „Entscheidungs-Fluss" — eine Ablauf-Darstellung (n8n-Stil) der einen Antwort, von oben nach unten: Nachricht → Routing → Tools → Wissen → LLM → Tool-Aufrufe → Antwort. Jeder Knoten hat eine Ampel (grün/gelb/rot). Klicken Sie einen Knoten an, öffnet sich rechts ein Detail-Inspektor — beim Wissens-Knoten z. B. eine „Retrieval-Distanzkarte": jeder Kandidat als Punkt auf einer Achse, grüne Zone = innerhalb der Schwelle (verwendet), rote Zone = verworfen, mit Schwellen-Markierung. Der informativste Knoten ist automatisch vorausgewählt. Ein Recall-Fallback wird als gelber Knoten mit dem Hinweis „Recall-Fallback (großzügiger Treffer)" angezeigt.

Schritt 3: Bei Daumen runter die Ursache festhalten. Im Korrektur-Bereich: - „Was ist schiefgelaufen?" — eine Kategorie wählen: Falsches Tool, Falsches Routing, Schlechte Antwort, Wissen fehlte oder Sonstiges. - Notiz — optionales Freitextfeld.

Schritt 4: Per Ein-Klick zu Trainingsdaten befördern. Genau hier schließt sich die Schleife — drei Übernahme-Optionen:

„Routing korrigieren — als Beispiel für Thema:" Wählen Sie das richtige Thema (Wissen, Termine, Bestellung, Lead, Smalltalk), dann „Routing-Beispiel übernehmen". Die vorangehende Kundennachricht wird (auf 150 Zeichen gekürzt) als Routing-Beispiel für dieses Thema gespeichert — der Router lernt, solche Fragen künftig richtig zuzuordnen. (Erscheint im Reiter „Routing-Beispiele".)
„Die richtige Antwort beibringen:" Bearbeiten Sie im Feld die Antwort, die richtig gewesen wäre, dann „Beispielantwort übernehmen". Das speichert ein Frage→Antwort-Paar (Few-Shot-Beispiel), an dem sich der Assistent künftig orientiert.
„Zum Eval-Set hinzufügen" — macht aus diesem Turn einen dauerhaften Regressionstest (siehe Reiter „Eval"). Die Kundennachricht wird zur Test-Eingabe, Ihre Korrektur (falls vorhanden) zur Referenzantwort, Ihre Notiz zum Bewertungskriterium und das gewählte Thema zum erwarteten Thema.

Nach erfolgreicher Übernahme erscheint ein grünes „Übernommen"-Etikett an der Nachricht.

18.5 Reiter „Eval" — beweisen, dass eine Änderung wirkt

Der Eval-Harness ist Ihr Regressionstest: Sie sammeln „Golden-Fälle" (vorbildliche Frage→Antwort-Paare), spielen sie auf Knopfdruck erneut durch und lassen jede Antwort von einem LLM-Richter bewerten — ohne echte Nebenwirkungen (keine Buchungen, keine E-Mails).

Schritt 1: Golden-Fälle anlegen. Im unteren Bereich „Golden-Fälle" auf „Fall hinzufügen" klicken und ausfüllen: - Name (Pflicht, 1–200 Zeichen) — z. B. „Öffnungszeiten". - Eingabe (Pflicht, 1–4000 Zeichen) — die Kundennachricht zum Erneut-Abspielen. - Referenzantwort (optional, bis 8000 Zeichen) — die ideale Antwort; gibt dem Richter einen Maßstab.

Mit „Fall speichern" sichern. Jeder Fall trägt eine Quelle (manual / feedback / trace) — Fälle, die Sie aus einer Konversation befördert haben, erscheinen automatisch hier mit Quelle feedback. Fälle löschen Sie über das Papierkorb-Symbol. Empfehlung: 10–20 Fälle, die Ihre häufigsten und kniffligsten echten Fragen abdecken.

Schritt 2: „Eval starten". Der Knopf oben rechts ist erst aktiv, sobald mindestens ein Fall existiert. Der Lauf spielt alle aktiven Fälle durch und bewertet sie. Abschluss-Meldung: „Eval fertig: X/Y bestanden".

Schritt 3: Ergebnisse lesen. Links die „Läufe"-Historie (jeder Lauf mit Datum und Bestehensquote als Prozent-Badge — grün ab 80 %, gelb ab 50 %, sonst rot). Klicken Sie einen Lauf an, zeigt „Ergebnisse" rechts: - die Bestehensquote groß (z. B. 85 %, 17/20), - drei Durchschnittsnoten des Richters: „Hilfreich", „Korrekt" und „Tool" (passende Werkzeugwahl), - darunter jeder Fall mit Haken (bestanden) oder Kreuz (durchgefallen), der tatsächlich erzeugten Antwort, der Begründung des Richters und den Einzelnoten (Hilfreich/Korrekt/Tool).

Schritt 4: Die Schleife schließen. Eval vor einer Änderung laufen lassen → Änderung vornehmen (Schwelle, Wissen, Persona, Routing-Beispiele) → Eval erneut laufen lassen → Quoten der beiden Läufe vergleichen. Steigt die Quote, hat die Änderung messbar geholfen. Sinkt sie, haben Sie eine Verschlechterung erkannt, bevor echte Kunden sie merken.

18.6 Reiter „Routing-Beispiele" — die Themenzuordnung schärfen

Hier hinterlegen Sie pro Thema Beispielsätze, die Kunden wirklich verwenden. Der Router nutzt sie (zusammen mit FAQ, Menü und Services), um jede Nachricht an die richtige Fähigkeit zu schicken.

Schritt 1: Pro Themenkarte über „Phrase hinzufügen" Beispielsätze eintragen, z. B. unter „Wissen / Fragen" den Satz „Was kostet die Ente?". Welche Themen erscheinen, hängt vom Agententyp ab (Restaurant, Termine, Vertrieb, Support); Standard sind alle: Wissen / Fragen, Termine buchen, Bestellungen, Vertrieb / Leads, Begrüßung / Small Talk.

Schritt 2: Grenzen beachten — jede Phrase 4 bis 150 Zeichen (zu kurz/lang wird rot umrandet), max. 10 Phrasen pro Thema und max. 30 insgesamt (der Gesamt-Zähler oben wird rot, sobald 30 überschritten sind — dann lässt sich nicht speichern).

Schritt 3: Mit „Phrasen speichern" sichern („Routing-Phrasen gespeichert."). Leere Felder werden automatisch verworfen. Lassen Sie ein Thema leer, gelten sinnvolle Standardwerte.

Verbindung zur Schleife: Wenn Sie in einer Konversation eine Antwort als Falsches Routing markieren und „Routing-Beispiel übernehmen" klicken (Abschnitt 18.4), landet die Phrase automatisch hier. Sie können sie anschließend hier feinschleifen.

Tipps & Stolpersteine

Erst diagnostizieren, dann drehen. Lassen Sie das Feld „Max. Distanz" beim ersten Abruf-Test leer — so sehen Sie, was der Kunde real erlebt. Erst danach experimentieren oder die Empfehlung speichern.
Dreckige gecrawlte Seiten blähen die Distanz auf. Wenn ein Dokument viel Navigations- und Footer-Text enthält („Boilerplate"), wirken selbst gute Abschnitte „weit weg" und werden verpasst. Die bessere Reparatur ist dann nicht die Schwelle hochzudrehen, sondern den sauberen Text neu hochzuladen. Achten Sie auf tote Dokumente und niedrige Qualitäts-Scores (rot) in der Übersicht.
Recall-Fallback ist eine Krücke, kein Sieg. Eine gelbe „Recall-Fallback"-Markierung heißt: Es gab eigentlich keinen guten Treffer, der beste Beinahe-Treffer wurde aus Verzweiflung genommen. Eine hohe Recall-Fallback-Quote in der Übersicht ist ein klares Signal, Wissen nachzubessern.
Schwelle ist ein zweischneidiges Schwert. Höher = mehr Treffer, aber auch mehr falsche/irrelevante Abschnitte. Erhöhen Sie nur so weit, dass der gewünschte Abschnitt gerade hineinrutscht (die Empfehlung tut genau das) — nicht pauschal auf 2,0.
„über Schwelle" vs. „unter top_k" unterscheiden. „über Schwelle" heißt, der Abschnitt war zu weit weg — eine höhere Schwelle hilft. „unter top_k" heißt, der Abschnitt war nah genug, wurde aber durch zu viele andere verdrängt — hier hilft ein größeres top_k (Standard 5), nicht die Schwelle.
Eval braucht Fälle. Der „Eval starten"-Knopf bleibt grau, bis mindestens ein Golden-Fall existiert. Bauen Sie das Set früh auf — am einfachsten, indem Sie schlechte Antworten direkt aus Konversationen mit „Zum Eval-Set hinzufügen" übernehmen.
Immer vorher/nachher messen. Eine Schwellen- oder Wissens-Änderung „fühlt sich besser an" — beweisen lässt sie sich nur, indem Sie den Eval vor und nach der Änderung laufen lassen und die Bestehensquoten vergleichen.
Der Sammel-Audit spart Zeit. Statt 20 Fragen einzeln zu testen: Sammel-Audit mit „Letzte Nachrichten" laufen lassen — die rot hinterlegten Zeilen sind Ihre Reparatur-Liste.
Sammel-Audit und Tests kosten ein wenig. Der Sammel-Audit bettet bis zu 50 Fragen ein und respektiert das Tagesbudget (daily_budget_usd) des Agenten — ist das erreicht, wird der Lauf gestoppt. Plant das ein, wenn Sie ein enges Budget gesetzt haben.
Traces müssen aktiviert sein. Sind keine Traces vorhanden, wird nichts aufgezeichnet (oder die Aufzeichnung ist deaktiviert). Ohne Traces bleibt der Entscheidungs-Fluss leer („Für diese Antwort wurde kein Entscheidungs-Trace aufgezeichnet.").
Daumen runter ohne Übernahme bringt wenig. Die Bewertung allein verbessert den Agenten nicht automatisch — erst die Übernahme als Routing-Beispiel, Beispielantwort oder Eval-Fall macht daraus echtes Training. Nutzen Sie die Ein-Klick-Knöpfe konsequent.