SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场nemo-evals-plugin

nemo-evals-plugin

测试与质量

查看项目

更新于 11-01 10:59

技能介绍

用途

NeMo Helix Evals 插件用于评估模型、数据集和智能体。其命令行入口为 uv run nemo evals。该技能旨在帮助用户选择评估接口和指标，验证最小示例，提交 NeMo Helix 评估作业，并获取结果。

主要能力

  • 评估接口：支持数据集驱动、任务驱动和检索驱动三种评估方式。
  • 执行接口：提供独立 SDK 评估（nhx_evals_sdk.Evaluator）和持久化 NeMo Helix 平台作业。
  • 指标选择：可列出可用指标名称并查看模式，支持确定性指标和 LLM 评判指标。
  • 平台作业命令：默认使用 nemo evals evaluate、nemo evals agent-evaluate 和 nemo evals retrieve-eval 进行持久化平台评估。
  • 结果管理：支持存储指标、任务、任务集等可复用定义，并查询持久化结果。
  • 捆绑资产：提供离线冒烟测试规范、在线生成加评判规范、任务驱动 Fabric 和 Gym 运行器规范，以及 SDK 示例脚本。
  • 示例脚本：scripts/generate_example_specs.py 可用于生成或检查捆绑规范的一致性。

使用方式

前提条件

命令假设当前工作目录为 NVIDIA-NeMo/nemo-helix 仓库根目录。在仓库检出中通过工作区运行命令：

uv run nemo evals info
uv run nemo evals metric-types
uv run nemo evals evaluate explain
uv run nemo evals agent-evaluate explain
uv run nemo evals retrieve-eval explain

若技能和插件已安装，可直接使用 nemo 命令，无需假定仓库根目录或手动激活虚拟环境。捆绑资产相对于技能目录解析，规范路径为 skills/nemo-evals-plugin。

构建评估

在构建评估之前，需要明确以下输入：

  • 评估接口：数据集驱动、任务驱动或检索驱动。
  • 执行接口：独立 SDK 评估或持久化 NeMo Helix 作业。
  • 通过/失败数据集示例：最小代表性的通过和失败用例。
  • 指标：要评分的行为及其使用的模板字段。
  • 目标：离线评分无目标，或产生输出的模型、智能体、运行器或预计算试验。

选择能衡量所需行为的最简单指标，优先使用确定性指标。构建包含一个预期通过和一个预期失败的微型冒烟用例，在独立 SDK 中验证指标行为，检查行级输出、聚合计数、nan_count 和覆盖率后再解释均值。在扩展之前修复字段映射、提示、解析器或任务定义。仅在输入和评分形式正常工作后提交平台作业。

选择执行接口

需求 接口
无需 NeMo Helix 的快速指标迭代 nhx_evals_sdk.Evaluator
数据集驱动的平台作业 evaluator.submit(...) 或 nemo evals evaluate
单个作业中多个内联/存储指标引用 nemo evals evaluate 配合 EvaluateInputSpec
任务驱动的平台作业 evaluator.submit(tasks=..., target=<runner>) 或 nemo evals agent-evaluate
检索驱动的平台作业 nemo evals retrieve-eval
可复用平台定义和结果索引 evaluator.metrics、.tasks、.tasksets、.eval_results、.agent_eval_results

默认使用插件特定的作业命令进行持久化平台评估。旧的 nemo evals ... run 和 nemo evals ... submit CLI 动词不受支持。

数据集驱动评估

遵循“独立验证”流程，然后提交到平台。两行通过/失败冒烟测试及其 CLI 提交可参考捆绑规范 assets/specs/exact_match_metric.json。数据集列需要字段映射时参考 field_mapping。作业结果获取包括提交、终端等待、结果检索和工件下载。可复用定义可存储指标、任务和任务集，并查询持久化结果。

任务驱动智能体评估

独立 SDK 评估使用 AgentEvaluator().run(...)，目标可以是 Model、GenericAgent 或直接的 AgentTaskRunner。平台作业评估使用 agent-evaluate 命令，目标为 ModelTarget、AgentTarget、FabricRunnerTarget、HarborRunnerTarget 或 GymRunnerTarget，或提供预计算试验。必须且只能提供 target 或 trials 之一。

FabricRunnerTarget 的源可以是内联配置（{"kind": "fabric", "source": {"config": {...}}}）或已注册智能体（{"kind": "fabric", "source": {"agent": "<name>"}}）。HarborRunnerTarget 的源采用相同的注册智能体形状，在每个任务容器内运行，可与内置智能体（{"name": "oracle"}）或自定义智能体（{"import_path": "pkg:Agent"}）并列。GymRunnerTarget 的源也接受注册智能体形状，并需要 resources_server，在沙箱化 Gym 主机上运行。提交时服务按部署方式解析智能体，模型绑定到工作区推理网关，规范中不含凭证，每次试验都全新运行。可选环境可重定向 MCP 服务器到模拟、添加进程环境变量并按引用绑定秘密。仅 nemo-agents-spec-v1 智能体可解析，不支持模型覆盖。

提交接受内联任务或存储的 TasksetRef，存储任务集在目标工作区解析。

准备 Fabric

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

uv sync --frozen --package nhx-evals-sdk --extra fabric --inexact
script/dev-install-fabric.sh

安装脚本下载与锁定 Python 绑定匹配的校验和验证的 nemo-relay 二进制文件。将其报告目录添加到 PATH，然后使用 uv run --frozen --no-sync ... 进行 Fabric 检查。

输出格式

完成的平台评估报告格式：

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

适用场景

  • 需要比较不同模型或智能体在数据集上的表现。
  • 需要按任务驱动方式评估智能体在特定任务上的行为。
  • 需要对检索结果进行 BEIR 风格的评估。
  • 需要快速迭代指标并在独立 SDK 中验证。
  • 需要提交持久化平台作业并管理可复用评估定义。

限制

  • api_key_secret 在独立使用时是环境变量名，提交时是 NeMo 平台秘密名称。
  • 提交返回 HTTP 409 通常表示引用的平台秘密缺失，而非重复作业，应阅读响应体。
  • intent 是评分器元数据，从不展示给智能体，仅 inputs 到达智能体。
  • 指标模板对数据集行使用 item.*，但在智能体评估中使用 reference.*、sample.* 和 inputs.*。
  • 指标进度可能在平台作业终止前达到 100%，检索结果或下载工件前必须调用 job.wait_until_done()。
  • 需要完整嵌入/重排微调方案时，应转交 nemo-retrieval-recipes，本技能仅用于运行和调试 retrieve-eval。
  • GymRunnerTarget 需要沙箱化执行，作业会暂存包含 harness 的 wheels-v1 包。
  • 仅 nemo-agents-spec-v1 智能体可解析，不支持模型覆盖。
  • 不要打印、序列化或提交秘密值，规范中仅存储环境变量名或平台秘密引用。