Annotare le tracce con feedback umano (anteprima)

Importante

Gli elementi contrassegnati come anteprima in questo articolo sono attualmente in anteprima. Questa anteprima viene fornita senza un contratto di servizio e Microsoft non lo consiglia per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate. Per ulteriori informazioni, vedere Condizioni supplementari per l'uso delle versioni di anteprima di Microsoft Azure.

Aggiungi annotazioni con pollice in su o pollice in giù alle tracce in Microsoft Foundry per raccogliere segnali di qualità umana relativi alle singole interazioni degli agenti. Le annotazioni di traccia consentono di contrassegnare se una risposta dell'agente è stata utile o non utile e vengono visualizzate inline nella pagina dei dettagli della traccia in modo da poter identificare rapidamente i modelli nel comportamento dell'agente.

Le annotazioni di traccia supportano due flussi di lavoro:

Annotazioni dei Builder: I Builder e gli esperti di dominio annotano le tracce dal portale Foundry durante la revisione delle interazioni degli agenti. Queste annotazioni vengono contrassegnate automaticamente con un'origine di builder.
Feedback degli utenti finali: Registra programmaticamente annotazioni nei log dalla tua applicazione quando gli utenti finali esprimono un feedback positivo o negativo. Queste annotazioni hanno come origine end_user e vengono visualizzate nella pagina della traccia insieme alle annotazioni del builder. Per informazioni dettagliate sulla registrazione dei commenti e suggerimenti degli utenti finali, vedere Registrare il feedback degli utenti finali.

Tutte le annotazioni vengono aggiunte alla traccia. L'aggiunta di un'annotazione del generatore non sovrascrive mai o sostituisce il feedback dell'utente finale esistente e viceversa. Ogni annotazione contiene un attributo di origine, in modo che i segnali rimangano in modo indipendente e filtrabili.

Prerequisites

Progetto Foundry con una risorsa di Application Insights connessa . Vedi Configurare il tracciamento.
Strumentazione OpenTelemetry configurata nell'applicazione. Per istruzioni sulla configurazione, vedi Configurare il tracciamento in Microsoft Foundry.
Per le annotazioni programmatiche: i pacchetti azure-ai-projects e azure-monitor-opentelemetry installati.
```
pip install "azure-ai-projects>=2.0.0" azure-monitor-opentelemetry python-dotenv
```
Per le annotazioni programmatiche che usano l'inserimento di Application Insights autenticato Microsoft Entra: l'identità che genera dati di telemetria ha il ruolo Monitoring Metrics Publisher nella risorsa di Application Insights connessa. Per indicazioni specifiche per la configurazione e l'identità, vedere Configurare l'autenticazione Microsoft Entra per l'inserimento di tracce.

Modello di assegnazione dei punteggi predefinito

Ogni progetto Foundry include già un modello predefinito di valutazione pollice su/giù, immediatamente disponibile senza alcuna configurazione aggiuntiva. È possibile iniziare a annotare le tracce il giorno 1. Il modello predefinito usa il punteggio binario pass/fail:

Pollice su = punteggio 1.0, etichetta pass
Pollice giù = punteggio 0.0, etichetta fail

Ogni modello di punteggio richiede che l'attributo gen_ai.evaluation.name abbia il valore task_completion in modo che ogni annotazione sia attribuibile a una dimensione di valutazione specifica. task_completion supporta i pollici in su e in giù.

Annota le tracce nel portale Foundry

Aggiungere annotazioni direttamente dalla pagina dei dettagli di traccia per registrare la valutazione delle risposte dell'agente.

Apri il progetto Foundry e vai a Tracciamento nella barra di navigazione a sinistra.
Selezionare una traccia per aprire la vista dettagliata della traccia.
Nella pagina dei dettagli della traccia selezionare il pulsante Annota nell'angolo superiore destro.
Selezionare Thumbs up o Thumbs down per inviare il punteggio. Facoltativamente, aggiungere una spiegazione in formato libero.
L'annotazione viene salvata immediatamente e appare nella traccia.

Note

La visualizzazione di una traccia e il salvataggio di un'annotazione sono operazioni di autorizzazione separate. Se la traccia è visibile ma l'annotazione non può essere salvata, verificare la destinazione dell'annotazione, l'identità di scrittura effettiva e il percorso di autenticazione. Un altro ruolo trace-reader non concede l'accesso in scrittura ai dati di telemetria.

Le annotazioni aggiunte dal portale vengono contrassegnate automaticamente con:

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

Modifica del punteggio

Ogni utente può annotare più volte:

Più utenti possono avere una propria annotazione dello stesso tipo nella stessa traccia.
Le annotazioni precedenti non vengono eliminate in Application Insights. Vengono aggiunte nuove annotazioni e nel portale vengono visualizzate tutte le annotazioni nella sezione Cronologia annotazioni del pannello annotazione.

Registrare il feedback dell'utente finale come annotazioni di traccia

Quando gli utenti finali forniscono un feedback verso l'alto o il pollice verso il basso nell'applicazione, è possibile registrare il feedback in modo che venga visualizzato come annotazioni sulla traccia corrispondente. Questo approccio usa l'evento gen_ai.evaluation.result OpenTelemetry, con il feedback correlato automaticamente alla traccia di origine.

Schema dell'attributo annotazione

Usa i seguenti attributi quando emetti un'annotazione di pollice in su o pollice in giù:

Attribute	Value	Descrizione
`gen_ai.evaluation.name`	`task_completion`	Nome della metrica di valutazione
`gen_ai.evaluation.score.value`	`1.0` (pollice su) o `0.0` (pollice giù)	Punteggio numerico
`gen_ai.evaluation.score.label`	`"pass"` oppure `"fail"`	Etichetta categorica
`gen_ai.evaluation.explanation`	Commento facoltativo in formato libero	Spiegazione del revisore
`gen_ai.response.id`	Ad esempio, `"chatcmpl-123"`	ID risposta di intelligenza artificiale usato per correlare l'annotazione alla risposta tracciata
`microsoft.gen_ai.human_evaluation.source`	`"end_user"` oppure `"builder"`	Tipo di provider di feedback
`microsoft.gen_ai.evaluation.actor.type`	`"human"`	Indica che l'annotazione è stata inviata da un revisore umano, distinguendola dalle valutazioni automatizzate
`operation_Id`	`trace_Id`	Collega l'annotazione alla richiesta di traccia originale in Application Insights
`operation_ParentId`	`span_Id`	Include l'ID intervallo dell'intervallo specifico nell'ambito della traccia annotata
`gen_ai.agent.id`	Stringa dell'identificatore di risorsa dell'agente	Identificatore univoco dell'agente che ha prodotto la risposta annotata
`gen_ai.agent.name`	Stringa del nome visualizzato dell'agente	Nome visualizzato dell'agente che ha prodotto la risposta annotata
`gen_ai.agent.version`	Stringa di versione `1`, `2` o `3`	Disponibile in `internal_properties`, la versione dell'agente al momento in cui è stata generata la risposta annotata

È necessario generare l'evento di valutazione nello stesso contesto di traccia (usando lo stesso ID di traccia e l'ID intervallo) dell'interazione dell'agente che annota. Questa correlazione garantisce che l'annotazione venga visualizzata nella traccia corretta nel portale.

Per un esempio eseguibile completo, vedere sample_human_evaluations.py.

Visualizzare le annotazioni nella pagina di traccia

Dopo aver aggiunto annotazioni (dal portale o a livello di codice), vengono visualizzate nella pagina dei dettagli della traccia.

Aprire il progetto Foundry e passare a Traccia.
Selezionare una traccia con annotazioni.
Nella pagina dei dettagli di traccia le icone di annotazione vengono visualizzate accanto agli intervalli con annotazioni. Un'icona a forma di pollice in alto indica un feedback positivo e un'icona a forma di pollice verso il basso indica un feedback negativo.
Passare il puntatore del mouse su un'annotazione per visualizzare i metadati, tra cui l'origine (builder o end_user), il nome della valutazione e il timestamp.

Nella visualizzazione elenco di traccia le annotazioni vengono visualizzate con un trattamento compatto: solo l'annotazione più recente mostra inline e quando esistono più annotazioni in una traccia, un indicatore "+X more" segnala che sono disponibili annotazioni aggiuntive. Selezionare la traccia per visualizzare tutte le annotazioni.

Filtrare le tracce in base all'annotazione

È possibile filtrare l'elenco di tracce in base a:

Tipo di valutazione (gen_ai.evaluation.name): il valore è "task_completion".
Valore del punteggio o etichetta (gen_ai.evaluation.score.value, gen_ai.evaluation.score.label): ad esempio, mostra solo le tracce con una valutazione negativa.
Origine (microsoft.gen_ai.human_evaluation.source): mostra solo annotazioni del generatore o solo commenti e suggerimenti degli utenti finali.

Queste dimensioni del filtro vengono visualizzate insieme ai filtri di traccia esistenti (intervallo di tempo, agente, stato, modello).

Annotazioni delle query in Application Insights

Tutte le annotazioni vengono pubblicate in Monitoraggio di Azure/Application Insights e collegate alla traccia originale. È possibile eseguire query sulle annotazioni usando KQL (Kusto Query Language) per analizzare i modelli di feedback, creare dashboard o configurare avvisi.

Riepilogare il feedback in base all'origine e al giorno

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

Trova tracce con feedback negativo

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

Risolvere i problemi di scrittura delle annotazioni

Sintomo	Controlla
È possibile visualizzare una traccia, ma il salvataggio di un'annotazione del builder non riesce con un errore di autorizzazione	Considera il salvataggio come operazione di scrittura separata. Verificare la risorsa di Application Insights connessa, l'identità usata per la scrittura e la modalità di autenticazione della connessione. Non aggiungere un altro ruolo Reader come correzione generica.
Un'annotazione a livello di codice restituisce `401` o `403`	Verificare che l'applicazione invii dati di telemetria alla risorsa di Application Insights prevista. Per l'acquisizione autenticata tramite Microsoft Entra, concedere Monitoring Metrics Publisher all'identità che emette i dati di telemetria su tale risorsa.
L'applicazione segnala l'esito positivo, ma l'annotazione non viene visualizzata	Verificare che l'evento di valutazione usi il contesto di traccia e span originale, che sia stato inviato alla stessa risorsa di Application Insights della traccia e che l'ingestione sia stata completata.
Un'annotazione appare sulla traccia sbagliata	Verificare `operation_Id`, `operation_ParentId`e `gen_ai.response.id` prima di emettere l'evento.

Commenti e suggerimenti

Questa pagina è stata utile?

Ultimo aggiornamento: 2026-10-08