Traces annoteren met menselijke feedback (preview)

Important

Items die zijn gemarkeerd als voorbeeld in dit artikel, zijn momenteel beschikbaar als preview-versie. Deze preview wordt aangeboden zonder een service level agreement en Microsoft raadt dit niet aan voor productieworkloads. Bepaalde functies worden mogelijk niet ondersteund of hebben mogelijk beperkte mogelijkheden. Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure Previews voor meer informatie.

Voeg aantekeningen met duimen omhoog of duim omlaag toe aan traceringen in Microsoft Foundry om menselijke kwaliteitssignalen vast te leggen voor interacties met afzonderlijke agents. Met traceringsaantekeningen kunt u markeren of een agentantwoord nuttig of niet nuttig was en ze inline worden weergegeven op de traceringsdetailpagina, zodat u snel patronen in agentgedrag kunt identificeren.

Traceringsaantekeningen ondersteunen twee werkstromen:

Builder-aantekeningen: Builders en domeinexperts annoteren traces in het Foundry-portaal terwijl ze interacties van agents beoordelen. Deze annotaties worden automatisch gemarkeerd met als bron builder.
Feedback van eindgebruikers: Leg annotaties programmatisch vast vanuit uw applicatie wanneer eindgebruikers feedback geven met een duim omhoog of omlaag. Deze aantekeningen bevatten een bron van end_user en worden weergegeven op de traceringspagina naast opbouwaantekeningen. Zie Feedback van eindgebruikers registreren voor meer informatie over het vastleggen van feedback van eindgebruikers.

Alle annotaties worden toegevoegd aan de trace: het toevoegen van een builder-annotatie overschrijft of vervangt nooit bestaande feedback van eindgebruikers, en omgekeerd. Elke annotatie heeft een bronattribuut, zodat de signalen afzonderlijk opvraagbaar en filterbaar blijven.

Prerequisites

Een Foundry-project met een Application Insights-resource die is verbonden. Zie Tracering configureren.
OpenTelemetry-instrumentatie geconfigureerd in uw applicatie. Zie Opsporing instellen in Microsoft Foundry voor installatie-instructies.
Voor programmatische aantekeningen: de azure-ai-projects en azure-monitor-opentelemetry pakketten zijn geïnstalleerd.
```
pip install "azure-ai-projects>=2.0.0" azure-monitor-opentelemetry python-dotenv
```
Voor programmatische aantekeningen die gebruikmaken van Microsoft Entra-geverifieerde Application Insights-gegevensopname: de identiteit die telemetrie verzendt, heeft de rol Monitoring Metrics Publisher voor de verbonden Application Insights-resource. Zie Microsoft Entra-verificatie configureren voor traceringsopname voor installatie- en identiteitsspecifieke richtlijnen.

Standaardscoresjabloon

Elk Foundry-project wordt standaard geleverd met een beoordelingssjabloon met duim omhoog/omlaag dat direct beschikbaar is zonder aanvullende configuratie. U kunt op dag één beginnen met aantekeningen maken van traceringen. In de standaardsjabloon wordt gebruikgemaakt van binaire pass/fail scoring:

Duim omhoog = score 1.0, label pass
Duimpje omlaag = score 0.0, label fail

Elke scoresjabloon vereist dat het gen_ai.evaluation.name kenmerk de waarde task_completion heeft, zodat elke aantekening kan worden toegeschreven aan een specifieke evaluatiedimensie. task_completion ondersteunt duimen omhoog en omlaag.

Traces annoteren in het Foundry-portaal

Voeg aantekeningen rechtstreeks toe vanaf de traceringsdetailpagina om uw beoordeling van agentreacties vast te leggen.

Open uw Foundry-project en navigeer naar Tracering in de linkernavigatiebalk.
Selecteer een trace om de detailweergave van de trace te openen.
Selecteer op de detailpagina van de tracering de knop Aantekeningen toevoegen in de rechterbovenhoek.
Selecteer Duim omhoog of Duim omlaag om uw score in te dienen. Voeg desgewenst een uitleg van vrije tekst toe.
De annotatie wordt direct opgeslagen en verschijnt op de trace.

Note

Het weergeven van een tracering en het opslaan van een aantekening zijn afzonderlijke autorisatiebewerkingen. Als de trace zichtbaar is, maar de annotatie niet kan worden opgeslagen, controleert u de bestemming van de annotatie, de werkelijke schrijfidentiteit en het authenticatiepad. Een andere rol van traceringslezer verleent geen schrijftoegang tot telemetrie.

Aantekeningen die u vanuit de portal toevoegt, worden automatisch gelabeld met:

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

Score bewerken

Elke gebruiker kan meerdere keren aantekeningen maken:

Meerdere gebruikers kunnen elk hun eigen aantekening van hetzelfde type op dezelfde trace hebben.
Eerdere aantekeningen worden niet verwijderd in Application Insights. Er worden nieuwe aantekeningen toegevoegd en in de portal worden alle aantekeningen weergegeven in de sectie Annotatiegeschiedenis van het deelvenster Aantekeningen.

Feedback van eindgebruikers vastleggen als traceringsaantekeningen

Wanneer eindgebruikers feedback met duim omhoog of omlaag geven in uw toepassing, kunt u die feedback vastleggen zodat deze wordt weergegeven als aantekeningen op de bijbehorende trace. Deze benadering maakt gebruik van de gen_ai.evaluation.result OpenTelemetry-gebeurtenis, waarbij de feedback automatisch is gecorreleerd aan de oorspronkelijke tracering.

Schema voor annotatieattributen

Gebruik de volgende attributen wanneer u een duim omhoog- of duim omlaagannotatie geeft:

Attribute	Value	Description
`gen_ai.evaluation.name`	`task_completion`	Naam van de evaluatiemetriek
`gen_ai.evaluation.score.value`	`1.0` (duim omhoog) of `0.0` (duim omlaag)	Numerieke score
`gen_ai.evaluation.score.label`	`"pass"` of `"fail"`	Categorisch label
`gen_ai.evaluation.explanation`	Optionele vrije-tekstcommentaar	Uitleg van revisor
`gen_ai.response.id`	Bijvoorbeeld: `"chatcmpl-123"`	ID van het AI-antwoord dat wordt gebruikt om de annotatie te koppelen aan het getraceerde antwoord
`microsoft.gen_ai.human_evaluation.source`	`"end_user"` of `"builder"`	Type feedbackaanbieder
`microsoft.gen_ai.evaluation.actor.type`	`"human"`	Geeft aan dat de aantekening is ingediend door een menselijke revisor, waarbij deze wordt onderscheiden van geautomatiseerde evaluaties
`operation_Id`	`trace_Id`	De aantekening koppelen aan de oorspronkelijke traceringsaanvraag in Application Insights
`operation_ParentId`	`span_Id`	Bevat de span-id van de specifieke span binnen de trace die wordt geannoteerd
`gen_ai.agent.id`	Tekenreeks voor agentresource-id	Unieke id van de agent die het antwoord heeft geproduceerd dat wordt geannoteerd
`gen_ai.agent.name`	Weergavenaamtekenreeks van agent	Weergavenaam van de agent die het antwoord heeft gegenereerd dat wordt geannoteerd
`gen_ai.agent.version`	Versietekenreeks `1`, `2`, of `3`	Bevindt zich binnen `internal_properties`de versie van de agent op het moment dat het geannoteerde antwoord werd geproduceerd

U moet de evaluatie-gebeurtenis verzenden binnen dezelfde traceringscontext (met behulp van dezelfde tracerings-id en span-id) als de agentinteractie die er aantekeningen bij maakt. Deze correlatie zorgt ervoor dat de annotatie op de juiste trace in het portaal wordt weergegeven.

Zie sample_human_evaluations.py voor een volledig voorbeeld dat kan worden uitgevoerd.

Aantekeningen weergeven op de traceringspagina

Nadat u aantekeningen (vanuit de portal of programmatisch) hebt toegevoegd, worden deze weergegeven op de traceringsdetailpagina.

Open uw Foundry-project en ga naar Tracering.
Selecteer een trace met annotaties.
Op de traceringsdetailpagina worden annotatiepictogrammen weergegeven naast de geannoteerde spanten. Een duim omhoog-pictogram geeft positieve feedback aan en een duim omlaag geeft negatieve feedback aan.
Beweeg de muisaanwijzer over een aantekening om metagegevens weer te geven, inclusief de bron (builder of end_user), evaluatienaam en tijdstempel.

In de traceringslijstweergave worden aantekeningen in compacte vorm weergegeven: alleen de meest recente aantekening wordt inline weergegeven, en wanneer er meerdere aantekeningen in een trace zijn, geeft een indicator '+X meer' aan dat er aanvullende aantekeningen beschikbaar zijn. Selecteer de trace om alle annotaties te bekijken.

Traceringen filteren op aantekening

U kunt de traceringslijst filteren op:

Evaluatietype (gen_ai.evaluation.name): waarde is "task_completion".
Scorewaarde of label (gen_ai.evaluation.score.value, gen_ai.evaluation.score.label): bijvoorbeeld alleen traceringen weergeven met een duim-omlaag beoordeling.
Bron (microsoft.gen_ai.human_evaluation.source): alleen aantekeningen van de bouwer of alleen feedback van eindgebruikers weergeven.

Deze filterdimensies worden weergegeven naast bestaande traceringsfilters (tijdsbereik, agent, status, model).

Queryaantekeningen uitvoeren in Application Insights

Alle aantekeningen worden gepubliceerd naar Azure Monitor/Application Insights en gekoppeld aan de oorspronkelijke tracering. U kunt aantekeningen opvragen met behulp van Kusto Query Language (KQL) om feedbackpatronen te analyseren, dashboards te bouwen of waarschuwingen in te stellen.

Feedback samenvatten per bron en dag

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 met negatieve feedback zoeken

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

Problemen met annotaties schrijven oplossen

Symptoom	Controle
U kunt een tracering bekijken, maar het opslaan van een builder-annotatie mislukt met een autorisatiefout	Behandel het opslaan als een afzonderlijke schrijfbewerking. Bevestig de verbonden Application Insights-resource, de identiteit die wordt gebruikt voor het schrijven en de verbindingsverificatiemodus. Voeg geen andere Lezer-rol toe als algemene oplossing.
Een programmatische annotatie retourneert `401` of `403`	Controleer of de toepassing telemetrie verzendt naar de verwachte Application Insights-resource. Voor met Microsoft Entra geverifieerde gegevensopname verleent u Monitoring Metrics Publisher aan de identiteit die telemetrie verzendt voor die resource.
De toepassing meldt succes, maar de aantekening wordt niet weergegeven	Controleer of de evaluatiegebeurtenis gebruikmaakt van de oorspronkelijke tracerings- en spancontext, of deze is verzonden naar dezelfde Application Insights-resource als de tracering en of de opname is voltooid.
Er verschijnt een aantekening op de verkeerde tracering	Controleer `operation_Id`, `operation_ParentId`en `gen_ai.response.id` voordat u de gebeurtenis verzendt.

Feedback

Is deze pagina nuttig?

Laatst bijgewerkt om 2026-10-08