代理评估 CLI 参考 (预览版)

本文提供了命令的完整命令行参考 runevals ，该命令是包的 @microsoft/m365-copilot-eval 一部分。

注意

代理评估 CLI 目前为预览版。特性和功能可能会发生更改。

简介

runevals [options]
runevals cache-info
runevals cache-clear
runevals cache-dir

说明

该runevals命令使用 Azure AI + 机器学习评估指标发送测试提示和评分响应来评估智能智能 Microsoft 365 Copilot 副驾驶® 副驾驶®代理。该工具支持从 JSON 文件、内联提示和交互式测试进行批量评估。

选项

`-V, --version`

输出 CLI 工具的版本号。

示例：

runevals --version

输出：

1.3.0-preview.1

`--log-level [level]`

设置日志记录详细级别。可用级别： debug、 info、 warning、 error。

默认值：如果使用不带值的标志，则默认为 info。
debug：详细的调试信息，包括 API 有效负载。
info：有关评估进度的一般信息。
警告：仅警告消息。
error：仅错误消息。

示例：

# Info level (default when flag is present)
runevals --log-level

# Debug level
runevals --log-level debug

# Error level only
runevals --log-level error

警告

该 debug 级别可能包括控制台输出中的原始 API 有效负载和响应数据。修订是基于模式的，可能不会捕获所有 PII 或凭据。未经手动评审，请勿公开共享调试输出。

`--prompts <prompts...>`

直接在命令行上指定一个或多个提示，以便快速测试，而无需创建文件。

示例：

# Single prompt
runevals --prompts "What is Microsoft 365?"

# Multiple prompts
runevals --prompts "What is Teams?" "What is SharePoint?" "What is OneDrive?"

`--expected <responses...>`

提供预期的响应，以随附指定的 --prompts提示。响应数必须与提示数匹配。

示例：

runevals --prompts "What is Microsoft Graph?" \
  --expected "Microsoft Graph is the API gateway to Microsoft 365 data and intelligence."

多个提示和响应：

runevals --prompts "What is Teams?" "What is SharePoint?" \
  --expected "Teams is a collaboration platform" "SharePoint is a content management system"

`--prompts-file <file>`

指定包含测试提示的自定义 JSON 文件。此文件将替代自动发现。

示例：

runevals --prompts-file ./tests/my-custom-tests.json

文件格式：

[
  {
    "prompt": "Test question",
    "expected_response": "Expected answer"
  }
]

有关完整的数据集架构，请参阅数据集架构和测试设计。

`-o, --output <file>`

指定输出文件路径和格式。格式由文件扩展名决定。

支持的格式：

.html - HTML 报表 (默认，在浏览器) 中自动打开
.json - JSON 结果
.csv - CSV 电子表格

示例：

# HTML output
runevals --output ./reports/results.html

# JSON output
runevals --output ./results/eval-results.json

# CSV output
runevals --output ./data/scores.csv

默认行为：

如果没有 --output，该命令会将结果保存到 ./.evals/YYYY-MM-DD_HH-MM-SS.html。

`-i, --interactive`

进入交互式模式进行手动提示输入和测试。

示例：

runevals --interactive

在交互模式下，系统会提示你一次输入一个提示，以便可以执行探索性测试。

`--m365-agent-id <id>`

重写代理 ID 以评估特定代理。在测试多个代理或无法自动检测代理 ID 时，此参数非常有用。

示例：

runevals --m365-agent-id "U_0dc4a8a2-b95f-edac-91c8-d802023ec2d4"

代理 ID 格式：

用户范围： U_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
租户范围： T_agent-name.declarativeAgent

`--env <environment>`

指定要加载的环境配置。此参数加载 env/.env.<environment>。

默认值： dev (加载 env/.env.dev)

示例：

# Load env/.env.dev (default)
runevals --env dev

# Load env/.env.prod
runevals --env prod

# Load env/.env.staging
runevals --env staging

环境文件优先级：

.env.local) 代理工具包项目自动检测到 (
.env.local.user (机密，如果存在) ，则会自动加载
env/.env.<environment>) --env 指定的 (
系统环境变量

`--init-only`

在不运行评估的情况下初始化 Python 环境并下载依赖项。此选项适用于：

在 CI/CD 管道中预热缓存
排查安装问题
在运行测试之前验证设置

示例：

runevals --init-only

若要进行故障排除，请将此选项与 --log-level debug结合使用：

runevals --init-only --log-level debug

`-h, --help`

显示有关可用命令和选项的帮助信息。

示例：

runevals --help

缓存命令

评估工具对 Python 运行时和依赖项使用本地缓存。这些命令可帮助你管理缓存。

`cache-info`

显示有关缓存 Python 环境的统计信息，包括大小、位置和已安装的包。

示例：

runevals cache-info

输出：

Cache Information

Location: C:\Users\YourName\.m365-copilot-eval\cache
Size: 245 MB
Python Version: 3.11.5
Packages: 42 installed

Last updated: 2026-04-10 14:23:15

`cache-clear`

删除缓存的 Python 环境和所有下载的依赖项。排查安装问题或释放磁盘空间时，请使用此命令。

示例：

runevals cache-clear

跟进：

清除缓存后，重新初始化：

runevals --init-only

`cache-dir`

打印缓存目录的绝对路径。此功能对于脚本或手动检查非常有用。

示例：

runevals cache-dir

输出：

C:\Users\YourName\.m365-copilot-eval\cache

脚本中的用法：

# Check cache directory permissions (Unix/macOS)
chmod -R u+w $(runevals cache-dir)

# View cache contents
ls -lah $(runevals cache-dir)

环境变量

该工具从环境文件和系统变量读取配置。有关获取这些值的分步说明，请参阅所需的环境变量。

必需变量

变量	说明	示例
`TENANT_ID`	Microsoft Entra租户 ID	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
`AZURE_AI_OPENAI_ENDPOINT`	Azure Foundry Model 中的 OpenAI 终结点 URL	`https://your-resource.openai.azure.com/`
`AZURE_AI_API_KEY`	Azure OpenAI API 密钥	`your-api-key-here`

可选变量

变量	说明	默认值
`M365_AGENT_ID`	要评估的代理 ID	自动检测自 `M365_TITLE_ID`
`M365_TITLE_ID`	代理名称 ID (Agents Toolkit)	无
`AZURE_AI_API_VERSION`	Azure OpenAI API 版本	`2024-12-01-preview`
`AZURE_AI_MODEL_NAME`	评估模型	`gpt-4o-mini`

示例

基本用法

使用自动发现的数据集文件进行评估：

cd /path/to/your-agent-project
runevals

指定环境

使用生产环境配置：

runevals --env prod

自定义数据集文件

使用特定的测试文件：

runevals --prompts-file ./tests/regression-tests.json

内联测试

使用内联提示进行快速测试：

runevals --prompts "What is Microsoft 365?" \
  --expected "Microsoft 365 is a cloud-based productivity suite"

交互模式

手动输入提示：

runevals --interactive

自定义输出格式

生成 JSON 结果：

runevals --output ./results/eval-$(date +%Y%m%d).json

调试模式

使用详细日志记录运行：

runevals --log-level debug --output ./debug-results.json

仅设置

在不运行测试的情况下预缓存 Python 环境：

runevals --init-only --log-level info

替代代理 ID

测试特定代理：

runevals --m365-agent-id "U_0dc4a8a2-b95f-edac-91c8-d802023ec2d4"

组合选项

使用自定义设置进行全面评估：

runevals \
  --env staging \
  --prompts-file ./evals/full-suite.json \
  --output ./reports/staging-eval-$(date +%Y%m%d).html \
  --log-level info \
  --m365-agent-id "T_my-agent.declarativeAgent"

退出代码

代码	含义
`0`	成功
`1`	常规错误
`2`	参数无效
`3`	环境配置错误
`4`	找不到代理
`5`	身份验证失败
`10`	Python 环境设置失败

疑难解答

有关安装、身份验证、运行时错误、缓存问题和代理设置的常见问题，请参阅故障排除一文。

反馈

此页面是否有帮助？

Last updated on 2026-05-01

代理评估 CLI 参考 (预览版)

简介

说明

选项

-V, --version

--log-level [level]

--prompts <prompts...>

--expected <responses...>

--prompts-file <file>

-o, --output <file>

-i, --interactive

--m365-agent-id <id>

--env <environment>

--init-only

-h, --help

缓存命令

cache-info

cache-clear

cache-dir

环境变量

必需变量

可选变量

示例

基本用法

指定环境

自定义数据集文件

内联测试

交互模式

自定义输出格式

调试模式

仅设置

替代代理 ID

组合选项

退出代码

疑难解答

相关内容

反馈

其他资源

`-V, --version`

`--log-level [level]`

`--prompts <prompts...>`

`--expected <responses...>`

`--prompts-file <file>`

`-o, --output <file>`

`-i, --interactive`

`--m365-agent-id <id>`

`--env <environment>`

`--init-only`

`-h, --help`

`cache-info`

`cache-clear`

`cache-dir`