nemo-evaluator-plugin

Evaluator Plugin

Plugin CLI 入口点为 uv run nemo evaluator。

用途

使用此技能选择评估接口和指标，验证最小示例，提交 NeMo Platform 评估任务，并获取其结果。

输入

构建评估前，请确定以下输入：

• 评估接口：数据集驱动评估与任务驱动 Agentic 评估
• 执行接口：独立 SDK 评估或持久化的 NeMo Platform 任务。
• 通过/失败数据集示例：最具代表性的最小通过和失败案例。
• 指标：要评分的行为及其使用的模板字段。
• 目标：离线评分时无需目标；否则提供生成输出的模型、Agent、运行器或预计算试验结果。

说明

1. 确认输入是数据集驱动的行 还是任务驱动的 Agent 工作。
2. 选择能衡量所需行为的最简单指标。尽可能优先选择确定性指标。
3. 构建一个包含一个预期通过案例和一个预期失败案例的小型冒烟测试。
4. 使用独立 SDK 验证指标行为，并检查行级输出和汇总结果。
5. 在扩大规模前，修正字段映射、提示词、解析器或任务定义。
6. 只有在输入和评分形式正常运行后，才提交平台任务。

为量规、RAG 工作流或工具调用评估选择指标前，请阅读指标选择。

选择执行接口

需求	接口
不使用 NeMo Platform，快速迭代指标	nemo_evaluator_sdk.Evaluator
数据集驱动的平台任务	client.evaluator.submit(...) 或 nemo evaluator evaluate submit
在一个任务中使用多个内联/存储的指标引用	使用 EvaluateInputSpec 的 nemo evaluator evaluate submit
任务驱动的平台任务	nemo evaluator agent-evaluate submit
可复用的平台定义和结果索引	client.evaluator.metrics、.tasks、.tasksets、.eval_results、.agent_eval_results

所有插件评估默认使用 submit。插件的本地执行路径 （client.evaluator.run() 和 nemo evaluator ... run CLI 子命令） 即将弃用，因此即使 --help 仍列出该路径，也不要基于它构建。若要 在不使用平台的情况下快速迭代指标，请改用独立的 nemo_evaluator_sdk.Evaluator。

• 请阅读 SDK 执行，了解数据集、目标、 配置、字段映射、任务生命周期和自定义指标打包。
• 请阅读存储资源，了解持久化定义和结果查询。

限制

• 独立运行时，api_key_secret 是环境变量名称；使用 submit 时，它是 NeMo Platform 密钥名称。请参阅 API 身份验证。
• 提交时收到 HTTP 409 通常表示缺少所引用的平台密钥，而非任务重复。请阅读响应正文。
• intent 是评分器元数据，不会展示给 Agent；只有 inputs 会传递给它。
• 指标模板在数据集行中使用 item.*，而在 Agent 评估中使用 reference.*、sample.* 和 inputs.*。
• 指标进度可能在平台任务结束前达到 100%。获取结果或下载 构件前，务必调用 job.wait_until_done()。

CLI 接口

先决条件

本文件中的所有命令均假定 Shell 的当前工作目录为 NVIDIA-NeMo/nemo-platform 仓库的根目录。

在 NeMo Platform 仓库检出目录中，通过工作区运行命令：

# confirms plugin readiness and lists the registered evaluator jobs.
uv run nemo evaluator info
# lists available metric names; add a metric name to print its schema.
uv run nemo evaluator metric-types
# next two commands print the dataset-driven and task-driven job input and
# output schemas - can be very large, use with caution to avoid filling up the context window.
uv run nemo evaluator evaluate explain
uv run nemo evaluator agent-evaluate explain

安装技能和插件后，直接使用已安装的 nemo 命令，无需假定当前目录为仓库根目录，也无需手动激活 .venv。

相对于此技能目录解析随附资源。在此仓库中，规范路径为 skills/nemo-evaluator-plugin；已安装的技能可能位于不同的 skills 根目录下。

捆绑资源

路径	用途
assets/specs/exact_match_metric.json	两行离线冒烟测试规范；按原样提交
assets/specs/llm_as_judge.json	在线生成 + 评审；优先使用本地配置（NVIDIA_API_KEY）
assets/specs/fabric_agent_eval.json	任务驱动的 Fabric 运行器规范
assets/examples/plugin_sdk_examples.py	每个插件接口的可复制 SDK 代码片段

可用脚本

脚本	用途	参数
scripts/generate_example_specs.py	生成或检查捆绑规范是否存在偏差	--check、--write

在此仓库中，NeMo 使用显示的工作区命令：

uv run --frozen python skills/nemo-evaluator-plugin/scripts/generate_example_specs.py --check

不要假设客户端特定的 run_script() 辅助函数存在；请使用显示的 uv run 命令。

示例

数据集驱动的评估示例

• 按照先独立验证，再提交到平台， 进行两行通过/失败冒烟测试并通过 CLI 提交。
• 当数据集列需要 field_mapping 时，请按照映射非规范字段。
• 按照获取作业结果，完成提交、等待作业结束、获取结果和下载产物。
• 按照存储指标、任务和任务集，保存可复用定义；按照查询已持久化结果查找结果。

任务驱动的 Agent 评估示例

独立 SDK 评估

使用 AgentEvaluator().run(...) 进行独立的任务驱动 SDK 评估。其 target 可以是 Model、GenericAgent 或直接的 AgentTaskRunner。

平台作业评估

使用插件 agent-evaluate submit 作业进行平台任务评估。其 target 可以是 ModelTarget、AgentTarget、CodexRunnerTarget、 FabricRunnerTarget 或 HarborRunnerTarget；也可以提供预先计算的 trials。target 和 trials 必须且只能提供其中一个。

提交时可以使用内联任务或已存储的 TasksetRef。已存储的任务集会在目标工作区中解析。

阅读 Agent 评估，了解内联任务、 TasksetRef、并发、快速失败行为、结果产物和运行器配置。

在仓库检出目录中准备 Fabric

Fabric 运行器示例和测试需要可选的适配器以及匹配的 Relay 网关：

uv sync --frozen --package nemo-evaluator-sdk --extra fabric --inexact
script/dev-install-fabric.sh

安装脚本会下载与已锁定 Python 绑定匹配且经过校验和验证的 nemo-relay 二进制文件。将其报告的目录添加到 PATH，然后使用 uv run --frozen --no-sync ... 运行 Fabric 检查，以免 uv 移除可选适配器。

输出格式

按以下形式报告已完成的平台评估：

Job: <job-name>
Status: <terminal-status>
Metrics: <metric-names>
Mean: <aggregate-mean>
Artifacts: <downloaded result or artifact location>
Errors: <error messages>

阅读专项参考文档

• 使用模型、Agent、远程指标或持久化提交前，请阅读评估器 API 身份验证。
• 编写评审分数、提示词或解析器前，请阅读 LLM 评审。

故障排除

当架构、身份验证、作业、结果或运行器行为出现问题时，请阅读评估器故障排除。

遵循安全最佳实践

切勿打印、序列化或提交密钥值。规范和示例中只能存储环境变量名称或平台密钥引用。