人間のフィードバックを使用してトレースに注釈を付ける (プレビュー)

Important

この記事でプレビューとしてマークされているアイテムは、現在プレビュー段階です。このプレビューはサービスレベルアグリーメント（SLA）なしで提供されており、Microsoft はこれを運用ワークロードでの使用に推奨していません。特定の機能がサポートされていないか、機能が制限されている可能性があります。詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。

Microsoft Foundry のトレースにサムアップまたはサムダウン注釈を追加して、個々のエージェントの相互作用に関する人間の品質シグナルをキャプチャします。トレース注釈を使用すると、エージェントの応答が役に立ったか役に立たなかったかをマークできます。また、エージェントの動作のパターンをすばやく識別できるように、それらはトレースの詳細ページにインラインで表示されます。

トレース注釈は、次の 2 つのワークフローをサポートします。

ビルダーの注釈: ビルダーとドメインエキスパートは、エージェントの相互作用を確認しながら、Foundry ポータルからのトレースに注釈を付けます。これらの注釈は、 builderのソースで自動的にタグ付けされます。
エンドユーザーのフィードバック: エンドユーザーがサムアップフィードバックまたはサムダウンフィードバックを提供するときに、アプリケーションからプログラムで注釈をログに記録します。これらの注釈は、 end_user のソースを保持し、ビルダーの注釈と共にトレースページに表示されます。エンドユーザーフィードバックのログ記録の詳細については、「エンドユーザーフィードバックのログ記録」を参照してください。

すべての注釈がトレースに 追加されます 。ビルダー注釈を追加しても、既存のエンドユーザーのフィードバックが上書きされたり置き換えられたりすることはありません。また、その逆も同様です。各注釈にはソース属性が含まれているため、シグナルは個別にクエリ可能でフィルター可能なままです。

Prerequisites

Application Insights リソースが接続された Foundry プロジェクト。トレースの設定を参照してください。
アプリケーション内で構成された OpenTelemetry インストルメンテーション。セットアップ手順については、「 Microsoft Foundry でトレースを設定する」を参照してください。
プログラムによる注釈の場合: azure-ai-projects パッケージと azure-monitor-opentelemetry パッケージがインストールされています。
```
pip install "azure-ai-projects>=2.0.0" azure-monitor-opentelemetry python-dotenv
```
Microsoft Entra認証された Application Insights インジェストを使用するプログラムによる注釈の場合: テレメトリを出力する ID には、接続された Application Insights リソースに対する Monitoring Metrics Publisher ロールがあります。セットアップと ID 固有のガイダンスについては、「トレースインジェストのMicrosoft Entra認証を構成する」を参照してください。

既定のスコアリングテンプレート

すべての Foundry プロジェクトには、追加のセットアップなしですぐに使用できる既定のサムアップ/ダウンスコアリングテンプレートが用意されています。 1 日目にトレースに注釈を付けることができます。既定のテンプレートでは、バイナリの合格/失敗スコアリングが使用されます。

高評価 = スコア 1.0、ラベル pass
低評価 = スコア 0.0、ラベル fail

各スコアリングテンプレートでは、すべての注釈が特定の評価ディメンションに紐付けられるように、gen_ai.evaluation.name 属性の値を task_completion にする必要があります。 task_completion は、高評価と低評価に対応しています。

Foundry ポータルでトレースに注釈を付ける

トレースの詳細ページから注釈を直接追加して、エージェントの応答の評価を記録します。

Foundry プロジェクトを開き、左側のナビゲーションで [トレース ] に移動します。
トレースを選択して、トレース詳細ビューを開きます。
トレースの詳細ページで、右上隅にある [ 注釈 ] ボタンを選択します。
スコアを送信するには、高評価または低評価を選択します。必要に応じて、フリーテキストの説明を追加します。
注釈はすぐに保存され、トレースに表示されます。

Note

トレースの表示と注釈の保存は、個別の認可操作です。トレースが表示されていても注釈を保存できない場合は、注釈の宛先、実際の書き込み ID、および認証パスを確認します。別のトレースリーダーのロールには、テレメトリへの書き込みアクセス権は付与されません。

ポータルから追加した注釈には、次のタグが自動的に付きます。

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

スコア編集

各ユーザーは、複数回注釈を付けることができます。

複数のユーザーがそれぞれ、同じトレースで同じ型の独自の注釈を持つことができます。
Application Insights では、以前の注釈は削除されません。新しい注釈が追加され、ポータルには注釈パネルの注釈履歴セクションにすべての注釈が表示されます。

エンドユーザーのフィードバックをトレース注釈としてログに記録する

エンドユーザーがアプリケーションでサムアップフィードバックまたはサムダウンフィードバックを提供すると、そのフィードバックをログに記録して、対応するトレースに注釈として表示されるようにすることができます。この方法では、 gen_ai.evaluation.result OpenTelemetry イベントが使用され、フィードバックは元のトレースに自動的に関連付けられます。

注釈属性スキーマ

サムアップまたはサムダウン注釈を出力する場合は、次の属性を使用します。

Attribute	価値	説明
`gen_ai.evaluation.name`	`task_completion`	評価メトリック名
`gen_ai.evaluation.score.value`	`1.0` (サムアップ) または `0.0` (サムダウン)	数値スコア
`gen_ai.evaluation.score.label`	`"pass"` または `"fail"`	カテゴリラベル
`gen_ai.evaluation.explanation`	省略可能なフリーテキストコメント	レビュアーの説明
`gen_ai.response.id`	たとえば、`"chatcmpl-123"` のように指定します。	注釈とトレースされた応答の関連付けに使用される AI 応答 ID
`microsoft.gen_ai.human_evaluation.source`	`"end_user"` または `"builder"`	フィードバックプロバイダーの種類
`microsoft.gen_ai.evaluation.actor.type`	`"human"`	注釈が人間の校閲者によって送信されたことを示し、自動評価とは区別します
`operation_Id`	`trace_Id`	Application Insights の元のトレース要求に注釈をリンクします。
`operation_ParentId`	`span_Id`	注釈が付けられたトレース内の特定のスパンのスパン ID が含まれます
`gen_ai.agent.id`	エージェントリソース識別子の文字列	注釈が付けられている応答を生成したエージェントの一意の識別子
`gen_ai.agent.name`	エージェントの表示名の文字列	注釈が付けられた応答を生成したエージェントの表示名
`gen_ai.agent.version`	バージョン文字列 `1`、 `2`、または `3`	`internal_properties`内に配置され、注釈付き応答が生成された時点のエージェントのバージョン

評価イベントは、注釈を付けるエージェントとのやり取りと同じトレースコンテキスト内 (同じトレース ID とスパン ID を使用) で発行する必要があります。この相関関係により、ポータルの正しいトレースに注釈が確実に表示されます。

実行可能な完全な例については、 sample_human_evaluations.pyを参照してください。

トレースページで注釈を表示する

(ポータルまたはプログラムから) 注釈を追加すると、トレースの詳細ページに注釈が表示されます。

Foundry プロジェクトを開き、[トレース] に移動 します。
注釈を含むトレースを選択します。
トレースの詳細ページで、注釈付きスパンの横に注釈アイコンが表示されます。サムアップアイコンは肯定的なフィードバックを示し、サムダウンアイコンは否定的なフィードバックを示します。
注釈にカーソルを合わせると、ソース (builder または end_user)、評価名、タイムスタンプなどのメタデータが表示されます。

トレースリストビューでは、注釈はコンパクトな処理で表示されます。最新の注釈のみがインラインで表示され、トレースに複数の注釈が存在する場合は、"+X more" インジケーターが追加の注釈を使用できます。トレースを選択すると、すべての注釈が表示されます。

注釈でトレースを絞り込む

トレース一覧は、次の方法でフィルター処理できます。

評価の種類 (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

注釈の書き込みに関するトラブルシューティング

症状:	確認
トレースは表示できますが、ビルダー注釈の保存は認証エラーにより失敗します	保存は別の書き込み操作として扱います。接続されている Application Insights リソース、書き込みに使用される ID、接続認証モードを確認します。一般的な対処法として、別の「閲覧者」ロールを追加しないでください。
プログラムによる注釈は、`401` または `403` を返します	アプリケーションが予想される Application Insights リソースにテレメトリを送信することを確認します。 Microsoft Entra による認証を経たデータ取り込みを行うには、そのリソースに対して、テレメトリを送信する ID にMonitoring Metrics Publisherの権限を付与してください。
アプリケーションは成功と表示されますが、注釈は表示されません	評価イベントで元のトレースとスパンコンテキストが使用されていること、トレースと同じ Application Insights リソースに送信されたこと、およびインジェストが完了したことを確認します。
間違ったトレースに注釈が表示される	イベントを生成する前に、 `operation_Id`、 `operation_ParentId`、および `gen_ai.response.id` を確認します。

フィードバック

このページはお役に立ちましたか?

最終更新: 2026-10-08