评估你的 AI 智能体

可易团队2026-11-08阅读约 10 分钟

在 Microsoft Foundry 中对智能体运行评估：生成评分细则，叠加内容安全与连贯性评估器，上传 JSONL 测试集，并把通过率设为发布前的质量门禁。

评估（evaluation）对于确保你的智能体（agent）在部署前达到质量与安全标准至关重要。在开发期间运行评估，可以为智能体的表现建立基线，并在向用户发布之前设定验收阈值，例如 85% 的任务遵循（task adherence）通过率。

在本文中，你将学习如何对 Foundry 智能体或托管智能体（hosted agent）运行以智能体为目标的评估。你使用根据智能体上下文生成的评分细则评估器（rubric evaluator）作为主要度量，并叠加用于内容安全（content safety）和其他风险的内置评估器。具体来说，你将：

为评估设置 SDK 客户端。
生成一份针对你的智能体定制的评分细则评估器，并将其与内置评估器搭配使用。
创建测试数据集并运行评估。
解读结果并将其纳入你的工作流。

提示

关于生成式 AI 模型和应用的通用评估，包括自定义评估器、不同数据源以及其他 SDK 选项，请参阅《从 SDK 运行评估》（Run evaluations from the SDK）。

先决条件

Python 3.8 或更高版本。
一个带有智能体或托管智能体的 Foundry 项目。
一个 Azure OpenAI 部署，其中包含支持聊天补全（chat completion）的 GPT 模型（例如 gpt-4o 或 gpt-4o-mini）。
对 Foundry 项目拥有 Foundry User 角色。重要 Foundry 的 RBAC 角色最近已更名。Foundry User、Foundry Owner、Foundry Account Owner 和 Foundry Project Manager 先前分别名为 Azure AI User、Azure AI Owner、Azure AI Account Owner 和 Azure AI Project Manager。在更名推广期间，你仍可能在某些地方看到先前的名称。角色 ID 和核心权限不因更名而改变。
有关全部评估角色要求，请参阅《为评估工作流设置权限》（Set up permissions for evaluation workflows）。

注意

部分评估功能——包括评分细则生成、合成数据集与基于追踪（trace）的数据集创建，以及风险与安全评估器——存在区域限制。完整列表请参阅《评估的速率限制、区域支持与企业功能》（Rate limits, region support, and enterprise features for evaluation）。

设置客户端

安装 Foundry SDK 并设置身份验证：

Python

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()

JavaScript/TypeScript

npm install @azure/ai-projects @azure/identity dotenv

创建项目客户端。以下代码示例假定你在此上下文中运行它们：

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import "dotenv/config";

const endpoint = process.env["AZURE_AI_PROJECT_ENDPOINT"] || "";
const modelDeployment = process.env["AZURE_AI_MODEL_DEPLOYMENT_NAME"] || "";

const projectClient = new AIProjectClient(
  endpoint,
  new DefaultAzureCredential(),
);
const client = projectClient.getOpenAIClient();

参考：AIProjectClient 类

选择评估器

评估器为你的智能体响应打分。智能体评估推荐的主要度量是评分细则评估器——一组带权重的评分维度，由一个 LLM 评判器应用到每一条响应上，这样你就可以表达真正重要的精确标准（例如策略执行、工具使用准确性或沟通清晰度），并在规模上保持一致打分。详情请参阅《评分细则评估器》（Rubric evaluators）。

将你的评分细则与其他评估器搭配，以完整覆盖评估范围：

智能体评估器（Agent evaluators）——评估智能体处理任务、工具和用户意图的有效程度。
质量评估器（Quality evaluators）——度量生成响应的整体质量。
文本相似度评估器（Text similarity evaluators）——使用 NLP 指标将生成文本与参考答案进行比较。
安全评估器（Safety evaluators）——识别生成输出中潜在的内容与安全风险。
自定义评估器（Custom evaluators）——当评分细则和内置评估器不能覆盖你的标准时，构建你自己的评估器。

你可以手工编写评分细则，也可以根据智能体的上下文——其名称、指令和工具——生成一份。以下示例生成一份评分细则并打印其维度，以便你在使用前进行审阅。

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"}

提示

如果你没有手工整理的数据集，可以引导生成一份。在发布前或流量较低时，使用《生成合成评估数据集》（Generate a synthetic evaluation dataset）；要从真实生产流量构建数据集，则使用《将智能体追踪转换为评估数据集》（Convert agent traces into evaluation datasets）。

将此文件作为数据集上传到你的项目：

Python

dataset = project_client.datasets.upload_file(
    name="agent-test-queries",
    version="1",
    file_path="./test-queries.jsonl",
)

JavaScript/TypeScript

const dataset = await projectClient.datasets.uploadFile(
  "agent-test-queries",
  "1",
  "./test-queries.jsonl",
);

参考：datasets.uploadFile

运行评估

运行评估时，服务会把每条测试查询发送给你的智能体，捕获响应，并应用你选定的评估器为结果打分。

首先，配置测试标准。按名称引用生成的评分细则评估器。每一项使用 data_mapping 指向测试数据和智能体响应中的字段，并使用 initialization_parameters 传递评估器设置：

{{item.X}} 引用测试数据中的字段，例如 query。
{{sample.output_items}} 引用完整的智能体响应，包括工具调用。
{{sample.output_text}} 只引用响应消息文本。
initialization_parameters={"deployment_name": <model>} 提供评判模型。LLM 评判评估器通常需要它。各评估器参数请参阅《内置评估器》（built-in evaluators）。

Python

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>" 的条目。例如，加入 Violence（内容安全）和 Coherence（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}}",
        },
    )
)

JavaScript/TypeScript SDK 示例尚未演示评分细则评估器的生成，因此本示例直接从内置评估器开始：Violence（内容安全）和 Coherence（LLM 评判质量）。使用相同的 data_mapping 模式来添加更多内置评估器：

const testingCriteria = [
  {
    type: "azure_ai_evaluator",
    name: "Violence",
    evaluator_name: "builtin.violence",
    data_mapping: {
      query: "{{item.query}}",
      response: "{{sample.output_text}}",
    },
  },
  {
    type: "azure_ai_evaluator",
    name: "Coherence",
    evaluator_name: "builtin.coherence",
    initialization_parameters: { deployment_name: modelDeployment },
    data_mapping: {
      query: "{{item.query}}",
      response: "{{sample.output_text}}",
    },
  },
];

接下来，创建评估。一次评估定义测试数据模式和测试标准。它作为多次运行的容器。同一次评估下的所有运行都遵循相同模式，并产生同一组指标。这种一致性对于跨运行比较结果很重要。

Python

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,
)

JavaScript/TypeScript

const dataSourceConfig = {
  type: "custom",
  item_schema: {
    type: "object",
    properties: { query: { type: "string" } },
    required: ["query"],
  },
  include_sample_schema: true,
};

const evaluation = await client.evals.create({
  name: "Agent Quality Evaluation",
  data_source_config: dataSourceConfig,
  testing_criteria: testingCriteria,
});

最后，创建一次运行，把测试查询发送给智能体并应用评估器：

Python

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}")

JavaScript/TypeScript

const evalRun = await client.evals.runs.create(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: agentName,
      version: "1", // Optional; omit to use latest version
    },
  },
});

console.log(`Evaluation run started: ${evalRun.id}`);

提示

本示例同时适用于使用 responses 协议的提示词智能体和托管智能体。对于使用 invocations 协议的托管智能体，input_messages 的格式不同——提供一个自由形式的 JSON 对象，而不是结构化模板。详情和代码示例请参阅云评估指南中的《托管智能体调用协议》（Hosted agent invocations protocol）。

提示

要使用来自 Application Insights 的追踪评估已经发生的智能体交互，请参阅云评估指南中的《追踪评估》（Trace evaluation）。

解读结果

评估通常在几分钟内完成，具体取决于查询数量。轮询直至完成，并检索报告 URL，以便在 Microsoft Foundry 门户的 Evaluations 选项卡下查看结果：

Python

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}")

JavaScript/TypeScript

// Wait for completion
let run = evalRun;
while (!["completed", "failed"].includes(run.status)) {
  run = await client.evals.runs.retrieve(run.id, {
    eval_id: evaluation.id,
  });
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

console.log(`Status: ${run.status}`);
console.log(`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 }
    ]
}

行级输出

每次评估运行都会为测试数据集中的每一行返回输出项，从而让你详细看到智能体的表现。输出项包括原始查询、智能体响应、带有分数和理由的各个评估器结果，以及令牌用量：

{
    "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 评判器产生的逐维度分解。每个维度的分数采用 1–5 分制。顶层分数是适用维度分数的加权平均，并归一化到 0–1 范围。完整输出模式请参阅《评分细则评估器》（Rubric evaluators）。

纳入你的工作流

持续集成/持续交付（CI/CD）管道：把评估用作部署管道中的质量门禁。详细集成请参阅《使用 GitHub Actions 运行评估》（Run evaluations with GitHub Actions）。
生产监控：使用持续评估在生产中监控你的智能体。设置说明请参阅《设置持续评估》（Set up continuous evaluation）。

优化并比较版本

使用评估来迭代并改进你的智能体：

运行评估以识别薄弱环节。使用聚类分析找出模式和错误。
根据发现调整智能体指令或工具。
重新评估并比较各次运行，以度量改进。
重复，直到达到质量阈值。

PRIMARY_SOURCE: https://learn.microsoft.com/en-us/azure/foundry/observability/how-to/evaluate-agent

#智能体评估
#质量门禁
#内容安全
#Foundry

评估你的 AI 智能体

先决条件

设置客户端

Python

JavaScript/TypeScript

选择评估器

创建测试数据集

Python

JavaScript/TypeScript

运行评估

Python

Python

JavaScript/TypeScript

Python

JavaScript/TypeScript

解读结果

Python

JavaScript/TypeScript

汇总结果

行级输出

纳入你的工作流

优化并比较版本

继续阅读

将智能体追踪转换为评估数据集

用 Amazon Bedrock 上的开放权重模型运行 AI 编码智能体

共享基础设施、隔离租户：用 Amazon Bedrock AgentCore 做池化多租户