使用人工意見註解追蹤資料（預覽）

Important

本文中標示為預覽的項目目前仍在預覽中。此預覽版未簽訂服務等級協議，Microsoft 不建議用於生產工作負載。某些功能可能不被支援或功能受限。欲了解更多資訊，請參閱 Microsoft Azure 預覽版補充使用條款。

在 Microsoft Foundry 中為追蹤新增讚或倒讚註解，以擷取個別 Agent 互動上的人工品質訊號。追蹤註解可以讓你標示代理的回應是否有幫助或無益，並且會直接顯示在追蹤細節頁面，讓你能快速辨識代理行為的模式。

追蹤註解支援兩種工作流程：

建置者註解： 建置者和領域專家會在檢視代理程式互動時，為 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 資料擷取的程式化註釋：發出遙測的身分識別在已連線的 Application Insights 資源上具有監控計量發佈者角色。關於設定及特定身份的指引，請參見「設定 Microsoft Entra 認證以進行追蹤擷取」。

預設計分範本

每個 Foundry 專案都預先提供預設的按讚／倒讚評分範本，無需額外設定即可立即使用。您可以從第一天開始標註追蹤。預設範本採用二元通過/失敗評分：

讚 = 分數 1.0，標籤 pass
大拇指向下 = 分數 0.0，標籤 fail

每個評分範本都要求 gen_ai.evaluation.name 屬性的值必須為 task_completion，因此每個註解都可歸因於特定的評估維度。 task_completion 支援讚和倒讚。

在 Foundry 入口網站中標註追蹤

直接從追蹤詳細頁面新增註解，記錄你對客服人員回應的評估。

打開您的 Foundry 專案，然後在左側導覽中前往 Tracing。
選擇一條走線以開啟走跡細節檢視。
在追蹤詳細資料頁面中，按一下右上角的註解按鈕。
點選讚或倒讚來提交你的評分。可選擇性地加入自由文字說明。
註解會立即儲存，並顯示在追蹤記錄中。

Note

查看追蹤與儲存註解是分開的授權操作。如果追蹤可見但註解無法儲存，請驗證註解目的地、實際寫入身份及認證路徑。另一個追蹤讀取器角色則不賦予遙測寫入權限。

你從入口網站新增的註解會自動標註：

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 回應識別
`microsoft.gen_ai.human_evaluation.source`	`"end_user"` 或 `"builder"`	回饋提供者類型
`microsoft.gen_ai.evaluation.actor.type`	`"human"`	表示註解是由人工審核者提交，與自動評估區分開來
`operation_Id`	`trace_Id`	將註解連結至應用程式洞察中的原始追蹤請求
`operation_ParentId`	`span_Id`	包含被註解路徑中特定跨度的跨度識別碼
`gen_ai.agent.id`	代理資源識別字串	產生該已加註回應之代理人的唯一識別碼
`gen_ai.agent.name`	Agent 顯示名稱字串	產生被標註回應之代理程式的顯示名稱
`gen_ai.agent.version`	版本字串 `1`、 `2`，或 `3`	位於 `internal_properties` 內、產生註解回應時的代理程式版本

您必須在與其所標註之 Agent 互動相同的追蹤內容中發出評估事件 (使用相同的追蹤 ID 和 Span ID)。此關聯可確保註解會顯示在入口網站中的正確追蹤上。

完整可執行範例請參見 sample_human_evaluations.py。

請在追蹤頁面查看註解

在你從入口網站或程式化添加註解後，它們會出現在追蹤詳細頁面上。

打開你的 Foundry 專案，進入追蹤。
選取具有註解的追蹤。
在描圖細節頁面上，標註圖示會出現在標註區間旁。豎起大拇指圖示表示正面回饋，向下大拇指圖示表示負面回饋。
將滑鼠移到註解上即可查看元資料，包括來源（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 監視器 / 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 資源、寫入時使用的身份，以及連線驗證模式。請勿再新增另一個讀取者角色作為通用的修復方法。
程式化註解會回傳 `401` 或 `403`	確認應用程式是否將遙測資料傳送到預期的 Application Insights 資源。對於使用 Microsoft Entra 驗證的擷取，請授與在該資源上發出遙測的身分識別監控計量發佈者角色。
應用程式報告成功，但註解卻不出現	確認評估事件使用原始的追蹤與跨度上下文，且傳送到與追蹤相同的 Application Insights 資源，且該擷取已完成。
註解出現在錯誤的追蹤線上	在發出事件前，先驗證 `operation_Id`、`operation_ParentId` 和 `gen_ai.response.id`。

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-10-08