本文提供该 runevals 命令的完整命令行参考,它是该 @microsoft/m365-copilot-eval 命令的一部分。
剧情简介
runevals [options]
runevals cache-info
runevals cache-clear
runevals cache-dir
说明
该runevals命令通过使用 Microsoft Foundry 云评估和内置指标发送测试提示和评分响应来评估 智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 代理。 该工具支持从 JSON 文件、内联提示和交互式测试进行批量评估。
CLI v1 使用 npm latest 标记。 CLI v2 使用 preview 并评估使用插件的 Copilot 响应。 在 v2 中,没有配置代理 ID 的运行将评估智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 聊天。 有关预览设置和架构 v2 示例,请参阅 工具调用评估程序。
选项
-V, --version
输出 CLI 工具的版本号。
示例:
runevals --version
输出:
1.15.0
--log-level [level]
设置日志记录详细级别。 可用级别: debug、 info、 warning。 error
-
默认值:使用不带值的标志时,它默认为
info. - debug:详细的调试信息,包括 API 有效负载。
- 信息:有关评估进度的一般信息。
- 警告:仅警告消息。
- 错误:仅错误消息。
示例:
# 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
对于 v2 预览插件方案,请省略此选项,并从 shell 和加载的环境文件中删除M365_AGENT_ID旧版。AGENT_ID
--list-tools <agent-id> (v2 预览版)
列出声明性代理操作的同意标识符和可复制的评估者标识。 独立插件不支持此选项。 动态发现的工具可能不会出现;在评估后确认 diagnostics.tool_calls 他们的身份。
npx -y --package @microsoft/m365-copilot-eval@preview runevals --list-tools "<your-agent-id>"
有关独立插件同意名称和由三部分组成的评估程序标识,请参阅 查找工具调用名称。
--evaluate-only <file>
在不执行提示的情况下重新对保存的响应和可用诊断进行评分。 每个项目或回合都必须包含一个 response. 如果选择基于 LLM 的评估员,请配置评委;不需要 Microsoft 365 执行身份验证。
runevals --evaluate-only results\captured-responses.json --output results\rescored.html
工具调用重新评分需要 CLI v2 预览版并保留工具调用证据。 有关详细信息,请参阅 诊断和保存的响应评估。
--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(自动检测 Agents Toolkit 项目) -
.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_PROJECT_ENDPOINT |
用于基于 LLM 评分的 Microsoft Foundry 项目终结点。 不适用于仅确定性评估。 | https://<account>.services.ai.azure.com/api/projects/<project> |
可选变量
| 变量 | 说明 | 默认 |
|---|---|---|
M365_AGENT_ID |
要评估的代理 ID | 自动检测来源 M365_TITLE_ID |
M365_TITLE_ID |
代理游戏 ID (代理工具包) | 无 |
AZURE_AI_MODEL_NAME |
评估模型 | gpt-5-mini |
EVALS_SUPPRESS_DIAGNOSTICS |
设置为true省略保留的诊断。 不编辑提示、响应、评估程序选项或本机验证消息。 隐藏的证据无法重播。 |
未设置 |
示例
基本用法
使用自动发现的数据集文件进行评估:
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 环境设置失败 |
疑难解答
有关安装、身份验证、运行时错误、缓存问题和代理设置的常见问题,请参阅疑 难解答 文章。