Traces mit menschlichem Feedback versehen (Vorschau)

Important

Elemente, die in diesem Artikel als Vorschau gekennzeichnet sind, befinden sich derzeit in der Vorschau. Diese Vorschau wird ohne Service Level Agreement (SLA) bereitgestellt, und Microsoft empfiehlt sie nicht für Produktionsworkloads. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar. Weitere Informationen finden Sie unter Supplementale Nutzungsbedingungen für Microsoft Azure Previews.

Fügen Sie Traces in Microsoft Foundry „Daumen hoch“- oder „Daumen runter“-Anmerkungen hinzu, um menschliche Qualitätssignale zu einzelnen Agentinteraktionen zu erfassen. Mit Anmerkungen zur Ablaufverfolgung können Sie markieren, ob die Antwort eines Agenten hilfreich oder nicht hilfreich war. Diese Anmerkungen werden direkt auf der Detailseite der Ablaufverfolgung angezeigt, sodass Sie Verhaltensmuster des Agenten schnell erkennen können.

Trace-Annotationen unterstützen zwei Arbeitsabläufe:

Builder-Anmerkungen: Builder und Domänenexpert:innen annotieren Traces aus dem Foundry-Portal, während sie Agenteninteraktionen überprüfen. Diese Annotationen werden automatisch mit der Quelle builder gekennzeichnet.
Endbenutzerfeedback: Protokollieren Sie Annotationen programmgesteuert über Ihre Anwendung, wenn Endbenutzer Feedback mit „Daumen hoch“ oder „Daumen runter“ geben. Diese Anmerkungen haben die Quelle end_user und werden auf der Trace-Seite zusammen mit Builder-Anmerkungen angezeigt. Ausführliche Informationen zum Protokollieren von Endbenutzerfeedback finden Sie unter Protokollieren von Endbenutzerfeedback.

Alle Annotationen werden dem Trace angehängt – das Hinzufügen einer Builder-Annotation überschreibt oder ersetzt niemals vorhandenes Endbenutzer-Feedback und umgekehrt. Jede Anmerkung trägt ein Quellattribute, sodass die Signale unabhängig abfragbar und gefiltert werden können.

Voraussetzungen

Ein Foundry-Projekt mit einer verbundenen Application Insights-Ressource. Weitere Informationen finden Sie unter Ablaufverfolgung einrichten.
Die in Ihrer Anwendung konfigurierte OpenTelemetry-Instrumentierung. Anweisungen zum Einrichten finden Sie unter Set up tracing in Microsoft Foundry.
Für programmatische Annotationen: die Pakete azure-ai-projects und azure-monitor-opentelemetry installiert.
```
pip install "azure-ai-projects>=2.0.0" azure-monitor-opentelemetry python-dotenv
```
Für programmgesteuerte Anmerkungen, die Microsoft Entra authentifizierte Application Insights-Erfassung verwenden: Die Identität, die Telemetrie ausgibt, hat auf der verbundenen Application Insights-Ressource die Rolle Monitoring Metrics Publisher. Informationen zur Einrichtung und identitätsspezifische Hinweise finden Sie unter Konfigurieren der Microsoft Entra-Authentifizierung für die Tracedatenerfassung.

Standardbewertungsvorlage

Jedes Foundry-Projekt ist standardmäßig mit einer Vorlage für die Bewertung mit „Daumen hoch“ oder „Daumen runter“ vorkonfiguriert, die ohne zusätzliche Einrichtung sofort verfügbar ist. Sie können bereits ab dem ersten Tag Annotationen zu Traces hinzufügen. Die Standardvorlage verwendet binäre Pass/Fail-Bewertung:

Daumen nach oben = Punktzahl 1.0, Beschriftung pass
Daumen nach unten = Bewertung 0.0, Beschriftung fail

Jede Bewertungsvorlage erfordert, dass das gen_ai.evaluation.name Attribut den Wert task_completion aufweist, sodass jede Anmerkung auf eine bestimmte Auswertungsdimension zurückzuführen ist. task_completion unterstützt „Daumen hoch“ und „Daumen runter“.

Traces im Foundry-Portal kommentieren

Fügen Sie Anmerkungen direkt auf der Detailseite der Ablaufverfolgung hinzu, um Ihre Bewertung der Antworten des Agenten zu erfassen.

Öffnen Sie Ihr Foundry-Projekt, und wechseln Sie in der linken Navigationsleiste zu Ablaufverfolgung.
Wählen Sie einen Trace aus, um die Trace-Detailansicht zu öffnen.
Wählen Sie auf der Detailseite der Ablaufverfolgung die Schaltfläche " Kommentieren " in der oberen rechten Ecke aus.
Wählen Sie "Daumen nach oben " oder " Daumen nach unten " aus, um Ihre Bewertung zu übermitteln. Fügen Sie optional eine Freitexterklärung hinzu.
Die Annotation wird sofort gespeichert und erscheint im Trace.

Hinweis

Das Anzeigen einer Ablaufverfolgung und das Speichern einer Anmerkung sind separate Autorisierungsvorgänge. Wenn die Ablaufverfolgung sichtbar ist, die Anmerkung jedoch nicht gespeichert werden kann, überprüfen Sie das Anmerkungsziel, die tatsächliche Schreibidentität und den Authentifizierungspfad. Eine andere Trace-Reader-Rolle gewährt keinen Telemetrie-Schreibzugriff.

Anmerkungen, die Sie im Portal hinzufügen, werden automatisch mit folgenden Tags versehen:

microsoft.gen_ai.human_evaluation.source = "builder"
microsoft.gen_ai.evaluation.actor.type = "human"

Bearbeitung der Bewertung

Jeder Benutzer kann mehrfach annotieren:

Mehrere Benutzer können jeweils ihre eigene Annotation desselben Typs zum selben Trace hinzufügen.
Vorherige Anmerkungen werden in Application Insights nicht gelöscht. Neue Anmerkungen werden angefügt, und im Portal werden alle Anmerkungen im Abschnitt " Anmerkungsverlauf " des Anmerkungsbereichs angezeigt.

Feedback von Endbenutzern als Trace-Anmerkungen protokollieren

Wenn Endbenutzer in Ihrer Anwendung Feedback mit „Daumen hoch“ oder „Daumen runter“ geben, können Sie dieses Feedback protokollieren, sodass es in der entsprechenden Ablaufverfolgung als Annotationen angezeigt wird. Dieser Ansatz verwendet das OpenTelemetry-Ereignis gen_ai.evaluation.result, wobei das Feedback automatisch mit dem ursprünglichen Trace korreliert wird.

Schema für Annotationsattribute

Verwenden Sie die folgenden Attribute, wenn Sie eine „Daumen hoch“- oder „Daumen runter“-Annotation erstellen:

Attribute	Wert	Beschreibung
`gen_ai.evaluation.name`	`task_completion`	Auswertungsmetrikname
`gen_ai.evaluation.score.value`	`1.0` (Daumen nach oben) oder `0.0` (Daumen nach unten)	Numerischer Wert
`gen_ai.evaluation.score.label`	`"pass"` oder `"fail"`	Kategoriebezeichnung
`gen_ai.evaluation.explanation`	Optionaler Freitextkommentar	Erläuterung des Prüfers
`gen_ai.response.id`	Beispiel: `"chatcmpl-123"`	KI-Antwort-ID, die verwendet wird, um die Anmerkung mit der nachverfolgten Antwort zu korrelieren
`microsoft.gen_ai.human_evaluation.source`	`"end_user"` oder `"builder"`	Feedbackanbietertyp
`microsoft.gen_ai.evaluation.actor.type`	`"human"`	Gibt an, dass die Anmerkung von einem menschlichen Prüfer übermittelt wurde und von automatisierten Auswertungen unterscheidet.
`operation_Id`	`trace_Id`	Verknüpft die Annotation mit der ursprünglichen Traceanforderung in Application Insights
`operation_ParentId`	`span_Id`	Enthält die Span-ID des spezifischen Spans innerhalb des zu kommentierenden Traces
`gen_ai.agent.id`	Bezeichnerzeichenfolge der Agent-Ressource	Eindeutiger Bezeichner des Agents, der die Antwort generiert hat, die kommentiert wurde
`gen_ai.agent.name`	Anzeigename des Agents	Anzeigename des Agents, der die Antwort generiert hat, die kommentiert wurde
`gen_ai.agent.version`	Versionszeichenfolge `1`, `2`, oder `3`	Befindet sich innerhalb von `internal_properties`, Version des Agents zum Zeitpunkt der Erstellung der kommentierten Antwort

Sie müssen das Auswertungs-Ereignis innerhalb desselben Trace-Kontexts (unter Verwendung derselben Trace-ID und Span-ID) auslösen wie die Agent-Interaktion, die damit kommentiert wird. Diese Zuordnung stellt sicher, dass die Annotation im Portal auf dem richtigen Trace angezeigt wird.

Ein vollständiges Runnable-Beispiel finden Sie unter sample_human_evaluations.py.

Annotationen auf der Trace-Seite anzeigen

Nachdem Sie Anmerkungen (aus dem Portal oder programmgesteuert) hinzugefügt haben, werden sie auf der Detailseite der Ablaufverfolgung angezeigt.

Öffnen Sie Ihr Foundry-Projekt, und wechseln Sie zur Ablaufverfolgung.
Wählen Sie einen Trace mit Annotationen aus.
Auf der Trace-Detailseite werden Anmerkungssymbole neben den kommentierten Spans angezeigt. Ein Symbol mit Daumen nach oben zeigt positive Rückmeldung an, und ein Symbol mit Daumen nach unten zeigt negative Rückmeldung an.
Zeigen Sie mit der Maus auf eine Anmerkung, um Metadaten anzuzeigen, einschließlich des Quellnamens (builder oder end_user), des Auswertungsnamens und des Zeitstempels.

In der Listenansicht der Ablaufverfolgungen werden Anmerkungen in kompakter Form angezeigt: Nur die neueste Anmerkung wird inline angezeigt, und wenn für eine Ablaufverfolgung mehrere Anmerkungen vorhanden sind, weist der Hinweis „+X mehr“ darauf hin, dass weitere Anmerkungen verfügbar sind. Wählen Sie den Trace aus, um alle Annotationen anzuzeigen.

Traces nach Annotation filtern

Sie können die Trace-Liste nach folgenden Kriterien filtern:

Auswertungstyp (gen_ai.evaluation.name): Wert ist "task_completion".
Bewertungswert oder Bezeichnung (gen_ai.evaluation.score.value, gen_ai.evaluation.score.label): Zeigen Sie beispielsweise nur Traces mit einer „Daumen-runter“-Bewertung an.
Quelle (microsoft.gen_ai.human_evaluation.source): Nur Generatoranmerkungen oder nur Endbenutzerfeedback anzeigen.

Diese Filterdimensionen erscheinen neben den vorhandenen Trace-Filtern (Zeitbereich, Agent, Status, Modell).

Abfrageanmerkungen in Application Insights

Alle Anmerkungen werden in Azure Monitor / Application Insights veröffentlicht und an die ursprüngliche Trace angehängt. Sie können Anmerkungen mithilfe von Kusto Query Language (KQL) abfragen, um Feedbackmuster zu analysieren, Dashboards zu erstellen oder Warnungen einzurichten.

Zusammenfassen von Feedback nach Quelle und Tag

customEvents
| where name == "gen_ai.evaluation.result"
| extend
    eval_name = tostring(customDimensions["task_completion"]),
    score = todouble(customDimensions["gen_ai.evaluation.score.value"]),
    label = tostring(customDimensions["gen_ai.evaluation.score.label"]),
    eval_source = tostring(customDimensions["microsoft.gen_ai.human_evaluation.source"]),
    trace_id = tostring(customDimensions["trace_id"])
| where eval_source in ("builder", "end_user")
| summarize
    thumbs_up = countif(score == 1.0),
    thumbs_down = countif(score == 0.0),
    total = count()
  by eval_source, bin(timestamp, 1d)
| order by timestamp desc

Traces mit negativem Feedback finden

customEvents
| where name == "gen_ai.evaluation.result"
| extend
    eval_name = tostring(customDimensions["task_completion"]),
    score = todouble(customDimensions["gen_ai.evaluation.score.value"]),
    eval_source = tostring(customDimensions["microsoft.gen_ai.human_evaluation.source"]),
    explanation = tostring(customDimensions["gen_ai.evaluation.explanation"]),
    trace_id = tostring(customDimensions["trace_id"])
| where score == 0.0
| project timestamp, trace_id, eval_name, eval_source, explanation
| order by timestamp desc

Fehlerbehebung bei Schreibvorgängen für Anmerkungen

Symptom	Prüfen
Sie können eine Ablaufverfolgung anzeigen, aber das Speichern einer Builder-Anmerkung schlägt mit einem Autorisierungsfehler fehl.	Behandeln Sie die Speicherung als separaten Schreibvorgang. Bestätigen Sie die verbundene Application Insights-Ressource, die für den Schreibvorgang verwendete Identität und den Verbindungsauthentifizierungsmodus. Fügen Sie keine weitere Reader-Rolle als generischen Fix hinzu.
Eine programmgesteuerte Anmerkung gibt zurück `401` oder `403`	Vergewissern Sie sich, dass die Anwendung Telemetrie an die erwartete Application Insights-Ressource sendet. Gewähren Sie für die mit Microsoft Entra authentifizierte Erfassung der Telemetrieidentität für diese Ressource die Rolle Herausgeber von Überwachungsmetriken.
Die Anwendung meldet Erfolg, aber die Anmerkung wird nicht angezeigt.	Vergewissern Sie sich, dass das Auswertungsereignis den ursprünglichen Ablaufverfolgungs- und Span-Kontext verwendet, dass es an dieselbe Application Insights-Ressource wie die Ablaufverfolgung gesendet wurde und dass die Aufnahme abgeschlossen wurde.
Eine Anmerkung wird in der falschen Ablaufverfolgung angezeigt	Überprüfen Sie `operation_Id`, `operation_ParentId` und `gen_ai.response.id`, bevor Sie das Ereignis auslösen.

Feedback

War diese Seite hilfreich?

Zuletzt aktualisiert um 2026-10-08