Anotar traços com feedback humano (pré-visualização)

Importante

Os itens marcados como pré-visualização neste artigo estão atualmente em pré-visualização. Esta pré-visualização é fornecida sem um acordo de nível de serviço, e a Microsoft não a recomenda para cargas de trabalho de produção. Certas funcionalidades podem não ser suportadas ou podem ter capacidades limitadas. Para mais informações, consulte Termos Suplementares de Utilização para Microsoft Azure Previews.

Adicione anotações de polegares para cima ou para baixo aos traços no Microsoft Foundry para captar sinais de qualidade humana nas interações individuais dos agentes. As anotações de rastreamento permitem-lhe assinalar se a resposta do agente foi útil ou inútil, e aparecem em linha na página de detalhe do rastreio para que possa identificar rapidamente padrões no comportamento do agente.

As anotações de traço suportam dois fluxos de trabalho:

Anotações do criador: Os criadores e os especialistas de domínio anotam os registos no portal Foundry ao analisarem as interações dos agentes. Estas anotações são automaticamente marcadas com a origem builder.
Feedback dos utilizadores finais: Regista as anotações programaticamente da tua aplicação quando os utilizadores finais fornecerem feedback positivo ou negativo. Estas anotações têm como origem end_user e aparecem na página de rastreio, a par das anotações do builder. Para detalhes sobre como registar feedback dos utilizadores finais, consulte Registar feedback dos utilizadores finais.

Todas as anotações são adicionadas ao rastreio — adicionar uma anotação builder nunca sobreescreve nem substitui o feedback existente do utilizador final, e vice-versa. Cada anotação transporta um atributo de origem, pelo que os sinais permanecem independentemente consultáveis e filtráveis.

Prerequisites

Um projeto Foundry com um recurso do Application Insights associado. Veja Configurar o rastreio.
Instrumentação OpenTelemetry configurada na sua aplicação. Consulte Configurar o rastreio no Microsoft Foundry para obter instruções de configuração.
Para anotações programáticas: os pacotes azure-ai-projects e azure-monitor-opentelemetry instalados.
```
pip install "azure-ai-projects>=2.0.0" azure-monitor-opentelemetry python-dotenv
```
Para anotações programáticas que utilizam a ingestão autenticada pelo Microsoft Entra do Application Insights: a identidade que emite telemetria tem a função Monitoring Metrics Publisher no recurso do Application Insights ligado. Para orientações específicas de configuração e identidade, consulte Configurar autenticação Microsoft Entra para ingestão de traços.

Modelo de pontuação padrão

Cada projeto Foundry é pré-seedado com um modelo padrão de pontuação com o polegar para cima/baixo que está imediatamente disponível sem qualquer configuração adicional. Pode começar a anotar os rastreios desde o primeiro dia. O modelo predefinido utiliza uma classificação binária de aprovação/reprovação:

Gostei = pontuação 1.0, etiqueta pass
Não gosto = pontuação 0.0, etiqueta fail

Cada modelo de pontuação exige que o atributo gen_ai.evaluation.name tenha o valor task_completion, pelo que cada anotação é atribuível a uma dimensão específica de avaliação. task_completion suporta polegares para cima e para baixo.

Anotar rastreios no portal da Foundry

Adicione anotações diretamente da página de detalhamento para registar a sua avaliação das respostas dos agentes.

Abre o teu projeto Foundry e navega até Rastreio na navegação da esquerda.
Selecione um traço para abrir a vista de detalhe do traço.
Na página de detalhes do rastreio, selecione o botão Anotar no canto superior direito.
Selecione Gostei ou Não gostei para enviar a sua classificação. Opcionalmente, adiciona uma explicação em texto livre.
A anotação é guardada imediatamente e aparece no rasto.

Note

Visualizar um rastreio e guardar uma anotação são operações de autorização separadas. Se o rastreio estiver visível mas a anotação não puder ser guardada, verifique o destino da anotação, a identidade real de escrita e o caminho de autenticação. Outro papel trace-reader não concede acesso de escrita de telemetria.

As anotações que adicionas do portal são automaticamente etiquetadas com:

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

Edição da banda sonora

Cada utilizador pode anotar várias vezes:

Vários utilizadores podem ter cada um a sua própria anotação do mesmo tipo na mesma pista.
As anotações anteriores não são eliminadas no Application Insights. Novas anotações são adicionadas e o portal mostra todas as anotações na secção de histórico de anotações do painel de anotações.

Registar os comentários do utilizador final como anotações de rastreio

Quando os utilizadores finais fornecem feedback positivo ou negativo na sua aplicação, pode registar esse feedback para que apareça como anotações no rastreio correspondente. Esta abordagem utiliza o evento OpenTelemetry gen_ai.evaluation.result, com o feedback automaticamente correlacionado com o rastreio original.

Esquema de atributos de anotação

Utilize os seguintes atributos quando emitir uma anotação positiva ou negativa:

Attribute	Valor	Description
`gen_ai.evaluation.name`	`task_completion`	Nome da métrica de avaliação
`gen_ai.evaluation.score.value`	`1.0` (polegar para cima) ou `0.0` (polegar para baixo)	Pontuação numérica
`gen_ai.evaluation.score.label`	`"pass"` ou `"fail"`	Etiqueta categorial
`gen_ai.evaluation.explanation`	Comentário opcional em texto livre	Explicação do revisor
`gen_ai.response.id`	Por exemplo, `"chatcmpl-123"`	ID de resposta da IA usado para correlacionar a anotação com a resposta rastreada
`microsoft.gen_ai.human_evaluation.source`	`"end_user"` ou `"builder"`	Tipo de fornecedor de feedback
`microsoft.gen_ai.evaluation.actor.type`	`"human"`	Indica que a anotação foi submetida por um revisor humano, distinguindo-a das avaliações automáticas
`operation_Id`	`trace_Id`	Liga a anotação ao pedido de rastreamento original no Application Insights
`operation_ParentId`	`span_Id`	Inclui o ID do segmento específico dentro do rasto que está a ser anotado
`gen_ai.agent.id`	Cadeia de caracteres do identificador de recurso do agente	Identificador único do agente que produziu a resposta que está a ser anotada
`gen_ai.agent.name`	Cadeia de caracteres do nome de exibição do agente	Nome de exibição do agente que produziu a resposta a ser anotada
`gen_ai.agent.version`	Cadeia de caracteres da versão `1`, `2` ou `3`	Localizado dentro de `internal_properties`, versão do agente à data em que a resposta anotada foi produzida

Tem de emitir o evento de avaliação no mesmo contexto de rastreio (utilizando o mesmo ID de rastreio e o mesmo ID de span) da interação do agente que anota. Esta correlação assegura que a anotação aparece na pista correta no portal.

Para um exemplo completo executável, veja sample_human_evaluations.py.

Veja as anotações na página do traço

Depois de adicionares anotações (do portal ou programáticamente), elas aparecem na página de detalhe do traço.

Abra o seu projeto Foundry e aceda a Tracing.
Selecione um traço que tenha anotações.
Na página de detalhes do rastreio, os ícones de anotação aparecem ao lado dos segmentos anotados. Um ícone de polegar para cima indica feedback positivo e um ícone de polegar para baixo indica feedback negativo.
Passe o rato sobre uma anotação para ver os metadados, incluindo a origem (builder ou end_user), o nome da avaliação e o carimbo temporal.

Na vista de lista de traços, as anotações são exibidas com um tratamento compacto: apenas a anotação mais recente aparece em linha e, quando existem múltiplas anotações num traço, um indicador "+X mais" indica que há anotações adicionais disponíveis. Selecione o rasto para ver todas as anotações.

Filtrar rastreios por anotação

Pode filtrar a lista de traços por:

Tipo de avaliação (gen_ai.evaluation.name): valor é "task_completion".
Valor da pontuação ou rótulo (gen_ai.evaluation.score.value, gen_ai.evaluation.score.label): por exemplo, mostrar apenas rastreios com avaliação negativa.
Fonte (microsoft.gen_ai.human_evaluation.source): mostrar apenas anotações do construtor ou apenas feedback do utilizador final.

Estas dimensões do filtro aparecem juntamente com os filtros de traço existentes (intervalo de tempo, agente, estado, modelo).

Consultar anotações no Application Insights

Todas as anotações são publicadas no Azure Monitor / Application Insights e anexadas ao traçado original. Pode consultar anotações usando a Linguagem de Consulta Kusto (KQL) para analisar padrões de feedback, construir painéis de controlo ou configurar alertas.

Resuma o feedback por fonte e dia

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

Encontre vestígios com 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

Resolver problemas de escrita de anotações

Symptom	Verificar
Podes ver um rastreio, mas guardar uma anotação builder falha com um erro de autorização	Trate a gravação como uma operação de escrita separada. Confirme o recurso Application Insights ligado, a identidade usada para a escrita e o modo de autenticação da ligação. Não adicione outra função Reader como uma solução genérica.
Uma anotação programática retorna `401` ou `403`	Confirme que a aplicação envia telemetria para o recurso de Application Insights esperado. Para a ingestão autenticada pelo Microsoft Entra, conceda o Monitoring Metrics Publisher à identidade emissora de telemetria nesse recurso.
A aplicação reporta sucesso, mas a anotação não aparece	Confirme que o evento de avaliação utiliza o contexto original de rastreamento e span, que foi enviado para o mesmo recurso Application Insights que o rastreio, e que a ingestão foi concluída.
Uma anotação aparece no rasto errado	Verifique `operation_Id`, `operation_ParentId`, e `gen_ai.response.id` antes de emitir o evento.

Comentários

Esta página foi útil?

Última atualização a 2026-10-08