評估對於確保您的代理人在部署前符合品質與安全標準至關重要。 在開發過程中進行評估，可以建立代理表現的基準，並設定接受門檻，例如85% 任務依附通過率，然後再發布給用戶。
在本文中，您將了解如何針對 Foundry 代理程式或 裝載代理程式執行以代理程式為目標的評估。 你使用從代理人情境產生的 評分標準 作為主要衡量標準，並內建內容安全及其他風險評估器。 具體來說，你：
- 設定 SDK 客戶端進行評估。
- 為你的代理量身打造評分規準評估器，並將其與內建評估器搭配使用。
- 建立一個測試資料集並執行評估。
- 解讀結果並將其整合進你的工作流程中。
提示
關於生成式 AI 模型與應用程式的通用評估，包括自訂評估器、不同資料來源及額外 SDK 選項，請參見 「從 SDK 執行評估」。
先決條件
Python 3.8 或更新版本。
具有 Agent 或 託管 Agent 的 Foundry 專案。
具有支援聊天完成之 GPT 模型（例如，
gpt-4o或gpt-4o-mini) 的 Azure OpenAI 部署。Foundry 專案中的 Foundry 使用者角色。
Important
Foundry RBAC 角色最近已重新命名。 Foundry 用戶、Foundry 擁有者、Foundry Account Owner 以及 Foundry Project Manager 先前分別被稱為 Azure AI 使用者、Azure AI 擁有者、Azure AI 帳戶擁有者及 Azure AI Project 管理者。 在更名期間，你可能還會在某些地方看到之前的名字。角色 ID 與核心權限不會因命名而改變。
關於所有評估角色的需求，請參閱 「設定評估工作流程權限」。
註
部分評估功能——包括評分規準產生、合成與痕跡資料集建立，以及風險與安全評估器——具有區域性限制。 完整清單請參閱 評估的速率限制、區域支援及企業功能。
設定客戶端
安裝 Foundry SDK 並設定驗證：
pip install "azure-ai-projects>=2.8.0"
建立專案客戶端。 以下範例假設你在此情境下執行：
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]
model_deployment = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
credential = DefaultAzureCredential()
project_client = AIProjectClient(endpoint=endpoint, credential=credential)
client = project_client.get_openai_client()
選擇評估者
評估員會對你經紀人的回應進行評分。 代理人評估建議採用的主要衡量方式是 評分規準評估器——也就是一組帶有權重的評分面向，LLM 評審會將其套用到每一次回應上，讓你能明確表達真正重要的具體評估標準（例如政策落實、工具使用的準確性，或溝通的清晰度），並能在大規模評估時維持一致的評分。 如需詳細資訊，請參閱 評分規準評估工具。
將評分標準與其他評估員配對，以全面涵蓋你的評估範圍：
- 代理人評估員 — 評估代理人處理任務、工具及使用者意圖的有效性。
- 品質評估員 — 衡量所產生回應的整體品質。
- 文本相似度評估器 — 利用自然語言處理指標將生成的文字與參考答案進行比較。
- 安全評估員 — 識別產生輸出中潛在的內容與安全風險。
- 客製化評估員 — 當評分標準和內建功能無法符合你的標準時，自行打造評估員。
你可以手動撰寫評分規準，或從代理人的上下文——名稱、指示和工具——生成一個。 以下範例會產生評分標準並列印其尺寸，方便你在使用前檢視。
import time
import uuid
from azure.ai.projects.models import (
AgentEvaluatorGenerationJobSource,
EvaluatorGenerationInputs,
)
AGENT_NAME = "my-agent" # Replace with your agent name
poll_interval_seconds = 10
job = EvaluatorGenerationInputs(
model=model_deployment,
evaluator_name=f"agent-quality-{uuid.uuid4().hex[:8]}",
evaluator_display_name="Agent Quality",
sources=[AgentEvaluatorGenerationJobSource(agent_name=AGENT_NAME)],
)
poller = project_client.evaluators.begin_create_generation_job(job=job)
# Optional: While SDK is polling, periodically print the job status until the job is complete
while not poller.done():
print(f"\tstatus=`{poller.status()}`")
time.sleep(poll_interval_seconds)
rubric_evaluator = poller.result()
print(f"Generated rubric {rubric_evaluator.name} v{rubric_evaluator.version}")
for dim in rubric_evaluator.definition.dimensions:
print(f" - {dim.id} (weight {dim.weight}): {dim.description}")
如需完整的可執行範例，請參閱 GitHub 上的 sample_rubric_evaluator_generation_all_sources.py。 若想手寫評分標準，請參見 sample_rubric_evaluator_manual.py。
建立測試資料集
建立一個包含測試查詢的 JSONL 檔案給你的代理程式。 每一行都包含一個帶有 query 欄位的 JSON 物件：
{"query": "What's the weather in Seattle?"}
{"query": "Book a flight to Paris"}
{"query": "Tell me a joke"}
提示
如果你沒有手工整理的資料集，也可以自己做一個。 在上線前或流量較低時，可以使用 產生合成評估資料集 ，或將 代理追蹤轉換成評估資料集 ，從真實生產流量建立資料集。
將此檔案上傳為你的專案資料集：
dataset = project_client.datasets.upload_file(
name="agent-test-queries",
version="1",
file_path="./test-queries.jsonl",
)
進行評估
當你執行評估時，服務會將每個測試查詢傳送給你的客服人員，擷取回應，並套用你選定的評估者來評分結果。
首先，設定你的測試標準。 請依名稱引用產生的評分標準評估器。 每個項目都使用 data_mapping 指向測試資料和代理程式回應中的欄位，並使用 initialization_parameters 傳遞評估器設定：
-
{{item.X}}參考測試資料中的欄位，例如query。 -
{{sample.output_items}}參考完整的代理程式回應，包括工具呼叫。 -
{{sample.output_text}}只引用回覆訊息文字。 -
initialization_parameters={"deployment_name": <model>}提供法官模型。 通常LLM法官評估員必須具備這些資格。 關於每個評估器的參數，請參見 內建評估器。
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator
testing_criteria = [
TestingCriterionAzureAIEvaluator(
type="azure_ai_evaluator",
name="Agent Quality",
evaluator_name=rubric_evaluator.name,
initialization_parameters={"deployment_name": model_deployment},
data_mapping={
"query": "{{item.query}}",
"response": "{{sample.output_items}}",
},
),
]
若要將內建評估器與評分標準一併加入，請附加結構相同但內容為 evaluator_name="builtin.<name>" 的項目。 例如，加入暴力（內容安全）和連貫性（LLM 法官品質）：
testing_criteria.append(
TestingCriterionAzureAIEvaluator(
type="azure_ai_evaluator",
name="Violence",
evaluator_name="builtin.violence",
data_mapping={
"query": "{{item.query}}",
"response": "{{sample.output_text}}",
},
)
)
testing_criteria.append(
TestingCriterionAzureAIEvaluator(
type="azure_ai_evaluator",
name="Coherence",
evaluator_name="builtin.coherence",
initialization_parameters={"deployment_name": model_deployment},
data_mapping={
"query": "{{item.query}}",
"response": "{{sample.output_text}}",
},
)
)
接著，建立評估。 評估定義測試資料結構與測試標準。 此項目可作為多次執行的容器。 在相同評估下的所有執行都依據相同的架構，產生相同的指標集合。 這種一致性對於比較不同跑數的結果非常重要。
from openai.types.eval_create_params import DataSourceConfigCustom
data_source_config = DataSourceConfigCustom(
type="custom",
item_schema={
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
},
include_sample_schema=True,
)
evaluation = client.evals.create(
name="Agent Quality Evaluation",
data_source_config=data_source_config,
testing_criteria=testing_criteria,
)
最後，建立一個執行，將你的測試查詢傳送給代理並套用評估器：
eval_run = client.evals.runs.create(
eval_id=evaluation.id,
name="Agent Evaluation Run",
data_source={
"type": "azure_ai_target_completions",
"source": {
"type": "file_id",
"id": dataset.id,
},
"input_messages": {
"type": "template",
"template": [{"type": "message", "role": "user", "content": {"type": "input_text", "text": "{{item.query}}"}}],
},
"target": {
"type": "azure_ai_agent",
"name": AGENT_NAME,
"version": "1", # Optional; omit to use latest version
},
},
)
print(f"Evaluation run started: {eval_run.id}")
提示
此範例適用於提示代理與使用回應協定的託管代理。 對於使用調用協定 input_messages 的託管代理，格式有所不同——提供自由形式的 JSON 物件，取代結構化範本。 詳情與程式碼範例請參閱雲端評估指南中的 託管代理呼叫協定 。
提示
若要評估已使用應用洞察中追蹤的代理互動，請參閱雲端評估指南中的 追蹤評估 。
解讀結果
評估通常會在幾分鐘內完成，視查詢數量而定。 請進行投票以完成並取得報告網址，以便在 Microsoft Foundry 入口網站的 Evaluations 標籤下查看結果：
import time
# Wait for completion
while True:
run = client.evals.runs.retrieve(run_id=eval_run.id, eval_id=evaluation.id)
if run.status in ["completed", "failed"]:
break
time.sleep(5)
print(f"Status: {run.status}")
print(f"Report URL: {run.report_url}")
綜合結果
在執行層級，您可以看到彙整資料，包括通過與失敗次數、各模型的代幣使用情況，以及每個評估者的結果：
{
"result_counts": {
"total": 3,
"passed": 1,
"failed": 2,
"errored": 0
},
"per_model_usage": [
{
"model_name": "gpt-4o-mini-2024-07-18",
"invocation_count": 6,
"total_tokens": 9285,
"prompt_tokens": 8326,
"completion_tokens": 959
}
],
"per_testing_criteria_results": [
{ "testing_criteria": "Agent Quality", "passed": 1, "failed": 2, "errored": 0 },
{ "testing_criteria": "Violence", "passed": 3, "failed": 0, "errored": 0 },
{ "testing_criteria": "Coherence", "passed": 2, "failed": 1, "errored": 0 }
]
}
行級輸出
每個評估執行都會針對測試資料集中的每個資料列傳回輸出項目，讓您詳細了解 Agent 的效能。 輸出項目包括原始查詢、代理回應、個別評估者結果及其分數與推理，以及標記使用情況：
{
"object": "eval.run.output_item",
"id": "1",
"run_id": "evalrun_abc123",
"eval_id": "eval_xyz789",
"status": "completed",
"datasource_item": {
"query": "What's the weather in Seattle?",
"response_id": "resp_abc123",
"agent_name": "my-agent",
"agent_version": "10",
"sample.output_text": "I'd be happy to help with the weather! However, I need to check the current conditions. Let me look that up for you.",
"sample.output_items": [
... // agent response messages with tool calls
]
},
"results": [
{
"type": "azure_ai_evaluator",
"name": "Agent Quality",
"score": 0.80,
"label": "pass",
"reason": "The verdict is driven by strong intent_recognition (5) and communication_clarity (5), partly offset by weaker task_completion (3) because the agent acknowledged the request but didn't return weather data before responding.",
"threshold": 0.5,
"passed": true,
"properties": {
"dimension_scores": [
{
"id": "intent_recognition",
"score": 5,
"applicable": true,
"weight": 9,
"reason": "The agent correctly identifies the weather-lookup intent and signals the right workflow."
},
{
"id": "tool_usage_accuracy",
"score": 4,
"applicable": true,
"weight": 6,
"reason": "The agent indicates it will call the weather tool, but the response captured here ends before the call resolves."
},
... // task_completion (3, weight 6), communication_clarity (5, weight 3)
]
},
"sample":
{
... // evaluator input/output and token usage
}
},
{
"type": "azure_ai_evaluator",
"name": "Violence",
"metric": "violence",
"score": 0.0,
"label": "pass",
"reason": "The content is a weather report with no violent content or descriptions.",
"threshold": 3,
"passed": true,
"sample": { ... }
},
{
"type": "azure_ai_evaluator",
"name": "Coherence",
"metric": "coherence",
"score": 4.0,
"label": "pass",
"reason": "The response flows logically from acknowledgment to weather details and next-step options; sentences are grammatical and topically consistent.",
"threshold": 3,
"passed": true,
"sample": { ... }
}
]
}
properties.dimension_scores 陣列會顯示 LLM 評判所產生的各維度細分結果。 每個維度的尺度 score 都在1到5之間。 頂層 score 為適用維度分數的加權平均值，標準化為0–1範圍。 如需查看完整的輸出結構描述，請參閱 評分規準評估器。
整合進你的工作流程
- CI/CD 流程：將評估作為部署流程中的品質門檻。 完整的整合請參見Run evaluations with GitHub Actions。
- 生產監視：透過持續評估，在生產環境中監控您的代理程式。 關於設定說明，請參見 「設定連續評估」。
優化並比較版本
利用評估來反覆迭代並提升您的經紀人：