Anotar rastreamentos com feedback humano (versão preliminar)

Importante

Os itens marcados como visualização neste artigo estão atualmente em versão prévia. Esta versão prévia é fornecida sem um contrato de nível de serviço (SLA), e a Microsoft não a recomenda para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.

Adicione anotações de avaliação positiva ou negativa aos rastreamentos no Microsoft Foundry para capturar sinais humanos de qualidade em interações de agentes individuais. As anotações de rastreamento permitem que você marque se uma resposta do agente foi útil ou inútil, e elas aparecem embutidas na página de detalhes de rastreamento para que você possa identificar rapidamente padrões no comportamento do agente.

As anotações de rastreamento dão suporte a dois fluxos de trabalho:

  • Anotações dos desenvolvedores: Desenvolvedores e especialistas de domínio anotam rastros no portal Foundry ao revisar as interações do agente. Essas anotações são identificadas automaticamente com a origem builder.
  • Feedback do usuário final: Registre anotações programaticamente no seu aplicativo quando os usuários finais fornecerem feedback positivo ou negativo. Essas anotações têm origem em end_user e aparecem na página de rastreamento ao lado das anotações do construtor. Para obter detalhes sobre o registro do feedback do usuário final, consulte Registrar o feedback do usuário final.

Todas as anotações são acrescentadas ao rastreamento. Adicionar uma anotação do construtor nunca substitui o feedback existente do usuário final, e vice-versa. Cada anotação carrega um atributo de origem para que os sinais permaneçam independentemente consultáveis e filtrados.

Prerequisites

Modelo de pontuação padrão

Cada projeto do Foundry é pré-criado com um modelo de pontuação positiva/negativa padrão que está imediatamente disponível sem nenhuma configuração adicional. Você pode começar a anotar rastreamentos já no primeiro dia. O modelo padrão usa a pontuação de passagem/falha binária:

  • Curtir = pontuação 1.0, rótulo pass
  • Não gostei = pontuação 0.0, rótulo fail

Cada modelo de pontuação requer que o gen_ai.evaluation.name atributo tenha o valor task_completion para que cada anotação seja atribuível a uma dimensão de avaliação específica. task_completion dá suporte a curtidas e rejeições.

Anotar rastreamentos no portal do Foundry

Adicione anotações diretamente da página de detalhes de rastreamento para registrar sua avaliação das respostas do agente.

  1. Abra seu projeto do Foundry e navegue até o Rastreamento na navegação à esquerda.
  2. Selecione um rastreamento para abrir a visualização de detalhes.
  3. Na página de detalhes de rastreamento, selecione o botão Anotar no canto superior direito.
  4. Selecione Gostei ou Não gostei para enviar sua avaliação. Opcionalmente, adicione uma explicação de texto livre.
  5. A anotação é salva imediatamente e aparece no rastreamento.

Captura de tela da guia Anotações na página de detalhes de rastreamento no portal do Foundry.

Note

Exibir um rastreamento e salvar uma anotação são operações de autorização separadas. Se o rastreamento estiver visível, mas a anotação não puder ser salva, verifique o destino da anotação, a identidade de gravação real e o caminho de autenticação. Outra função de leitor de rastreamento não concede acesso de gravação de telemetria.

As anotações que você adiciona do portal são marcadas automaticamente com:

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

Edição de pontuação

Cada usuário pode anotar várias vezes:

  • Vários usuários podem ter, cada um, sua própria anotação do mesmo tipo no mesmo rastreamento.
  • As anotações anteriores não são excluídas no Application Insights. Novas anotações são acrescentadas e o portal exibe todas as anotações na seção Histórico de Anotação do painel de anotação.

Registrar comentários do usuário final como anotações de rastreamento

Quando os usuários finais fornecem feedback positivo ou negativo no seu aplicativo, você pode registrar esse feedback para que apareça como anotações no rastreamento correspondente. Essa abordagem usa o evento gen_ai.evaluation.result OpenTelemetry, com o feedback automaticamente correlacionado ao rastreamento de origem.

Esquema de atributo de anotação

Use os seguintes atributos ao emitir uma anotação de curtida ou rejeição:

Attribute Valor Description
gen_ai.evaluation.name task_completion Nome da métrica de avaliação
gen_ai.evaluation.score.value 1.0 (polegares para cima) ou 0.0 (polegares para baixo) Pontuação numérica
gen_ai.evaluation.score.label "pass" ou "fail" Rótulo de categoria
gen_ai.evaluation.explanation Comentário de texto livre opcional Explicação do revisor
gen_ai.response.id Por exemplo, "chatcmpl-123" ID de resposta de IA usada para correlacionar a anotação com a resposta rastreada
microsoft.gen_ai.human_evaluation.source "end_user" ou "builder" Tipo de provedor de comentários
microsoft.gen_ai.evaluation.actor.type "human" Indica que a anotação foi enviada por um revisor humano, distinguindo-a de avaliações automatizadas
operation_Id trace_Id Vincula a anotação à solicitação de rastreamento original no Application Insights
operation_ParentId span_Id Inclui o ID do intervalo específico dentro do rastreamento que está sendo anotado
gen_ai.agent.id Cadeia de caracteres do identificador de recurso do agente Identificador exclusivo do agente que produziu a resposta que está sendo anotada
gen_ai.agent.name Texto do nome de exibição do agente Nome de exibição do agente que produziu a resposta que está sendo anotada
gen_ai.agent.version String de versão 1, 2 ou 3 Localizada dentro de internal_properties, a versão do agente no momento em que a resposta anotada foi produzida

Você deve emitir o evento de avaliação dentro do mesmo contexto de rastreamento (usando o mesmo ID de rastreamento e ID de intervalo) que a interação do agente anotada. Essa correlação garante que a anotação apareça no rastreamento correto no portal.

Para obter um exemplo executável completo, consulte sample_human_evaluations.py.

Exibir anotações na página de rastreamento

Depois de adicionar anotações (do portal ou programaticamente), elas aparecerão na página de detalhes do rastreamento.

  1. Abra seu projeto do Foundry e vá para Rastreamento.
  2. Selecione um rastro que tenha anotações.
  3. Na página de detalhes de rastreamento, os ícones de anotação aparecem ao lado dos intervalos anotados. Um ícone de polegar para cima indica comentários positivos e um ícone de polegar para baixo indica comentários negativos.
  4. Passe o mouse sobre uma anotação para ver metadados, incluindo a origem (builder ou end_user), o nome da avaliação e o carimbo de data/hora.

Na visualização em lista de rastreamentos, as anotações são exibidas em um formato compacto: somente a anotação mais recente é exibida em linha e, quando há várias anotações em um rastreamento, um indicador “+X a mais” indica que há anotações adicionais disponíveis. Selecione o rastreamento para ver todas as anotações.

Filtrar rastreamentos por anotação

Você pode filtrar a lista de rastreamento:

  • Tipo de avaliação (gen_ai.evaluation.name): o valor é "task_completion".
  • Valor ou rótulo da pontuação (gen_ai.evaluation.score.value, gen_ai.evaluation.score.label): por exemplo, mostrar apenas rastreamentos com uma avaliação negativa.
  • Origem (microsoft.gen_ai.human_evaluation.source): mostrar somente anotações do construtor ou somente comentários do usuário final.

Essas dimensões de filtro aparecem junto com filtros de rastreamento existentes (intervalo de tempo, agente, status, modelo).

Anotações de consulta no Application Insights

Todas as anotações são publicadas no Azure Monitor/Application Insights e anexadas ao rastreamento original. Você pode consultar anotações usando KQL (Linguagem de Consulta Kusto) para analisar padrões de comentários, criar painéis ou configurar alertas.

Resumir comentários por origem 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

Localizar rastreamentos 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

Solucionar problemas na gravação de anotações

Sintoma Verificação
Você pode exibir um rastreamento, mas salvar uma anotação do builder falha com um erro de autorização Trate o salvamento como uma operação de gravação separada. Confirme o recurso do Application Insights conectado, a identidade usada para a gravação e o modo de autenticação de conexão. Não adicione outra função Leitor como uma correção genérica.
Uma anotação programática retorna 401 ou 403 Confirme se o aplicativo envia telemetria para o recurso esperado do Application Insights. Para ingestão autenticada por Microsoft Entra, conceda Monitoring Metrics Publisher à identidade emissora de telemetria nesse recurso.
O aplicativo relata êxito, mas a anotação não aparece Confirme se o evento de avaliação usa o contexto original de trace e span, que ele foi enviado para o mesmo recurso do Application Insights que o trace e que a ingestão foi concluída.
Uma anotação aparece no rastreamento errado Verifique operation_Id, operation_ParentIde gen_ai.response.id antes de emitir o evento.

Conteúdo relacionado

  • Última atualização em