建立評估資料集與評估器

代理優化器會根據評估者評分的一系列任務資料集來評估你的代理。 你可以從 CLI 自動產生兩者,或手動建立資料集以完全控制。

這兩個部分對良好優化至關重要:資料集定義要測試 什麼 ,評估者則定義 如何 判斷每個回應。 較弱的評估器會產生含雜訊的分數,導致最佳化效果不佳,因此對強大的評估器應投入與具代表性任務同等的重視。

建立這些資產是 優化流程的第二步,前提是 讓你的代理人準備好使用優化器。 優化器會用這些數據來評分你的基準並排名候選人。

先決條件

  • 具有已部署代管代理程式的 Foundry 專案。
  • Azure Developer CLI (azd),版本 1.37.0 或更新版本,為azure.ai.agents擴充功能所需。
  • azure.ai.agents已安裝 CLI 擴充功能,版本為 1.0.0-beta.22 或更新版本 (請參閱快速入門:最佳化託管的 Agent)。
  • 這個 azure.ai.evaluations 擴充功能提供 azd ai eval 指令,且需要 azd 1.33.0 或更新版本。 microsoft.foundry 擴充套件沒有包含它,所以要另外安裝。
  • 一個經過 azd 認證的會話。 要檢查你的認證狀態,請執行 azd auth status。 如果你尚未登入,請執行 azd auth login。

最佳化工具會重複使用您透過azure.ai.evaluations擴充功能中的azd ai eval命令建立的評估資產。 azd ai agent eval指令群組已被棄用。 它只會列印遷移指引到 azd ai eval,不會發出服務請求或更改專案檔案。 優化器不支援舊版代理 eval.yaml 檔。

根據您的代理程式指示,產生資料集和評分標準評估器:

azd extension install azure.ai.evaluations
azd ai eval generate \
  --from prompt \
  --target <agent-name> \
  --generation-model <generation-deployment> \
  --agent-instruction "<agent-instructions>" \
  --no-prompt

預設情況下,指令會產生:

  • 供您的 Agent 使用的資料列資料集。
  • 一個自訂評分規準評估工具,是一個包含加權評分維度的可編輯 JSON 檔案。

命令會下載兩個成品,並為每個成品新增一個目錄條目到評估組態中,其預設值為evals/azure.eval.yaml。 除非你設定 --dataset-name 或 --evaluator-name,否則資料集名稱為 <deployed-agent>-turn-tests,評估器名稱為 <deployed-agent>-evaluator。 關於互動式與非互動式選項及產生產物的詳細資訊,請參見「產生資料集與評估器」。

接著用產生的資產建立評估架構。 優化器會重用針對你代理人的回合層級評估,因此設定 --evaluation-level turn 和 --target。 此範例將內建builtin.task_adherence評估工具新增至產生的評分規準評估工具中:

azd ai eval init \
  --source dataset \
  --evaluation-level turn \
  --target <agent-name> \
  --dataset <generated-dataset-name> \
  --evaluator <generated-evaluator-name>,builtin.task_adherence \
  --judge-model <judge-deployment> \
  --name optimizer-eval \
  --no-prompt

執行優化器並依名稱選擇評估:

azd ai agent optimize --eval optimizer-eval --optimize-model <optimization-deployment>

要自訂產生的資產,請參見 「自訂評估者 」及 「建立自訂資料集」。 要選擇執行所使用的評估,請參見「為執行選取評估」。 如需其他執行選項,請執行 azd ai agent optimize --help。

選擇某次執行的評估

azd ai agent optimize會從azd ai eval init宣告的評估讀取資料集及評估工具。 選擇以下其中一個評估:

Option Behavior
--eval <name> 選取具有該名稱的評估。 若無 --eval-config,優化器會讀取 azure.yaml 中的 azure.ai.eval 服務,而這些服務是由 azd ai eval init 新增的。
--eval-config <path> 從由 azd ai eval init 建立的設定檔讀取評估值,例如 evals/azure.eval.yaml,而不是從專案的服務讀取。 新增--eval以選取該檔案中的一個評估。

優化器套用以下規則:

  • 它僅考慮有agent目標的評估。 目標名稱必須與已部署的代理名稱或在 azure.yaml 中的代理服務名稱相符。
  • 它僅重複使用會讀取資料集的回合級評估。 不支援宣告source或simulation,或使用交談層級的評估,也不支援設定dataMapping的評估工具。
  • 如果您沒有傳遞這兩個選項,且專案只有一個相符的評估,最佳化工具就會使用它。 如果有多個相符項目,優化器會提示你選擇一個。 若使用 --no-prompt 或 -o json,指令會失敗並要求您提供 --eval。
  • 如果您傳遞--eval或--eval-config,且沒有符合的評估,命令就會失敗。

該 --config 選項接受獨立的優化請求檔案。 你無法將它與 --eval 或 --eval-config合併。

使用這些旗標覆寫或擴充評估所提供的內容:

  • --dataset 取代評估所使用的資料集。 將本地的 JSONL 檔案或註冊資料集傳給 name:version。
  • --evaluator 依名稱新增一個內建或自訂的評估器。 重複旗標以新增一個以上。 已在該評估中列出的評估器不會被重複加入。
  • --eval-model 設定評估回應的模型。 若無此,優化器會使用評估者在初始化參數中宣告的模型。 如果他們宣告不同模型,請傳遞--eval-model。

如果專案沒有針對您的 Agent 的評估,請直接傳遞資料集和評估工具:

azd ai agent optimize <agent-name> \
  --dataset eval.jsonl \
  --evaluator builtin.task_adherence \
  --eval-model <judge-deployment> \
  --optimize-model <optimization-deployment>

自訂評估器(進階)

評估者會對每位代理人的回應進行評分。 優化器支援兩種類型:

  • 內建的評估器,例如 builtin.task_adherence,會將每個任務層級的標準評為通過或不通過。
  • 自訂評分標準評估工具,能根據您的代理程式調整,在多個品質維度上評分回應。 azd ai eval generate會建立一個,並將其下載為可編輯的評分規準 JSON 檔案。

對大多數經紀人來說,產生的評分標準評估器會給出最有意義的分數,因為它是針對你的領域量身打造的。 編輯產生的評分規準檔以細化維度,然後執行 azd ai eval evaluator update <name> --from-file <path> 以發布變更為新版本。 關於產生、編輯及版本管理評估器的詳細資訊,請參見 「產生資料集與評估器」。

若要在執行中使用評估工具,請在評估中使用azd ai eval init --evaluator將其列出,或透過azd ai agent optimize --evaluator <name>傳遞它。 請參閱為執行選取評估。

建立自訂資料集(進階)

當你需要精確控制測試情境或有生產資料可直接使用時,可以建立自訂資料集。 建議的做法是在由 azd ai eval generate 產生的資料集上不斷迭代。 將其精煉成本地資料集,或指向你 Foundry 專案中已註冊的另一個資料集。

選擇資料集來源

資料集可來自兩種來源之一:

  • Foundry 資料集:已在你的 Foundry 專案中註冊的資料集。 以 --dataset <name>:<version> 傳遞它,或在你的評估配置的 datasets 目錄中以 name 和 version 宣告。 優化器需要名稱和版本。
  • 本地資料集:一個你撰寫並保存在專案中的 JSONL 檔案。 使用--dataset傳遞其路徑,或在datasets目錄中使用file宣告它。 相對 --dataset 路徑會從目前目錄解析。 相對 file 路徑會以評估設定檔為基準解析。

兩個來源都使用下一節所述的相同任務架構。 若要為執行選取資料集,請參閱為執行選取評估。

資料集結構

資料集使用 JSONL (JSON Lines)格式。 每一行代表一個 JSON 物件,代表單一評估 任務——一個獨立的情境。 任務包含提示(query),以及可選的任務層級 criteria。

{"name": "task_1", "query": "Your prompt here"}
{"name": "task_2", "query": "Another prompt", "ground_truth": "Expected answer"}
Field Required Description
name Yes 唯一任務識別碼(例如, "greeting", "math_test")。
query Yes 傳送至代理程式的訊息。
ground_truth No 這是評估者支持推薦信時會用的預期答案。
criteria No 選擇性的任務層級檢查。 請參見 新增任務層級標準。

使用本地資料集時,先驗證 JSONL 語法再執行優化:

python -c "import json; [json.loads(l) for l in open('eval.jsonl')]"

新增任務層級標準

標準為可選。 你為此次執行選擇的 評估器會套用到資料集中的每個任務。 只有在特定任務需要這些共用評估器以外的額外檢查時,才新增個別任務專用的 criteria。 當任務存在時, criteria 會被評分並與共享評估者一同彙整,以產生任務的整體分數。

Field Required Description
criteria[].name Yes 準則的簡稱(例如, "is_polite")。
criteria[].instruction Yes 評估員會檢查什麼。 要具體且可測試。

以下客戶支援資料集顯示具有任務層級標準的任務:

{"name": "refund_policy", "query": "What is your refund policy?", "criteria": [{"name": "mentions_30_days", "instruction": "Response must mention the 30-day refund window"}, {"name": "polite_tone", "instruction": "Response must be professional and empathetic"}]}
{"name": "order_status", "query": "Where is my order #12345?", "criteria": [{"name": "asks_for_details", "instruction": "Agent should ask for email or order details to look up the order"}, {"name": "no_hallucination", "instruction": "Agent must NOT make up a fake order status"}]}
{"name": "out_of_scope", "query": "Can you help me fix my car?", "criteria": [{"name": "polite_decline", "instruction": "Agent should politely explain this is outside its scope"}, {"name": "redirect", "instruction": "Agent should suggest contacting an appropriate service"}]}

用 CLI 註冊並版本化資料集

若要在一次優化器執行之外重複使用資料集,請安裝另外發布的資料集擴充功能:

azd ext install azure.ai.dataset
azd ai project set <project-endpoint>
azd ai dataset create support-golden --from-file ./support-golden.jsonl

--from-file 接受 JSONL 檔案或包含 JSONL 的目錄。 用 --version 來明確選擇版本;否則指令會發布下一個版本。 在比較代理變更時,保持用於評估的版本不變。

發布修訂後的數據並檢視各版本:

azd ai dataset update support-golden --from-file ./support-golden-v2.jsonl
azd ai dataset list --all
azd ai dataset show support-golden
azd ai dataset versions list support-golden

list 預設回傳 20 個條目。 使用--limit取得較小的分頁、使用--all取得所有分頁,並重複使用--tag key=value以要求符合多個標籤。

下載已註冊的版本以重現執行:

azd ai dataset download support-golden --version 1.0 \
  --output-dir ./downloaded-dataset

僅將 --output-file 用於單一檔案資料集。 現有檔案除非你傳入 --force,否則不會被覆寫。 若未指定--version,則會下載最新版本,並回報所選的版本。

要移除某個版本,請執行 azd ai dataset delete support-golden --version <version>。 必須指定 --version 旗標;省略時會回傳錯誤。 非互動式刪除需要明確指定 --force。

該 azd ai eval dataset 群組透過評估擴充功能公開相同的生命週期。 註冊資料並不代表每個 JSONL 架構都可以互換:請保持評估者和目標端所需的列結構。

撰寫優質資料集的技巧

包含邊緣案例

測試愉快路徑以外的情況。 包括:

  • 超出範疇的請求 — 您的代理應拒絕或重新導向的輸入內容
  • 模糊查詢 — 客服應要求釐清的任務
  • 對抗式輸入 — 試圖誘使代理產生不當行為
  • 多步驟任務 — 需要結構化推理的複雜請求

尺寸指引

資料集大小 取捨
3–5 任務 快速迭代,訊號有限
5至10項任務 速度與覆蓋範圍的平衡良好
10–20 項任務 全面評估,長距離跑
20 項以上任務 詳盡但速度較慢——可考慮用於最終驗證

較大的資料集能提供更廣泛的覆蓋範圍,但評估時間較長。

在需要時提供地面真實資訊

該 ground_truth 欄位提供評估者一個可比較的參考答案。 這並非必須——評估者也可以僅根據指示和任務層級的標準判斷回應。

{"name": "geography_fact", "query": "What is the largest city in France by population?", "ground_truth": "Paris", "criteria": [{"name": "correct_answer", "instruction": "Response must state that Paris is the largest city in France by population"}]}

寫出像真實使用者一樣的提示

如果可能的話,使用用戶的真實訊息。 真實提示捕捉了你的代理人在生產過程中所面臨的詞彙和語境,這也幫助你撰寫切實可行的任務層級標準。

要具體說明標準

模糊的標準會導致評分不一致。 讓每個標準具體且可測試。

缺點:

{"name": "good_answer", "instruction": "The response should be good"}

良好:

{"name": "mentions_30_days", "instruction": "Response must explicitly mention the 30-day refund window"}

Troubleshooting

Problem 原因 修復
dataset file "<path>" is not accessible 你傳遞給 --dataset 的路徑不存在 可以使用相對於目前目錄的路徑或絕對路徑。
failed to read JSONL file <path> 評估宣告的本機資料集file路徑不存在或無法讀取 使用相對於評估設定檔的 file 路徑。
invalid JSON line in <path> JSONL 格式錯誤 確認每行都是有效的 JSON。 檢查後尾逗號。
--dataset requires name:version for a registered dataset, or a local JSONL file 這個 --dataset 值既不是檔案路徑,也不是 name:version 傳遞 .jsonl 檔案的路徑,或以 name:version 傳遞已註冊的資料集。
a dataset is required 沒有來自 --dataset 或所選評量的資料集。 傳遞--dataset、重複使用宣告資料集的評估,或執行azd ai eval generate。
at least one evaluator is required 沒有來自 --evaluator 或所選評估的評估者 傳遞--evaluator <name> (可重複),或重複使用列出評估工具的評估。
no evaluation matches the selected eval and agent 沒有任何評估符合你傳入的名稱,或者沒有任何代理目標符合你要優化的代理程式 檢查評估值的 name 和 target,或用宣告它的設定檔傳入 --eval-config。
multiple evaluations match; specify --eval 多個評估針對 Agent,提示也不一致 按一下 --eval <name>,如果需要選擇設定檔,則再按一下 --eval-config。
optimizer eval reuse currently requires a turn dataset and an agent target 所選評估會讀取痕跡、模擬對話或評分對話 選擇針對該代理人的回合級資料集評估。
legacy optimization/eval configuration is not supported 檔案 --config 有頂層 agent 金鑰,就像舊代理 eval.yaml 一樣 使用azd ai eval init建立評估,並透過--eval加以選取,或傳遞最佳化要求檔案。
執行之間的分數不一致 模糊的標準 讓標準具體且可測試。