智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶®评估 CLI 参考

本文提供该 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

环境文件优先级:

  1. .env.local (自动检测 Agents Toolkit 项目)
  2. .env.local.user (机密,如果存在,则自动加载)
  3. env/.env.<environment> (由 --env) 指定
  4. 系统环境变量

--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 环境设置失败

疑难解答

有关安装、身份验证、运行时错误、缓存问题和代理设置的常见问题,请参阅疑 难解答 文章。