使用 azd CLI 執行代理程式評估(預覽版)

Important

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

利用這個azd ai eval擴充功能,為用 Microsoft Foundry 建置的代理程式加入一個測量品質迴圈。 你可以在專案旁邊搭建評估,選擇產生資料集和評分標準評估器,將評估結果與代理人對比,並在不離開終端機的情況下讀取結果。

同一項評估可以從管線執行,而 --fail-on 會將其結果轉換成建置閘門。

本文涵蓋使用 azd ai eval init 和 azd ai eval run start 進行的首次評估。

先決條件

  • 擁有存取 Microsoft Foundry 的 Azure 訂閱。
  • Azure Developer CLI (azd),版本 1.33.0 或更新版本。 安裝說明請參見 安裝Azure開發者 CLI。
  • 提供指令 azd ai eval 的 azure.ai.evaluations 擴充功能,版本須為 1.0.0-beta.2 或更新版本。 請參見 安裝擴充功能。
  • 一個經過 azd 認證的會話。 要檢查你的認證狀態,請執行 azd auth status。 如果你尚未登入,請執行 azd auth login。
  • Foundry 資源上的 Foundry User 角色(前稱 Azure AI User)。 欲了解更多資訊,請參閱 Microsoft Foundry 的 基於角色的存取控制。
  • 關於所有評估角色的需求,請參閱 「設定評估工作流程權限」。
  • 已初始化的azd專案和環境,可識別您的 Foundry 專案。 如需設定,請參閱 設定 Foundry 專案上下文。
  • 一個用於輪次資料集、模擬對話或追蹤的代理。 若要讓init在本機偵測它,請如同azd ai agent init所做的那樣,在azure.yaml中宣告一項 Agent 服務。 否則,請使用--target傳遞其部署的名稱。 靜態交談不需要 Agent 目標。 關於託管代理,請參見託管代理。
  • 您使用之角色的支援模型部署:分級、選用成品產生,以及選用使用者模擬。 明確設定每個角色;為某個角色使用一個部署並不會設定其他角色。
  • 一個真實的 JSONL 資料集或已註冊的資料集,用於以資料集為來源的評估。 或者,在設定評估前先產生資料集。 init 不會建立樣本列。

安裝擴充套件

安裝擴充功能 azure.ai.evaluations,其提供 azd ai eval 指令。 microsoft.foundry擴充功能不包含此項目,所以請另外安裝:

azd extension install azure.ai.evaluations

如果擴充功能已經安裝,請升級到最新版本:

azd extension upgrade azure.ai.evaluations

如果你需要獨立 azd ai dataset 指令,也請安裝 azure.ai.dataset:

azd extension install azure.ai.dataset

這兩個擴充功能都需要 azd 1.33.0 或更新版本。

確認安裝情況

請檢查已安裝的擴充套件版本及可用的旗標:

azd version
azd extension list --installed
azd ai eval version
azd ai eval init --help
azd ai eval generate --help
azd ai eval run start --help

如果你也使用 azure.ai.agents 或獨立的 azure.ai.dataset 擴充功能,請分別檢查它們:

azd ai agent version
azd ai dataset version

請確認評估擴充功能為 1.0.0-beta.2 或更新版本。

這些擴充功能各自具有獨立版本。 代理人擴充功能不會取代評估擴充功能,獨立資料集擴充功能也不需要用於 azd ai eval dataset。 如果 init --help 沒有列出 --conversation-mode 和 --simulation-model,請先升級擴充功能,再依照對話範例操作。

azd 評估的運作方式

你可以用 evals/azure.eval.yaml 檔案來描述評估。 你可以閱讀、編輯並提交這個檔案。 指令要麼寫入該檔案,要麼依據它宣告的指令來操作。

azd ai eval init          # scaffold the configuration without invoking an agent
azd ai eval generate      # optional: synthesize a dataset and a rubric evaluator
azd ai eval create        # register the eval in the Foundry project
azd ai eval run start     # run it and summarize the results
Item Description
init 搭建 evals/azure.eval.yaml,並新增評估服務至 azure.yaml。 不會叫用 Agent 或產生資料。
generate 合成資料集、評分規準評估工具或兩者,下載後在設定中為每一項新增一筆目錄項目。 提交計費的產生工作。
evals/azure.eval.yaml 評估流程:評估內容、列數來源,以及評分者。
create 將宣告的資料集、評估器及評估本身登錄於專案中。
run start 啟動執行,依預設會等待該次執行完成,並列印每個評估工具的摘要。
run output list 該摘要背後的逐一樣本結果。
dataset,evaluator 直接管理註冊資料集與評估器,包括 versions list。
job 檢視、取消及刪除由 generate 提交的生成作業。

-o json用於腳本編寫和--debug診斷。 由服務支援的命令接受 --project-endpoint;init 則改用本地專案與環境的元資料。

選擇資料列的來源

評估會為資料列評分。 本文中的例子使用了以下兩個來源之一:

  • --source traces透過讀取 Agent 發出的追蹤記錄來評估其您的 Agent 已完成的工作。 你不需要自行建立資料集。
  • --source dataset 評估一組固定的範例,可能是你的或是自己生成的。 固定資料集讓你能比較不同代理版本的結果。

以追蹤為來源的評估,需要會發出追蹤的 Agent。 來自資料集的評估需要 .jsonl 檔案或已註冊的資料集。

對於資料集,選擇一列代表什麼:

撰寫路徑 init 的選項 執行過程中會發生什麼事
轉換資料集 --source dataset --evaluation-level turn --target <agent> 對每個輸入呼叫代理人並評估回應。
已完成的對話 --conversation-mode static 從資料集對已完成的訊息進行評分,且不叫用 Agent 不要傳遞 --target。
模擬對話 --conversation-mode simulation --target <agent> --simulation-model <deployment> 使用情境種子模擬使用者與代理互動,然後評估對話內容。

唯一的 --conversation-mode 值是 static 和 simulation。 當你省略這些選項時,任一值都表示 --source dataset 和 --evaluation-level conversation。 追蹤是獨立的來源,不是一個交談模式。

對於交談資料集,為該模式提供互動式init提示。 若無提示,省略模式預設為static。 當您的資料集包含情境種子而非完整逐字稿時,請明確選擇 simulation。

建構評估框架

使用你現有且已初始化的 azd 專案。 如果你需要為已部署的代理建立新的本地工作空間,請從新目錄執行以下指令:

azd init --minimal --no-prompt -e evaluation
azd env set FOUNDRY_PROJECT_ENDPOINT "<your-project-endpoint>"

用你的 Foundry 專案端點取代 <your-project-endpoint> 。 這種設定不會部署 Agent。

從你的專案根執行 init ,互動式選擇輸入:

azd ai eval init

init 讀取本地專案與環境的元資料,以偵測代理服務與模型部署。 它不會發現服務中已部署的代理或模型。 傳遞給 --target 的本地代理服務金鑰會解析為該服務宣告的遠端代理名稱;你也可以直接傳遞已部署的代理名稱。

init 寫入 evals/azure.eval.yaml 並新增評估服務到 azure.yaml。 它不會部署或呼叫代理程式、產生資料集或註冊評估資源。 你可以在部署前撰寫設定,但基於代理的執行需要已部署的目標。

init會離線運作,除了兩個查找外。 你選擇的 builtin.* 評估器,包括 --no-prompt 下的預設評估器,都可以觸發一次最佳努力目錄查詢,並設有五秒逾時。 符合資格的connection-name/model-deployment模擬參考,或--simulation-model的連線探索,會查找 Foundry 專案中的連線。 如果無法完成評估器目錄查詢,則 init 保留原樣寫入的參照。 如果查找成功,init會拒絕目錄未列出的builtin.*名稱。 取消命令仍然會使其停止。

如果某個必要值無法在本機端解析,互動式 init 提示就會要求提供該值。 在 --no-prompt 或 -o json下,明確提供所有未解決的輸入。 對於沒有代理服務的專案中,基於代理人的評估,請提供 --target。

請根據你需要的來源和模式,選擇以下初始化範例之一。 範例使用預留位置 Agent、資料集和部署名稱。 用你自己的資源取代它們;擴充功能沒有提供這些。

對於追蹤來源型評估,請直接傳遞決策:

azd ai eval init \
  --source traces \
  --target support-agent \
  --judge-model judge-deployment \
  --name support-trace-eval \
  --no-prompt

要評估你已經擁有的回合資料集:

azd ai eval init \
  --source dataset \
  --evaluation-level turn \
  --target support-agent \
  --dataset golden-turns \
  --evaluator builtin.intent_resolution,builtin.task_adherence \
  --judge-model judge-deployment \
  --name turn-quality \
  --no-prompt

--dataset 會選擇本地 .jsonl 路徑或註冊資料集名稱。 對於本地檔案,請提供一個現有的資料集,並包含你評估所需的欄位。

--evaluator 可重複且逗號分隔。 為內建評估工具,或與評估層級相容的已宣告自訂評估工具使用builtin.<name>。 傳遞 --evaluator 會取代預設值。它不會提交生成作業。

create 根據服務架構驗證評估器的可用性、支援的評估等級、初始化參數及所需欄位。 已成功建立 scaffold 的檔案並不代表每個評估者都能使用或與你的資料相容。

要找出內建名稱:

azd ai eval evaluator list --builtin

為已完成的對話評分

使用已完成的對話訊息資料集,無需代理程式目標:

azd ai eval init \
  --name static-quality \
  --conversation-mode static \
  --dataset completed-transcripts \
  --judge-model judge-deployment \
  --no-prompt

靜態模式不會寫入目標組態或模擬組態。 它會拒絕明確的--target。

模擬與智慧助理的對話

使用情境種子的資料集,並分開指定模擬使用者的模型和評審模型:

azd ai eval init \
  --name simulation-quality \
  --conversation-mode simulation \
  --target support-agent \
  --dataset scenario-seeds \
  --simulation-model simulator-deployment \
  --judge-model judge-deployment \
  --num-conversations 1 \
  --max-turns 5 \
  --no-prompt

代理人是在你開始執行時被調用,而不是在 init 期間。 --num-conversations 將每個種子的對話數設定為 1 到 5,預設為 1。 --max-turns 接受 1 到 20;若要使用服務預設值,請省略此項。 明確的零在這兩種設定中都無效。

在撰寫組態前,init會確認本機可用的模擬種子,若資料集無效,會提示提供修正後的資料集。 如果你指定 --no-prompt 或 --output json,則 init 會拒絕無效的本地種子,且不會更改已編寫的檔案。 它不會擷取僅限已註冊使用者的資料集內容。

--simulation-model接受部署名稱,或是選擇專案中 Azure OpenAI 連線的限定connection-name/model-deployment參考。 部署名稱不需要查詢連線。

請將每列翻轉設定放在simulation_configuration底下的種子中,而不是放在該列的頂層:

{"test_case_description":"Ask about an order, then request a refund.","simulation_configuration":{"desired_num_turns":3,"max_num_turns":5}}

所需的回合數必須為正數,且不超過該行的 max_num_turns,否則 --max-turns,或預設為 20。 一列的最大值會覆寫已撰寫的最大值。 這兩種設定都無法保證已完成對話的確切長度。

保持三個模型角色分開:

Option 命令 角色
--generation-model generate 產生資料集或評分規準評估器。
--simulation-model init 處於模擬模式 在執行期間扮演模擬使用者。
--judge-model init 配置評估者使用的模型以評分結果。

你可以明確地為多個角色選擇相同的部署。 模擬模型並非從生成模型或評判模型推斷而來。

確認本機輸入並選擇名稱

對於每個資料集模式,在 init 建立設定檔、鎖定檔案、忽略檔案或工件目錄前,先檢查本地檔案是否有非空的 JSONL 物件列。 格式錯誤的 JSON、陣列、標量、空物件和空資料集如果沒有這些寫入就會失敗。 將配置目的地與輸入資料集分開;同一個檔案的等效路徑會被拒絕。

明確指定的 --name 具有優先權。 否則,名稱用來識別資料集或追蹤來源、評估層級,以及靜態或模擬模式。 現有的宣告不會被重新命名。 只有當描述名稱已經存在時,才會加上數字後綴。 靜態評估可使用單一本地代理作為命名提示,而無需調用該代理。

在 Windows 上,避免使用包含命令-shell 環境變數語法的檔名,例如 %TEMP%。 shell 可以在擴充功能接收路徑前展開該文字。

產生資料集與評估器

如果你沒有資料集,或想為這個代理撰寫評分標準,請使用它的指示來進行提示種子生成:

azd ai eval generate \
  --from prompt \
  --target support-agent \
  --generation-model generation-deployment \
  --no-prompt

預設情況下,這會產生資料集和評分規準評估器、將它們下載到 evals/ 下,並在 evals/azure.eval.yaml 中為兩者各新增一筆目錄項目。 新增--dataset以僅產生一個資料集。 若要只產生評估器,請加入 --evaluator 並移除 --from prompt,因為 --from 只適用於資料集生成。

此無人值守範例使用 --from prompt。 如果擴充功能無法讀取目標代理程式的指令,則提供 --agent-instruction-file <path>。 具有--from agent的 Agent 種子型產生是一個獨立選項;--no-prompt不會授權在服務失敗後進行第二次可計費的僅提示重試。

請用 --max-samples 來請求 15 到 1000 列(預設:15 列)。 這個值是對產生服務的請求,所以請檢查產生資料集的列數。

generate 會提交需要耗用模型呼叫的作業。 若要提供您自己的生成指令,請使用 --agent-instruction 或 --agent-instruction-file。 描述代理人的實際目的以及你需要測試的事項。

為了產生模擬對話的情境種子,而非回合層級的範例:

azd ai eval generate \
  --dataset \
  --from prompt \
  --target support-agent \
  --evaluation-level conversation \
  --generation-model generation-deployment \
  --dataset-name scenario-seeds \
  --max-samples 15 \
  --no-prompt

生成的對話資料集包含種子,而非完整的逐字稿。 建議 init 指令選擇模擬模式並保留自訂的 --path。 使用模擬和評審模型部署完成它;無人參與的使用也需要--no-prompt。

目錄條目不會將成品連接到現有的評估。 使用產生的資料集名稱執行init,或在evals/azure.eval.yaml中更新預期的評估。 trace-sourced 評估會持續讀取 trace,直到你設定 dataset-sourced 評估為止。

若要提交這兩個工作並在稍後收集其成品:

azd ai eval generate \
  --from prompt \
  --target support-agent \
  --generation-model generation-deployment \
  --no-wait
azd ai eval job list --dataset
azd ai eval job show <dataset-job-id> --dataset
azd ai eval job list --evaluator
azd ai eval job show <evaluator-job-id> --evaluator

使用每個工作的獨特 ID 及其對應的 --dataset 或 --evaluator 標誌。 當工作執行時,job show會回報其狀態而不收集任何成品。 該任務成功後再跑 job show 一次,下載並宣告其 artifact,然後將 artifact 附加到你的評估中。

提供產生的說明和名稱

產生的列和評分標準的具體程度取決於描述代理人的說明。 generate 使用第一個存在的來源:

  1. --agent-instruction 或 --agent-instruction-file。
  2. azd ai agent optimize留在 Agent 的服務資料夾中、位於.agent_configs/baseline/底下的基準指示。
  3. 指示會和 Agent 一起公佈。
  4. 互動式提示。 選擇 輸入指令 或 從檔案載入。 在檔案提示時,請輸入非空文字檔案的路徑,且不需加上殼層引號。 你可以修正無法讀取或空白的檔案,而不用重新開始其他選擇,或是在提交工作前取消。

使用 --no-prompt 或 JSON 輸出時,缺少指令會產生提到 --agent-instruction 和 --agent-instruction-file 而非提示的錯誤。 確認是指示來源,而非其內容。

單行指令會產生一般資料列。 對於未公開指令的託管代理,例如自帶程式碼代理,請傳遞 --agent-instruction 或 --agent-instruction-file,並附上代理的目的、處理的請求類型、政策以及你想測試的邊緣案例。

產生的產物名稱使用代理程式宣告的部署名稱,而非其本地服務金鑰或指令來源。 原始目標選擇器仍決定產生請求。 產生的資料集名稱有 50 個字元的限制。 長預設值會進行確定性縮短,而過長的明確--dataset-name則會失敗而非遭截斷。 此限制不會重新命名現有成品,也不適用於評估工具名稱。

編輯評分標準文件

產生、已完成工作收集及評分規準下載會產生可編輯的 JSON 文件,包含type: "rubric"、dimensions,以及可選的pass_threshold。 每個維度包含 id、 description、 weight和 always_applicable。 文件保留了其他由作者撰寫的定義與維度欄位,包括數值精確度。 權重為 1 到 10 的整數。 提供的門檻介於0到1之間。

服務封裝、產生的連線和目錄中繼資料不是評分規準欄位。 發佈編輯過的評分規準可以在你沒有明確替換其中繼資料時保留現有的目錄元資料。 提示式評估工具文件仍是分開的。 用 azd ai eval evaluator show <name> --version <version> -o json 來檢查完整服務的回應。

在依據評分規準前,請先讀取產生的內容。 由簡短指令撰寫的評分規準幾乎能通過每個列,這使其成為弱門檻。 緊縮維度和pass_threshold,然後再次執行create。

檢閱 azure.eval.yaml

檢查 init 寫入的檔案。 以追蹤資料為來源的評估如下:

evals:
    - name: support-trace-eval
      description: Basic quality evaluation for support-agent
      source:
        type: traces
        lookbackHours: 168
        maxTraces: 20
        agentName: support-agent
      evaluationLevel: turn
      evaluators:
        - evaluator: builtin.task_completion
          initializationParameters:
            model: judge-deployment

翻轉資料集評估會命名資料集,而非追蹤來源,並記錄其針對的 Agent。 先前turn-quality的指令會傳遞一個已註冊的資料集名稱,因此它會寫入這個檔案並在datasets型錄中宣告golden-turns,而不需本機檔案:

datasets:
    - name: golden-turns
evals:
    - name: turn-quality
      description: Basic quality evaluation for support-agent
      dataset: golden-turns
      evaluationLevel: turn
      evaluators:
        - evaluator: builtin.intent_resolution
          initializationParameters:
            model: judge-deployment
        - evaluator: builtin.task_adherence
          initializationParameters:
            model: judge-deployment
      target:
        type: agent
        name: support-agent

本地資料集的列命名為 file:,自訂評估器則將其規準命名為 source:。 這兩條路徑都是相對於設定檔的。 如果你傳遞像 --dataset tests/support-golden.jsonl 這樣的本機路徑,當組態處於 file: ../tests/support-golden.jsonl 時,init 會宣告名為 evals/ 且具有 support-golden 的資料集。 註冊資料集可以宣告其 name 和選用的 version,無需本地檔案。

產生 .jsonl 的 JSON 和 evaluator JSON 都是普通檔案:編輯後再執行 create 以註冊新版本。

提交這個檔案。 這是評估中可重現的部分。

檢閱評估器輸入對應

對於標準資料集與痕跡,預設映射恰好包含以下評估者輸入:

評估層級 預設對應(可用 dataMapping 覆寫)
轉動 query: "{{item.query}}"、、response: "{{item.response}}"tool_calls: "{{item.tool_calls}}"、tool_definitions: "{{item.tool_definitions}}"。
談話 messages: "{{item.messages}}",tool_definitions: "{{item.tool_definitions}}"。

產生與檢索的輸出會保留各自獨立的來源資訊。 模型輸出使用 sample.output_text。 代理人的輸出與儲存的回應會依據評估者的回應類型使用 sample.output_items 或 sample.output_text。 由代理產生的工具會使用相應的 sample 欄位。 用來過濾痕跡的代理名稱不會喚起該代理,也不會將痕跡欄位轉為產生的輸出。

明確映射會覆蓋相應的預設值。 使用 messages 或回合 query/response 格式其中一種,不要同時使用兩者。 即使資料集包含這些欄位,擴充也不會推斷 context 或 ground_truth。 提供真實的支持資料,並明確映射額外的評估者輸入。

在發布相依性之前,擴充功能會檢查每個適用資料集列中是否存在主要映射輸入。 可選工具欄位並非強制,產生的輸出也不會被誤認為資料集輸入欄位。 僅有正確的對應並不保證成功的依據性或其他託管的評估工具結果。

刻意移轉現有評估

儲存的映射是不可變的。 升級擴充功能並不會取代現有評估中的映射。 對於有計畫的移轉:

  1. 記錄舊的評估 ID,並用 azd ai eval show <eval-id> -o json 檢查該 ID。
  2. 從你打算遷移的宣告中移除明確的 id:,或建立一個獨立的未釘選宣告。 顯式 ID 會一直選擇舊的定義。
  3. 設定預期的name條目,並更改評估器參考的準則dataMapping。 僅僅更改評估組名稱是不夠的。
  4. 執行azd ai eval create <eval-name>,然後在開始執行前檢查產生的識別碼和對應。

先前的評估及其執行仍可透過已記錄的識別碼取得。 當儲存的輸入合約不同時,改變來源模式會產生新的定義。 只更改相容的執行過濾器、時間視窗或回應 ID 並不會丟棄過去紀錄。

建立評估並執行

請使用create來註冊所選的評估及其宣告的資料集和評估工具。

其餘區段的指令使用 support-trace-eval。 將其替換為您所選初始化範例中的名稱:turn-quality、static-quality 或 simulation-quality,用於資料集評估。

azd ai eval create

如果配置宣告只有一個評估,你可以省略其名稱。 否則,請使用azd ai eval create <eval-name>選取一個。

然後執行它:

azd ai eval run start

run start 依預設會等待該次執行完成,並列印每個評估工具的表格 (含通過率與平均分數),以及入口網站中該次執行的連結。 使用--no-wait來提交並返回。

如果設定中宣告了多個 eval,請指明你指的是哪一個:

azd ai eval run start --eval support-trace-eval

選取資料集版本並控制執行大小

註冊資料集執行會保留所選資料集版本的服務核發的身分識別。 版本選擇會使用宣告的目錄檔 version,接著是已記錄的發佈版本,最後是最新的服務版本。 發佈後保留本機file條目並不代表執行時會改為使用本機資料列。

註冊資料集不支援大於 0 的 --max-samples 值或評估層級的 maxSamples 設定。 即使上限超過資料集的列數,指令也會在提交執行前拒絕它。 這個指令不會默默忽略上限、用內嵌資料列取代已註冊的資料集,或發布臨時子集。

移除設定的上限以評估整個選定版本。 對於在 azure.eval.yaml中宣告的回合或靜態資料集評估,你可以明確覆蓋設定的上限:

azd ai eval run start --eval turn-quality --max-samples 0

省略--max-samples仍會使用任何已設定的maxSamples。 明確的零會停用對該已宣告評估的上限;這不代表零列。 負值是無效的。

模擬時,完全從評估配置中移除 maxSamples 。 --max-samples 0無法修復宣告正值上限的無效模擬組態。

對於較小的已註冊執行作業,可以刻意發佈較小的資料集,並在 datasets 型錄中宣告。 選擇其型錄名稱,而非檔案路徑或 URI:

azd ai eval run start --eval turn-quality --dataset small-golden

此範例假設 small-golden 已註冊、宣告,且與評估的欄位結構相容。 在執行前先移除所有正值上限。

內嵌資料列與正值上限僅適用於本機未註冊的資料集,前提是命令驗證其不存在於服務中。 查詢失敗或查詢結果無法判定時會停止執行,而非退回使用本機資料列。 在評估資料集前,先將本地編輯發布到已註冊的資料集。

對於追蹤來源的評估,在配置中使用 source.maxTraces 或 init --max-traces,而非 run start --max-samples。 僅用評估 ID 重執行會重用其先前來源,並拒絕明確的 --max-samples,即使是 0 也不接受;使用宣告的評估名稱來選擇其已設定的資料集。

檢查結果

摘要告訴你品質是否有所變動。 各樣本的資料列會告訴你原因:

azd ai eval run output list --eval support-trace-eval
azd ai eval run output list --eval support-trace-eval --failed-only

如要查看一段時間內的執行記錄,以及服務為單一評估保留哪些內容:

azd ai eval list
azd ai eval run list --eval support-trace-eval
azd ai eval show support-trace-eval

show 回傳專案中的評估識別資訊(ID、名稱、建立時間及建立者),並在可用時回傳評估器與資料來源類型。 評估做什麼,寫在您的 evals/azure.eval.yaml 中。

run list 針對每次執行只提供一項通過率。 每個評估工具的細目位於 -o json 輸出的 per_testing_criteria_results 底下,因為一旦不同執行評分的評估工具不盡相同,每個評估工具各佔一欄的呈現方式就會變得難以閱讀。

將結果移至其他地方:

azd ai eval run output list --eval support-trace-eval --output-file rows.json
azd ai eval run output export --eval support-trace-eval --output-file run.json

兩者不同,而差異很重要: run output list --output-file 將列寫成 JSON,並套用任何 --failed-only 或 --status 過濾器,且每列寫入,除非你設定 --limit。 run output export 將整個執行寫成一個 JSON 文件:該執行如服務所描述的那樣,以及其下方的每個評估列,並標示每位評估者的分數、判決與理由。 從該檔案衍生出任何其他形狀,例如jq -c '.items[]' run.json > rows.jsonl。

為建置設定閘門

傳入 --fail-on 以將執行作業變成檢查。 當執行結果未達閾值時,它會以非零狀態結束,這就是管線讓已導致品質劣化的變更判定為失敗的方式:

azd ai eval run start --eval support-trace-eval --fail-on pass-rate=0.8
azd ai eval run start --eval support-trace-eval --fail-on any-failure

若沒有 --fail-on,即使執行程序已完成且有失敗的樣本,仍會以退出碼 0 結束。 失敗的樣本是正常運作中評估的預期輸出,而非工具錯誤,因此閘門管制功能為選擇性啟用。

pass-rate 取一個介於0到1之間的數字。 並非有效閾值的值,會在提交執行之前遭到拒絕,因此輸入錯誤的閘門設定不會造成任何損失。

--fail-on 需要一次已完成的執行。 在 run show上,與 --wait配對。

將評估與專案其他部分一同部署

init命令會新增一個評估服務到azure.yaml,因此評估是專案的一部分:

azd up

azd up 指令會先佈建專案,然後部署評估服務來核對已宣告的資料集、評估者與評估結果。 azd ai eval create命令會獨立執行評估資源對帳;它不會佈建專案的基礎結構。 一個沒有基礎建設的專案,例如你使用 azd init --minimal 建立的工作區,就沒有任何可供 azd up 佈建的內容。 在該專案中,執行 azd ai eval create 以註冊評估。

更換代理人並重新評估

變更 Agent 後,部署它:

azd deploy

對於基於追蹤記錄的評估,呼叫更新後的代理程式使其產生新的追蹤記錄;run start 只讀取現有的追蹤記錄。 然後再執行選定的評估:

azd ai eval run start --eval support-trace-eval

當 azd ai eval run start 呼叫代理時,它會依名稱識別該代理,而不會固定版本。 要比較版本,請在部署變更前執行評估,並命名每個執行,這樣你就能區分:

azd ai eval run start --eval turn-quality --name baseline
azd deploy
azd ai eval run start --eval turn-quality --name updated

若要用代理優化器改進託管代理,並透過獨立評估驗證結果,請參見 快速入門:優化託管代理。

對於受控比較,請使用資料集來源的評估,固定資料集與自訂評估器版本,並保持評分設定與門檻不變。 追蹤來源的執行可讀取不同的互動,因此它們無法保證得到完全相同的案例集。

更改 evals/azure.eval.yaml 或產生的產出物後,再跑 create 一次,使其與專案一致。 早期執行結果仍可取得,但重複使用評估不會將未來的資料集或評估器版本釘選。

最佳做法

  • 如果代理程式已在執行並傳送追蹤資料,請從 --source traces 開始。 它會評量已發生的事,且不需要撰寫任何內容。
  • 當你想要一組可跨版本比較的固定案例時,請移至 --source dataset。
  • 在信任分數之前,先閱讀產生的資料集和評分標準。 檢查生成上下文是否代表你需要測試的行為。
  • 使用多位評估者。 只有一個標準會移動數字,卻不會告訴你原因。
  • 認可 evals/azure.eval.yaml 及產生的成品,讓評估可供檢閱。
  • 在 CI 中使用 --fail-on 設定閘門,並將閾值設定在確實會被真正品質劣化觸發的水準。
  • 部署變更代理前先執行具名基準,因為 run start 不會固定代理版本。

Limitations

  • 擴充功能目前還在預覽階段,指令面板可以更換。
  • generate 會提交計費工作。 azd provision 不會建立資料集或評估器。
  • 以追蹤為來源的評估,只能讀取 Agent 已發出的追蹤。
  • azd 會收斂延伸模組的結束代碼,因此無論是閘門違規還是操作失敗,都會以非零結束代碼呈現。 閱讀傳送門訊息來分辨它們。
  • 使用合成測試資料,且不要分享包含憑證、權杖或憑證 URL 的日誌。