Bewertungsergebnisse und Fehlercluster analysieren

Hinweis

Damit Sie die Bewertungsergebnisse aufrufen und analysieren können, müssen folgende Voraussetzungen erfüllt sein:

• Führen Sie mindestens eine Evaluierung durch, wie unter KI-Agents bewerten oder Offline-Evaluierungen durchführen beschrieben.
• Sie haben einen Cloud Storage-Bucket für die Auswertungsausgabe konfiguriert, wenn Sie Offlinebewertungen ausführen.
• Optional: Wenn Sie das SDK zum Abrufen von Ergebnissen verwenden, muss Ihre Umgebung authentifiziert sein.

Nachdem Sie eine Bewertung ausgeführt haben, bietet die Agent Platform Diagnosetools, mit denen Sie die Ursachen von Fehlern ermitteln können. Sie können die Ergebnisse auf drei Ebenen analysieren: aggregierte Trends im Dashboard, semantische Gruppen in Fehlerclustern und detaillierte Logikpfade in einzelnen Traces.

Das Bewertungs-Dashboard für Online-Monitore

Für Agenten mit aktiven Online-Monitoren können Sie im Dashboard aggregierte Leistungstrends ansehen:

1. Rufen Sie in der Google Cloud Console die Seite Agent Platform > Agents auf.
2. Wählen Sie im linken Navigationsmenü Bereitstellungen aus.

3. Wählen Sie den Agent aus.

   Zu Deployments

4. Klicken Sie auf den Tab Dashboard und wählen Sie den Unterabschnitt Bewertung aus.

• Leistungstrends:Hier können Sie visualisieren, wie sich die Werte für Messwerte wie Task Success oder Tool Use Quality in verschiedenen Agent-Versionen oder Zeiträumen ändern.
• Nullstatus:Bei Agents ohne aktive Online-Monitore werden in dieser Ansicht Abdeckungslücken ermittelt und ein Aufruf zum Handeln angezeigt, um mit der Bewertung zu beginnen.

Bewertungsergebnisse mit dem SDK ansehen

Sie können programmatisch auf die Bewertungsergebnisse zugreifen, indem Sie das Agent Platform SDK verwenden. Das SDK bietet integrierte interaktive Visualisierungen für Colab- und Jupyter-Notebook-Umgebungen, in denen sowohl zusammengefasste Messwerte als auch detaillierte Ergebnisse für einzelne Fälle angezeigt werden.

Rufen Sie nach der Ausführung einer Analyse .show() für das Ergebnisobjekt auf, um einen interaktiven Bericht direkt in Ihrem Notebook zu rendern:

from vertexai import evals, types

# Run an evaluation
result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.RubricMetric.FINAL_RESPONSE_QUALITY,
        types.RubricMetric.TOOL_USE_QUALITY,
        types.RubricMetric.HALLUCINATION,
        types.RubricMetric.SAFETY,
    ],
)

# Visualize aggregate and per-case results in your notebook
result.show()

Die Visualisierung enthält:

• Zusammenfassende Messwerte:Aggregierte Werte für alle Testläufe, einschließlich des Durchschnittswerts und der Bestehensrate für jeden Messwert.
• Ergebnisse pro Fall:Einzelne Bewertungen für jeden Testfall, die Sie maximieren können, um detaillierte Ergebnisse zu sehen.

Das folgende Beispiel zeigt die zusammengefassten Messwerte aus result.show():

Sie können einzelne Testläufe maximieren, um die Ergebnisse pro Messwert, die Bewertungsschema-Entscheidungen und die Begründungen zu sehen:

Bewertungsergebnisse interpretieren

Vordefinierte Messwerte geben Ergebnisse in zwei Formaten zurück, je nach Messwerttyp:

• Mit adaptiven Rubrikmesswerten werden Rubriken automatisch auf Grundlage der Konfiguration des KI-Agenten und des Nutzerprompts generiert. Jede Rubrik erhält ein individuelles Bestanden- oder Nicht bestanden-Ergebnis mit einer Begründung in natürlicher Sprache, in der die Argumentation des Judge-LLM erläutert wird. Der Gesamtwert entspricht der Bestehensrate, also dem Anteil der Rubriken, die das Ergebnis Bestanden erhalten haben.
• Statische Rubrikmesswerte verwenden einen festen Satz von Bewertungskriterien. Bei Hallucination wird die Antwort beispielsweise in atomare Behauptungen unterteilt und jede Behauptung wird anhand von Beweisen für die Tool-Nutzung geprüft. Sicherheitsprüfungen auf personenidentifizierbare Informationen, Hassrede, gefährliche Inhalte und andere Richtlinienverstöße. Diese Messwerte geben einen einzelnen numerischen Wert (0 bis 1) zurück.

Fehler identifizieren und priorisieren

Nachdem Sie die Bewertungsergebnisse geprüft haben, müssen Sie als Nächstes systematische Fehlermuster identifizieren und priorisieren, um Ihren Agent zu verbessern. Die Agent Platform bietet die automatische Verlustanalyse, bei der die Signale für „Bestanden“ oder „Nicht bestanden“ aus rubrikbasierten Messwerten analysiert, Fehler in vordefinierte Verlustmuster klassifiziert und in semantische Cluster gruppiert werden. So können Sie nicht nur dass Ihr Agent fehlgeschlagen ist, sondern auch warum und wie er fehlgeschlagen ist, besser nachvollziehen.

Auf Fehlercluster in der Console zugreifen

1. Rufen Sie die Seite Agent Platform > Agents > Evaluation auf.
2. Wählen Sie den Tab Bewertungen aus.
3. Klicken Sie auf den Namen eines abgeschlossenen Testlaufs, um den Bericht zu öffnen.
4. Wenn bei der Auswertung Cluster erkannt wurden, werden sie im Bericht im Bereich Fehlercluster angezeigt.

Fehlercluster mit dem SDK generieren

Sie können Fehlercluster auch programmatisch mit der Methode generate_loss_clusters generieren:

# Generate failure clusters from evaluation results
loss_clusters = client.evals.generate_loss_clusters(
    eval_result=result,
)

# Visualize the loss pattern analysis in your notebook
loss_clusters.show()

Das folgende Beispiel zeigt die Analyse des Verlustmusters aus loss_clusters.show():

Taxonomien für Verlustmuster

Bei der automatischen Verlustanalyse wird jeder Fehler in ein oder mehrere vordefinierte Verlustmuster eingeordnet. Diese Muster sind konkret und umsetzbar und lassen sich direkt bestimmten Bereichen Ihres Agenten zuordnen, die Sie verbessern können.

Es gibt zwei vordefinierte Taxonomien, die jeweils auf einen bestimmten Messwert ausgerichtet sind:

Taxonomie für erfolgreiche Agent-Aufgaben

Diese Taxonomie wird für den Messwert Erfolg von Multi-Turn-Aufgaben des KI-Agents (multi_turn_task_success_v1) verwendet. Sie umfasst allgemeine Verhaltensfehler des KI-Agents in Bezug auf Halluzinationen, Befolgung von Anweisungen, Tool-Aufrufe, Verarbeitung von Tool-Ausgaben und Tool-Qualität:

Kategorie	Verlustmuster	Beschreibung
Halluzination	Halluzination von Aktionen	Der Agent gibt an, eine Aktion abgeschlossen zu haben, ohne den erforderlichen Tool-Aufruf auszuführen.
	Halluzinationen von fehlenden Informationen	Der Agent erfindet ein Detail (z. B. einen Wert, eine Tatsache oder ein Datum), das in der Nutzeranfrage oder der Tool-Ausgabe nicht vorhanden ist.
	Halluzination von Tool oder Funktion	Der KI‑Agent gibt an, ein Tool oder eine Funktion zu haben, die er nicht besitzt.
Befolgung von Anweisungen	Beschränkungsverstoß	Der Agent führt die Aufgabe aus, verstößt dabei aber gegen explizite Nutzerbeschränkungen (z. B. Formatierungsregeln oder negative Einschränkungen).
	Sinnlose Aktion (Unter-Punting)	Der Agent führt eine irrelevante Aktion aus, anstatt anzugeben, dass die Aufgabe mit den verfügbaren Tools nicht möglich ist.
	Unvollständige Ausführung	Der Agent führt eine Aufgabe nur teilweise aus, bricht sie vorzeitig ab oder fragt unnötige Berechtigungen für explizit angeforderte Schritte an.
	Over-Punting	Der Agent lehnt eine Aufgabe ab, weil er angeblich nicht über ein Tool oder eine Funktion verfügt, die er tatsächlich besitzt.
Toolaufrufe	Falsche Toolauswahl	Der Agent wählt das falsche Tool aus den verfügbaren Optionen aus.
	Semantisch falsche Toolparameter	Der Toolaufruf ist syntaktisch gültig, enthält aber einen logischen oder semantischen Fehler in den Parameterwerten.
	Syntaktisch falscher Toolaufruf	Der Toolaufruf enthält Syntaxfehler, erforderliche Parameter fehlen oder es sind ungültige Argumentwerte enthalten.
Umgang mit Tool-Ausgabe	Falsche Verarbeitung der Tool-Ausgabe	Der Kundenservicemitarbeiter erhält eine gültige Tool-Ausgabe, extrahiert, verarbeitet oder interpretiert die Informationen jedoch falsch.
Tool-Qualität	Unzureichende Toolausgabe	Das Tool wird erfolgreich ausgeführt, gibt aber nicht genügend oder keine Daten zurück, die für die weitere Verarbeitung durch den Agenten erforderlich sind.
	Tool-Fehler	Das Tool schlägt aufgrund von Infrastrukturproblemen fehl, z. B. Authentifizierungsfehler, Zeitüberschreitungen oder interne Fehler.

Taxonomie für die Qualität der Toolnutzung

Diese Taxonomie wird mit dem Messwert Qualität der Multi-Turn-Toolnutzung durch den KI-Agenten (multi_turn_tool_use_quality_v1) verwendet. Sie konzentriert sich speziell auf die Korrektheit von Tool-Aufrufen und die Verarbeitung von Tool-Antworten:

Kategorie	Verlustmuster	Beschreibung
Halluzination	Halluzination von Parameterwerten	Der Agent erfindet einen bestimmten Wert für einen Parameter, der vom Nutzer nicht angegeben wurde oder nicht aus dem Kontext abgeleitet werden kann.
	Halluzination von Tools	Der KI-Agent versucht, eine Funktion aufzurufen, die in seinem definierten Toolset nicht vorhanden ist.
Toolaufrufe	Parameter konnte nicht festgelegt werden	Der Agent lässt einen Parameter aus, der zur Erfüllung der Einschränkungen des Nutzers erforderlich ist, und verwendet stattdessen einen unbeabsichtigten Standardwert.
	Falscher Datentyp für Parameter	Der Agent gibt für einen Parameter einen Wert des falschen Datentyps an, z. B. einen String, wenn eine Ganzzahl erforderlich ist.
	Falsche Parameterzuordnung	Der Agent weist einem falschen Parameter einen Wert zu, z. B. indem er Start- und Enddatum vertauscht.
	Falscher Parameterwert	Der Kundenservicemitarbeiter gibt einen Parameterwert an, der logisch oder sachlich falsch ist, oder wendet erforderliche Datentransformationen nicht an.
	Falsche Toolauswahl	Der Agent wählt die falsche Funktion aus seinem verfügbaren Toolset aus.
	Ungültige Syntax für Tool-Aufruf	Der KI-Agent generiert einen Funktionsaufruf mit einem Syntaxfehler, der das Parsen oder die Ausführung verhindert.
	Nicht vorhandener Parameter	Der Agent enthält ein Parameterargument, das nicht in der Signatur des Tools definiert ist.
	Erforderlicher Toolaufruf wurde ausgelassen	Der KI-Agent führt eine erforderliche Funktion nicht aus, indem er direkt antwortet, einen Teil einer zusammengesetzten Anfrage oder einen erforderlichen Schritt überspringt.
	Zu wenig Punting	Der Agent erzwingt einen Tool-Aufruf, wenn er mit natürlicher Sprache antworten sollte, z. B. um um Klärung zu bitten oder eine Anfrage abzulehnen, die nicht in den Aufgabenbereich fällt.
Antwort des Tools	Irrelevante Tool-Antwort	Das Tool wird erfolgreich ausgeführt, gibt aber Daten zurück, die für die spezifische Anfrage des Nutzers nicht relevant sind.
	Toolfehler	Das Tool gibt aufgrund eines externen Problems (z. B. API-Ausfall oder ungültige Berechtigungen) einen expliziten Fehler- oder Fehlerstatus zurück.

Empfohlener Triage-Workflow

Gehen Sie so vor, um Auswertungsfehler systematisch zu beheben:

1. Beginnen Sie mit den zusammenfassenden Messwerten, um die Messwerte mit der niedrigsten Punktzahl in Ihrem Bewertungs-Dataset zu ermitteln.
2. Ergebnisse nach Fall aufschlüsseln, um bestimmte Testläufe zu finden, die fehlgeschlagen sind.
3. Fehlercluster generieren, um systematische Verlustmuster bei Fehlern zu erkennen.
4. Traces aufschlüsseln, um den genauen Zug oder Tool-Aufruf zu finden, bei dem der Fehler aufgetreten ist. Rufen Sie in der Console Agent Platform > Agents > Deployments auf, wählen Sie Ihren Agent aus und öffnen Sie den Tab Traces (Traces). Wählen Sie einen Trace aus, um den vollständigen Unterhaltungsverlauf und die genaue Reihenfolge der Modelleingaben, Tool-Aufrufe und Antworten zu sehen.
5. Grundursache ermitteln: Verwenden Sie die Kategorie für das Verlustmuster, um festzustellen, ob es sich um ein Problem mit dem Prompt, ein Problem mit der Toolkonfiguration oder ein Datenproblem handelt.
6. Eine gezielte Korrektur anwenden: Sie können die Systemanweisungen, Tool-Definitionen oder Few-Shot-Beispiele des Agents korrigieren.
7. Führen Sie die Auswertung noch einmal aus und vergleichen Sie die Werte, um die Verbesserung zu überprüfen.