Anotar trazas con retroalimentación humana (versión preliminar)

Importante

Los elementos marcados como versión preliminar en este artículo se encuentran actualmente en versión preliminar. Esta versión preliminar se proporciona sin un contrato de nivel de servicio y Microsoft no lo recomienda para cargas de trabajo de producción. Es posible que algunas características no se admitan o que tengan funcionalidades restringidas. Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.

Agregue anotaciones de pulgar hacia arriba o hacia abajo a las trazas en Microsoft Foundry para capturar señales humanas de calidad en las interacciones individuales del agente. Las anotaciones de seguimiento le permiten marcar si una respuesta del agente era útil o no útil, y aparecen insertadas en la página de detalles de seguimiento para que pueda identificar rápidamente patrones en el comportamiento del agente.

Las anotaciones de seguimiento admiten dos flujos de trabajo:

  • Anotaciones del creador: los creadores y los expertos del dominio anotan trazas en el portal de Foundry mientras revisan las interacciones del agente. Estas anotaciones se etiquetan automáticamente con un origen de builder.
  • Comentarios del usuario final: Registre anotaciones mediante programación desde su aplicación cuando los usuarios finales proporcionen comentarios de aprobación o desaprobación. Estas anotaciones llevan un origen de end_user y aparecen en la página de la traza junto con las anotaciones del generador. Para obtener más información sobre el registro de comentarios de los usuarios finales, consulte Registro de comentarios del usuario final.

Todas las anotaciones se anexan a la traza: agregar una anotación del generador nunca sobrescribe ni sustituye los comentarios existentes del usuario final y viceversa. Cada anotación lleva un atributo de origen para que las señales permanezcan consultables y filtrables de forma independiente.

Prerequisites

Plantilla de puntuación predeterminada

Todos los proyectos de Foundry vienen preconfigurados con una plantilla predeterminada de puntuación de aprobación/rechazo, disponible de inmediato sin necesidad de configuración adicional. Puede empezar a anotar trazas desde el primer día. La plantilla predeterminada usa un sistema de puntuación binario de aprobado/reprobado:

  • Pulgar arriba = puntuación 1.0, etiqueta pass
  • No me gusta = puntuación 0.0, etiqueta fail

Cada plantilla de puntuación requiere que el gen_ai.evaluation.name atributo tenga el valor task_completion para que cada anotación sea imputable a una dimensión de evaluación específica. task_completion permite votos positivos y negativos.

Anotar trazas en el portal de Foundry

Agregue anotaciones directamente desde la página de detalles del seguimiento para registrar la evaluación de las respuestas del agente.

  1. Abra el proyecto Foundry y vaya a Seguimiento en el panel de navegación izquierdo.
  2. Seleccione una traza para abrir la vista de detalles de la traza.
  3. En la página de detalles del seguimiento, seleccione el botón Anotar en la esquina superior derecha.
  4. Seleccione Pulgar hacia arriba o Pulgar hacia abajo para enviar la puntuación. Opcionalmente, agregue una explicación de texto libre.
  5. La anotación se guarda inmediatamente y aparece en la traza.

Captura de pantalla de la pestaña Anotaciones de la página de detalles del seguimiento en el portal de Foundry.

Note

Ver una traza y guardar una anotación son operaciones de autorización independientes. Si la traza está visible, pero la anotación no se puede guardar, compruebe el destino de la anotación, la identidad de escritura real y la ruta de acceso de autenticación. Otro rol de lector de trazas no concede acceso de escritura de telemetría.

Las anotaciones que agregue desde el portal se etiquetan automáticamente con:

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

Edición de puntuaciones

Cada usuario puede anotar varias veces:

  • Varios usuarios pueden tener cada uno su propia anotación del mismo tipo en la misma traza.
  • Las anotaciones anteriores no se eliminan en Application Insights. Se anexan nuevas anotaciones y el portal muestra todas las anotaciones en la sección Historial de anotaciones del panel de anotaciones.

Registrar comentarios del usuario final como anotaciones de seguimiento

Cuando los usuarios finales proporcionen valoraciones con pulgar arriba o abajo en su aplicación, puede registrar esos comentarios para que aparezcan como anotaciones en la traza correspondiente. Este enfoque usa el evento gen_ai.evaluation.result de OpenTelemetry, y la retroalimentación se correlaciona automáticamente con la traza de origen.

Esquema de atributos de anotación

Utilice los siguientes atributos al emitir una anotación de aprobación o desaprobación:

Attribute Value Descripción
gen_ai.evaluation.name task_completion Nombre de la métrica de evaluación
gen_ai.evaluation.score.value 1.0 (pulgares hacia arriba) o 0.0 (pulgares hacia abajo) Puntuación numérica
gen_ai.evaluation.score.label "pass" o "fail" Etiqueta de categoría
gen_ai.evaluation.explanation Comentario de texto libre opcional Explicación del revisor
gen_ai.response.id Por ejemplo: "chatcmpl-123" Identificador de respuesta de IA usado para correlacionar la anotación con la respuesta rastreada
microsoft.gen_ai.human_evaluation.source "end_user" o "builder" Tipo de proveedor de comentarios
microsoft.gen_ai.evaluation.actor.type "human" Indica que un revisor humano envió la anotación, distinguiéndolo de evaluaciones automatizadas.
operation_Id trace_Id Vincula la anotación a la solicitud de seguimiento original en Application Insights
operation_ParentId span_Id Incluye el ID del intervalo específico dentro de la traza que se está anotando
gen_ai.agent.id Cadena de identificador de recursos del agente Identificador único del agente que produjo la respuesta anotada
gen_ai.agent.name Cadena de nombre para mostrar del agente Nombre visible del agente que produjo la respuesta que se está anotando
gen_ai.agent.version Cadena de versión 1, 2 o 3 Ubicada dentro de internal_properties, la versión del agente en el momento en que se generó la respuesta anotada

Debe emitir el evento de evaluación dentro del mismo contexto de traza (con el mismo identificador de traza y el identificador de intervalo) que la interacción del agente que anota. Esta correlación garantiza que la anotación aparezca en la traza correcta en el portal.

Para obtener un ejemplo completo de ejecución, consulte sample_human_evaluations.py.

Visualización de anotaciones en la página de seguimiento

Después de agregar anotaciones (desde el portal o mediante programación), aparecen en la página de detalles del seguimiento.

  1. Abra el proyecto Foundry y vaya a Seguimiento.
  2. Seleccione una traza que tenga anotaciones.
  3. En la página de detalles del seguimiento, los iconos de anotación aparecen junto a los intervalos anotados. Un icono de pulgar hacia arriba indica comentarios positivos y un icono de pulgar hacia abajo indica comentarios negativos.
  4. Mantenga el puntero sobre una anotación para ver los metadatos, incluido el nombre de la evaluación (builder o end_user), y la marca de tiempo.

En la vista de lista de trazas, las anotaciones se muestran en un formato compacto: solo la anotación más reciente se muestra en línea y, cuando existen varias anotaciones en una traza, un indicador “+X más” señala que hay anotaciones adicionales disponibles. Seleccione la traza para ver todas las anotaciones.

Filtrar trazas por anotación

Puede filtrar la lista de seguimiento por:

  • Tipo de evaluación (gen_ai.evaluation.name): el valor es "task_completion".
  • Valor o etiqueta de puntuación (gen_ai.evaluation.score.value, gen_ai.evaluation.score.label): por ejemplo, muestra solo las trazas con una valoración negativa.
  • Origen (microsoft.gen_ai.human_evaluation.source): muestra solo anotaciones del generador o solo comentarios del usuario final.

Estas dimensiones de filtro aparecen junto con los filtros de seguimiento existentes (intervalo de tiempo, agente, estado, modelo).

Consultar anotaciones en Application Insights

Todas las anotaciones se publican en Azure Monitor o Application Insights y se adjuntan al seguimiento original. Puede consultar anotaciones mediante el lenguaje de consulta kusto (KQL) para analizar patrones de comentarios, crear paneles o configurar alertas.

Resumir comentarios por origen y día

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

Buscar trazas con comentarios negativas

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 de escritura de anotaciones

Síntoma Check
Puede ver una traza, pero al guardar una anotación del generador se produce un error de autorización Trate el guardado como una operación de escritura independiente. Confirme el recurso de Application Insights conectado, la identidad usada para la escritura y el modo de autenticación de conexión. No agregue otro rol Reader como corrección genérica.
Una anotación mediante programación devuelve 401 o 403 Confirme que la aplicación envía telemetría al recurso de Application Insights esperado. Para la ingesta autenticada por Microsoft Entra, conceda el rol Monitoring Metrics Publisher a la identidad que emite la telemetría en ese recurso.
La aplicación indica que la operación se ha realizado correctamente, pero la anotación no aparece Confirme que el evento de evaluación usa el contexto de seguimiento y de span original, que se envió al mismo recurso de Application Insights que el seguimiento y que la ingesta se ha completado.
Aparece una anotación en la traza incorrecta Compruebe operation_Id, operation_ParentIdy gen_ai.response.id antes de emitir el evento.

Contenido relacionado

  • Se actualizó por última vez el