Аннотирование трассировок с помощью обратной связи от пользователей (предварительная версия)

Добавьте к трассировкам в Microsoft Foundry отметки «Нравится» или «Не нравится», чтобы фиксировать сигналы качества от человека для отдельных взаимодействий с агентом. Заметки трассировки позволяют пометить, был ли ответ агента полезным или бесполезным, и они отображаются на странице сведений о трассировке, чтобы быстро определить закономерности в поведении агента.

Аннотации трассировки поддерживают два сценария работы:

• Аннотации Builder: Разработчики и предметные эксперты аннотируют трассировки на портале Foundry в ходе проверки взаимодействий агента. Эти заметки автоматически помечены источником builder.
• Отзывы пользователей: Программно записывайте аннотации в журнал из своего приложения, когда пользователи ставят отметку «Нравится» или «Не нравится». Эти аннотации имеют источник end_user и отображаются на странице трассировки вместе с аннотациями сборщика. Дополнительные сведения о регистрации отзывов конечных пользователей см. в статье Регистрация отзывов конечных пользователей.

Все заметки добавляются в трассировку— добавление заметки построителя никогда не перезаписывает или заменяет существующие отзывы конечных пользователей и наоборот. Каждая заметка содержит исходный атрибут, поэтому сигналы остаются независимо запрашиваемыми и фильтруемыми.

Prerequisites

• Проект Foundry с подключённым ресурсом Application Insights. См. Настройка трассировки.

• Инструментирование OpenTelemetry, настроенное в вашем приложении. Инструкции по настройке см. в разделе Настроить трассировку в Microsoft Foundry.

• Для программных аннотаций: установлены пакеты azure-ai-projects и azure-monitor-opentelemetry.

  pip install "azure-ai-projects>=2.0.0" azure-monitor-opentelemetry python-dotenv
  

Шаблон оценки по умолчанию

Каждый проект Foundry по умолчанию содержит стандартный шаблон оценки «большой палец вверх/вниз», который доступен сразу, без дополнительных настроек. Вы можете начать аннотировать трассировки с первого дня. Шаблон по умолчанию использует бинарную систему оценки «прошёл/не прошёл»:

• Большой палец вверх = оценка 1.0, метка pass
• Пальцы вниз = оценка 0.0, метка fail

Для каждого шаблона оценки требуется, чтобы у gen_ai.evaluation.name attribute было значение task_completion, чтобы каждую аннотацию можно было отнести к определённому аспекту оценки. task_completion поддерживает отметки «Нравится» и «Не нравится».

Аннотирование трассировок в портале Foundry

Добавьте аннотации непосредственно на странице сведений о трассировке, чтобы зафиксировать вашу оценку ответов агента.

1. Откройте проект Foundry и перейдите к Tracing в левой панели навигации.
2. Выберите трассировку, чтобы открыть подробные сведения о трассировке.
3. На странице сведений о трассировке нажмите кнопку Annotate в правом верхнем углу.
4. Выберите Нравится или Не нравится, чтобы отправить свою оценку. При необходимости добавьте пояснение в свободной форме.
5. Аннотация сохраняется сразу и отображается в трассировке.

Заметки, добавленные на портале, автоматически помечены следующим образом:

• microsoft.gen_ai.human_evaluation.source = "builder"
• Записи будут иметь microsoft.gen_ai.evaluation.actor.type как "human"

Редактирование оценки

Каждый пользователь может аннотировать несколько раз, однако:

• Несколько пользователей могут каждый иметь собственную аннотацию одного и того же типа в одной и той же трассировке.
• Предыдущие заметки никогда не удаляются в Application Insights, новые заметки добавляются, а на портале отображаются все заметки в разделе "Журнал заметок " панели заметок.

Регистрировать отзывы конечных пользователей как аннотации трассировки

Когда конечные пользователи оставляют положительный или отрицательный отзыв в вашем приложении, вы можете регистрировать этот отзыв, чтобы он отображался в виде аннотаций в соответствующей трассе. Этот подход использует событие OpenTelemetry gen_ai.evaluation.result, при этом обратная связь автоматически связывается с исходной трассировкой.

Схема атрибутов аннотации

Используйте следующие атрибуты, когда вы добавляете аннотацию «Нравится» или «Не нравится»:

Необходимо отправить событие оценки в том же контексте трассировки (используя тот же идентификатор трассировки и идентификатор спана), что и взаимодействие с агентом, которое оно аннотирует. Эта корреляция гарантирует, что заметка отображается на правильной трассировке на портале.

Полный рабочий пример см. в sample_human_evaluations.py.

Просмотр заметок на странице трассировки

После добавления аннотаций (через портал или программно) они отображаются на странице сведений о трассировке.

1. Откройте проект Foundry и перейдите в раздел Tracing.
2. Выберите трассировку с заметками.
3. На странице сведений о трассировке значки аннотаций отображаются рядом с аннотированными участками. Значок вверх показывает положительные отзывы и значок вниз указывает на отрицательные отзывы.
4. Наведите указатель мыши на заметку, чтобы просмотреть метаданные, включая имя источника (builder или end_user), имя оценки и метку времени.

В представлении списка трасс аннотации отображаются в компактном виде: встроенно показывается только самая последняя аннотация, а если у трассы есть несколько аннотаций, индикатор «+X ещё» указывает на наличие дополнительных аннотаций. Выберите трассировку, чтобы увидеть все аннотации.

Фильтрация трассировок по заметкам

Список трассировок можно фильтровать по следующим параметрам:

• Тип оценки (gen_ai.evaluation.name): значение равно "task_completion".
• Значение или метка оценки (gen_ai.evaluation.score.value, gen_ai.evaluation.score.label): например, показывать только трассировки с отрицательной оценкой.
• Источник (microsoft.gen_ai.human_evaluation.source): отображаются только заметки построителя или только отзывы конечных пользователей.

Эти измерения фильтров отображаются вместе с существующими фильтрами трассировки (диапазон времени, агент, состояние, модель).

Заметки запросов в Application Insights

Все аннотации публикуются в Azure Monitor / Application Insights и прикрепляются к исходной трассировке. К аннотациям можно выполнять запросы с помощью языка запросов Kusto (KQL) для анализа закономерностей в отзывах, создания панелей мониторинга и настройки оповещений.

Сводка отзывов по источнику и деньу

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

Найти трассы с отрицательной обратной связью

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

Связанный контент

• Регистрировать отзывы конечных пользователей
• Настройка трассировки в Microsoft Foundry
• Просмотр взаимодействий агента с помощью Trace Replay
• Мониторинг агентов с помощью панели мониторинга агента