代理優化器會根據評估者評分的一系列任務資料集來評估你的代理。 你可以從 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指令,且需要azd1.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加以選取,或傳遞最佳化要求檔案。 |
| 執行之間的分數不一致 | 模糊的標準 | 讓標準具體且可測試。 |