通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 Microsoft Foundry SDK 在云中运行评估

重要

本文中标记了“（预览版）”的项目目前为公共预览版。 此预览版未提供服务级别协议，不建议将其用于生产工作负载。 某些功能可能不受支持或者受限。 有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

本文介绍如何在云中运行评估（预览版），以便在测试数据集上进行预部署测试。

对大多数方案使用云评估，尤其是在大规模测试时，将评估集成到持续集成和持续交付（CI/CD）管道中，或执行预部署测试。 在云中运行评估无需管理本地计算基础结构并支持大规模自动化测试工作流。 还可以计划定期运行的 评估 ，或设置 持续评估 以自动评估生产中的采样代理响应。

云评估结果存储在 Foundry 项目中。 可以在门户中查看结果、通过 SDK 检索结果，或将其路由到 Application Insights（如果已连接）。 云评估支持所有Microsoft策展的 内置评估器 和你自己的 自定义评估器。 评估程序员在具有相同项目范围的基于角色的访问控制的评估器目录中进行管理。

小窍门

有关完整的可运行示例，请参阅 GitHub 上的 Python SDK 评估示例 。

使用 Foundry SDK 时，它会在 Foundry 项目中记录评估结果，以提高可观测性。 此功能支持微软精选的所有内置评估器。 和你自己的 自定义评估器。 评估器可以位于 评估器库 中，并具有相同的项目范围、基于角色的访问控制。

云评估的工作原理

若要运行云评估，请使用数据架构和测试条件（评估标准）创建评估定义，然后开始评估执行。 这次运行针对您的数据执行每个评估器，并返回可以轮询完成情况的评分结果。

云评估支持以下方案：

Scenario 何时使用 数据源类型 目标
数据集评估 评估 JSONL 文件中的预计算响应。 jsonl —
模型目标评估 在运行时提供查询并从模型生成响应以供评估。 azure_ai_target_completions azure_ai_model
代理目标评估 在运行时提供查询并从 Foundry 代理生成响应以供评估。 azure_ai_target_completions azure_ai_agent
代理响应评估 按响应 ID 检索和评估 Foundry 代理响应。 azure_ai_responses —
红队评估 针对模型或代理运行自动对抗测试。 azure_ai_red_team azure_ai_model 或 azure_ai_agent

大多数方案都需要输入数据。 可以通过两种方式提供数据：

源类型 Description
file_id 按 ID 引用上传的数据集。
file_content 在请求中以内联形式提供数据。

每个评估都需要一个 data_source_config 来指示服务应该在数据中预期哪些字段。

  • custom — 使用字段名称和类型定义一个 item_schema 。 将include_sample_schema设置为true，以便在使用目标时评估者可以引用生成的响应。
  • azure_ai_source — 从服务推断架构。 将"scenario"设置为"responses"以进行代理响应评估或"red_team"红队演练。

每个情景都需要定义您的测试标准的评估者。 有关选择评估器的指导，请参阅 内置评估器。

先决条件

  • Foundry 项目。
  • 具有支持聊天完成的 GPT 模型的 Azure OpenAI 部署（例如，gpt-5-mini）。
  • Foundry 项目中的 Azure AI 用户 角色。
  • （可选）可以使用 自己的存储帐户 来运行评估。

注释

某些评估功能具有区域限制。 有关详细信息 ，请参阅支持的区域 。

开始

安装 SDK 并设置客户端：

pip install "azure-ai-projects>=2.0.0b1" azure-identity openai

import os
from azure.identity import DefaultAzureCredential 
from azure.ai.projects import AIProjectClient 
from openai.types.eval_create_params import DataSourceConfigCustom
from openai.types.evals.create_eval_jsonl_run_data_source_param import (
    CreateEvalJSONLRunDataSourceParam,
    SourceFileContent,
    SourceFileContentContent,
    SourceFileID,
)

# Azure AI Project endpoint
# Example: https://<account_name>.services.ai.azure.com/api/projects/<project_name>
endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]

# Model deployment name (for AI-assisted evaluators)
# Example: gpt-5-mini
model_deployment_name = os.environ.get("AZURE_AI_MODEL_DEPLOYMENT_NAME", "")

# Dataset details (optional, for reusing existing datasets)
dataset_name = os.environ.get("DATASET_NAME", "")
dataset_version = os.environ.get("DATASET_VERSION", "1")

# Create the project client
project_client = AIProjectClient( 
    endpoint=endpoint, 
    credential=DefaultAzureCredential(), 
)

# Get the OpenAI client for evaluation API
client = project_client.get_openai_client()

准备输入数据

大多数评估方案都需要输入数据。 可以通过两种方式提供数据：

上传 JSONL 文件，以在 Foundry 项目中创建版本化数据集。 数据集支持跨多个评估运行进行版本控制并重复使用。 使用此方法进行生产测试和 CI/CD 工作流。

为每一行准备一个 JSONL 文件，其中每个 JSON 对象包含评估者所需的字段：

{"query": "What is machine learning?", "response": "Machine learning is a subset of AI.", "ground_truth": "Machine learning is a type of AI that learns from data."}
{"query": "Explain neural networks.", "response": "Neural networks are computing systems inspired by biological neural networks.", "ground_truth": "Neural networks are a set of algorithms modeled after the human brain."}

# Upload a local JSONL file. Skip this step if you already have a dataset registered.
data_id = project_client.datasets.upload_file(
    name=dataset_name,
    version=dataset_version,
    file_path="./evaluate_test_data.jsonl",
).id

提供内联数据

若要快速试验小型测试集，请在评估请求中直接使用 file_content 提供数据。

source = SourceFileContent(
    type="file_content",
    content=[
        SourceFileContentContent(
            item={
                "query": "How can I safely de-escalate a tense situation?",
                "ground_truth": "Encourage calm communication, seek help if needed, and avoid harm.",
            }
        ),
        SourceFileContentContent(
            item={
                "query": "What is the largest city in France?",
                "ground_truth": "Paris",
            }
        ),
    ],
)

在创建运行时，将source作为数据源配置中的"source"字段传递。 方案部分默认情况下使用 file_id。

数据集评估

使用 jsonl 数据源类型评估 JSONL 文件中的预计算响应。 如果已有模型输出并想要评估其质量，则此方案非常有用。

小窍门

在开始之前，请完成 入门 和 准备输入数据。

定义数据模式和评估器

指定与 JSONL 字段匹配的架构，然后选择要运行的计算器（测试条件）。 使用 data_mapping 参数将输入数据中的字段连接到具有 {{item.field}} 语法的计算器参数。 始终将 data_mapping 与每个评估者所需的输入字段一起包含。 字段名称必须与您的 JSONL 文件中的名称匹配。例如，如果数据使用 "question" 而不是 "query"，则在映射中应使用 "{{item.question}}"。 有关每个计算器所需的参数，请参阅 内置计算器。

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
            "response": {"type": "string"},
            "ground_truth": {"type": "string"},
        },
        "required": ["query", "response", "ground_truth"],
    },
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
        "data_mapping": {
            "response": "{{item.response}}",
            "ground_truth": "{{item.ground_truth}}",
        },
    },
]

创建评估并运行

创建评估，然后针对您上传的数据集开始运行任务。 该运行对数据集中的每一行执行每个评估器。

# Create the evaluation
eval_object = client.evals.create(
    name="dataset-evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run using the uploaded dataset
eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="dataset-run",
    data_source=CreateEvalJSONLRunDataSourceParam(
        type="jsonl",
        source=SourceFileID(
            type="file_id",
            id=data_id,
        ),
    ),
)

有关完整的可运行示例，请参阅 GitHub 上的 sample_evaluations_builtin_with_dataset_id.py 。 若要轮询完成结果和解释结果，请参阅 “获取结果”。

模型目标评估

在运行时向已部署的模型发送查询，并使用azure_ai_target_completions数据源类型和azure_ai_model目标来评估响应。 输入数据包含查询;模型将生成随后评估的响应。

小窍门

在开始之前，请完成 入门 和 准备输入数据。

定义消息模板和目标

该 input_messages 模板控制如何将查询发送到模型。 请使用 {{item.query}} 引用输入数据中的字段。 指定要计算的模型和可选的采样参数：

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_model",
    "model": "gpt-5-mini",
    "sampling_params": {
        "top_p": 1.0,
        "max_completion_tokens": 2048,
    },
}

设置评估器和数据映射

当模型在运行时生成响应，用{{sample.output_text}}在data_mapping中使用来引用模型的输出。 请使用 {{item.field}} 引用输入数据中的字段。

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
        },
        "required": ["query"],
    },
    include_sample_schema=True,
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

创建评估并运行

eval_object = client.evals.create(
    name="Model Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="model-target-evaluation",
    data_source=data_source,
)

有关完整的可运行示例，请参阅 GitHub 上的 sample_model_evaluation.py 。 若要轮询完成结果和解释结果，请参阅 “获取结果”。

小窍门

若要添加另一个评估运行，可以使用同一代码。

代理目标评估

在运行时将查询发送到 Foundry 代理，并使用azure_ai_target_completions数据源类型和azure_ai_agent目标来评估响应。

小窍门

在开始之前，请完成 入门 和 准备输入数据。

定义消息模板和目标

该 input_messages 模板控制如何将查询发送到代理。 请使用 {{item.query}} 引用输入数据中的字段。 指定要通过名称评估的代理:

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "developer",
            "content": {
                "type": "input_text",
                "text": "You are a helpful assistant. Answer clearly and safely."
            }
        },
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_agent",
    "name": "my-agent",
    "version": "1"  # Optional. Uses latest version if omitted.
}

设置评估器和数据映射

当代理在运行时生成响应时，请使用 {{sample.*}} 变量 data_mapping 引用代理的输出：

Variable Description 用于
{{sample.output_text}} 代理的纯文本响应。 需要字符串响应的评估器（例如，coherence，violence）。
{{sample.output_items}} 代理的结构化 JSON 输出，包括工具调用。 需要完全交互上下文（例如，task_adherence）的评估器。
{{item.field}} 输入数据中的一个字段。 输入字段，例如 query 或 ground_truth。

小窍门

该 query 字段可以包含结构化 JSON，包括系统消息和对话历史记录。 某些代理计算器，例如 task_adherence 使用此上下文进行更准确的评分。 有关查询格式的详细信息，请参阅 代理计算器。

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
        },
        "required": ["query"],
    },
    include_sample_schema=True,
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "task_adherence",
        "evaluator_name": "builtin.task_adherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    },
]

创建评估并运行

eval_object = client.evals.create(
    name="Agent Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

agent_eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-target-evaluation",
    data_source=data_source,
)

有关完整的可运行示例，请参阅 GitHub 上的 sample_agent_evaluation.py 。 若要轮询完成结果和解释结果，请参阅 “获取结果”。

代理响应评估

使用 azure_ai_responses 数据源类型按响应 ID 检索和评估 Foundry 代理响应。 使用此方案评估发生特定代理交互后的情况。

小窍门

在开始之前，请完成 入门。

响应 ID 是每次 Foundry 代理生成响应时返回的唯一标识符。 可以使用 响应 API 或应用程序的跟踪日志从代理交互收集响应 ID。 以文件内容的形式提供内联 ID，或将其作为数据集上传（请参阅 准备输入数据）。

收集响应 ID

每次调用响应 API 都会返回一个具有唯 id 一字段的响应对象。 从应用程序的交互中收集这些 ID，或直接生成这些 ID：

# Generate response IDs by calling a model through the Responses API
response = client.responses.create(
    model=model_deployment_name,
    input="What is machine learning?",
)
print(response.id)  # Example: resp_abc123

还可以从应用程序的跟踪日志或监视管道中的代理交互中收集响应 ID。 每个响应 ID 唯一标识评估服务可以检索的存储响应。

创建评估并运行

data_source_config = {"type": "azure_ai_source", "scenario": "responses"}

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
    },
]

eval_object = client.evals.create(
    name="Agent Response Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_responses",
    "item_generation_params": {
        "type": "response_retrieval",
        "data_mapping": {"response_id": "{{item.resp_id}}"},
        "source": {
            "type": "file_content",
            "content": [
                {"item": {"resp_id": "resp_abc123"}},
                {"item": {"resp_id": "resp_def456"}},
            ]
        },
    },
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-response-evaluation",
    data_source=data_source,
)

有关完整的可运行示例，请参阅 GitHub 上的 sample_agent_response_evaluation.py 。 若要轮询完成结果和解释结果，请参阅 “获取结果”。

获取结果

评估运行完成后，检索评分的结果，并在门户中或以编程方式查看它们。

执行轮询以获取结果

评估运行是异步的。 轮询运行状态，直到运行完成，然后检索结果：

import time
from pprint import pprint

while True:
    run = client.evals.runs.retrieve(
        run_id=eval_run.id, eval_id=eval_object.id
    )
    if run.status in ("completed", "failed"):
        break
    time.sleep(5)
    print("Waiting for eval run to complete...")

# Retrieve results
output_items = list(
    client.evals.runs.output_items.list(
        run_id=run.id, eval_id=eval_object.id
    )
)
pprint(output_items)
print(f"Report URL: {run.report_url}")

分析结果

对于单个数据示例，所有计算器都输出以下架构：

  • 标签：一个“通过”或“失败”的标签，类似于单元测试的输出。 使用此结果可促进评估器之间的比较。
  • 评分：每个评估者自然刻度上的分数。 一些评估者使用细粒度的标尺，在 5 分级（质量评估器）或 7 分级（内容安全评估器）评分。 其他（如文本相似性计算器）使用 F1 分数，这些分数在 0 和 1 之间浮动。 基于“阈值”，任何非二元的“score”都会被二值化为“pass”或“fail”，然后放入“标签”字段中。
  • 阈值：任何非二进制分数都会根据默认阈值被二值化为“通过”或“失败”。用户可以在 SDK 体验中重写该默认阈值。
  • 原因：为了提高可理解性，所有 LLM 法官评估器也输出一个推理字段，以解释为什么给出特定分数。
  • 详细信息：（可选）对于某些计算器（如tool_call_accuracy），可能有一个“详细信息”字段或标志，其中包含其他信息以帮助用户调试其应用程序。

示例输出（单个项）

{
  "type": "azure_ai_evaluator",
  "name": "Coherence",
  "metric": "coherence",
  "score": 4.0,
  "label": "pass",
  "reason": "The response is well-structured and logically organized, presenting information in a clear and coherent manner.",
  "threshold": 3,
  "passed": true
}

示例输出（聚合）

对于多个数据样本（数据集）的聚合结果，包含“通过”样本的平均比率构成了该数据集的通过率。

{
  "eval_id": "eval_abc123",
  "run_id": "run_xyz789",
  "status": "completed",
  "result_counts": {
    "passed": 85,
    "failed": 15,
    "total": 100
  },
  "per_testing_criteria_results": [
    {
      "name": "coherence",
      "passed": 92,
      "failed": 8,
      "pass_rate": 0.92
    },
    {
      "name": "relevance", 
      "passed": 78,
      "failed": 22,
      "pass_rate": 0.78
    }
  ]
}

故障排除

长时间运行的作业

你的评估作业可能会长时间处于 “正在运行” 状态。 当 Azure OpenAI 模型部署没有足够的容量时，通常会发生这种情况，导致服务重试请求。

解决方法：

  1. 使用 client.evals.runs.cancel(run_id, eval_id=eval_id) 取消当前评估作业。
  2. 在 Azure 门户中增加模型容量。
  3. 再次运行评估。

身份验证错误

如果收到401 Unauthorized或403 Forbidden错误，请验证：

  • 您的 DefaultAzureCredential 已配置正确（如果使用 Azure CLI，请运行 az login）。
  • 你的帐户在 Foundry 项目中具有 Azure AI 用户 角色。
  • 项目终结点 URL 正确，包括帐户和项目名称。

数据格式错误

如果评估失败并出现架构或数据映射错误：

  • 验证 JSONL 文件是否每行有一个有效的 JSON 对象。
  • 确认 JSONL 文件中的字段名称与字段名称 data_mapping 完全匹配（区分大小写）。
  • 检查属性是否 item_schema 与数据集中的字段匹配。

额度限制错误

评估运行创建在租户级别、订阅级别和项目级别均受到速率限制。 如果收到 429 Too Many Requests 响应：

  • 检查 retry-after 响应中的标头，了解建议的等待时间。
  • 查看响应正文以了解速率限制详细信息。
  • 重试请求失败时，使用指数退避。

如果在执行过程中评估作业失败并出现 429 错误：

  • 减小评估数据集的大小，或将其拆分为较小的批处理。
  • 在 Azure 门户中增加模型部署的每分钟令牌（TPM）配额。

代理评估器工具错误

如果代理评估器返回不受支持工具的错误：

  • 检查代理评估工具支持的工具。
  • 解决方法是，将不受支持的工具包装为用户定义的函数工具，以便计算器可以评估它们。

相关内容

  • Last updated on