在 Model-Optimizer 中使用 NeMo Evaluator Launcher 运行 GPQA Diamond 基准评估：任务配置、并行度调优与 MLflow 分数提取

本指南以仓库内置的 GPQA Diamond 任务参考 为核心，讲解如何在 Model-Optimizer 项目的 NEL（NeMo Evaluator Launcher）评估体系中，将 GPQA Diamond（AA 4-choice MCQ 版本）作为 evaluation.tasks 列表中的一个任务接入，完成从 YAML 配置、dry-run → canary → 全量运行，到从 MLflow 中提取 gpqa_pass_at_1 分数的完整闭环。读完本文，你将掌握 ns_gpqa 任务的参数语义（num_repeats、prompt_config）、其与 example_eval.yaml 模板的拼接方式，以及如何在量化/基线模型对比中正确提取并验证该指标。

GPQA Diamond 任务是什么

GPQA（Graduate-Level Google-Proof Q&A）Diamond 是面向研究生级别科学问题的多项选择题基准，Diamond 子集是其最高难度分层。在 Model-Optimizer 的评估技能体系中，该任务被封装为 nemo-skills harness 下的 ns_gpqa 任务，并采用 Artificial Analysis（AA）Index v2 的 4 选 1 多选题提示（prompt）模板运行，即任务参考中明确写明的参数组合：

• harness：nemo-skills ns_gpqa
• 提示模板：AA 4-choice MCQ（++prompt_config=eval/aai/mcq-4choices）
• 重复次数：num_repeats: 16

需要说明的是，任务参考中标注的 Reference 指向 NVIDIA NeMo Evaluator 官方基准文档（外链，此处不展开），本文内容均以仓库内实际文件为准。从源码结构看，该任务是 AA Index v2 套件 的组成部分——当用户请求 "AA / Artificial Analysis" 评估时，技能会按 SKILL.md 中的 AA 规则，把 recipes/tasks/aa/ 下的多个任务合并生成一个多任务配置，GPQA Diamond 是该套件中面向短上下文、模型计算密集型（model-bound）的代表任务。

运行前提与 .env 配置

ns_gpqa 属于 nemo-skills 任务，对运行环境有明确要求（对应 SKILL.md 的 Step 1 与 env.example）：

1. NEL 已安装：执行 nel --version 检查，缺失时 pip install nemo-evaluator-launcher。
2. 工作区 .env 文件：从技能目录的模板复制到工作区根目录（即运行 nel 的目录），不要放在技能目录内：

cp "$SKILL_DIR/recipes/env.example" .env
set -a && source .env && set +a

3. 必填键：HF_TOKEN（模型/数据集下载必需）；DUMMY_API_KEY=dummy（nemo-skills 任务的硬性要求——nemo-skills 任务硬性要求服务端点的 api_key_name 环境变量在评测容器内有值，见 example_eval.yaml 中 evaluation.env_vars.DUMMY_API_KEY: lit:dummy 的注释说明）；NEMO_EVALUATOR_TRUST_PRE_CMD=1（允许 pre_cmd 执行）。

需要注意：GPQA Diamond 是符号判分任务（symbolic grading），不依赖 judge 端点，因此与 HLE、AA-LCR 等 judge 型任务不同，INFERENCE_API_KEY / INFERENCE_JUDGE_URL 并非必需（参考 env.example 中对各键用途的区分）。

在 evaluation.tasks 中接入 ns_gpqa

任务参考给出的 YAML 片段是接入的核心。将它放在顶层 evaluation.tasks 列表中：

- name: ns_gpqa
  container: nvcr.io/nvidia/eval-factory/nemo-skills:26.03
  nemo_evaluator_config:
    config:
      params:
        extra:
          num_repeats: 16
          args: "++prompt_config=eval/aai/mcq-4choices"

各字段语义如下：

字段	含义
name	任务名 ns_gpqa（nemo-skills 前缀 ns_ 标识其 harness）
container	评测容器镜像 nvcr.io/nvidia/eval-factory/nemo-skills:26.03，pyxis 加载时需要 registry#path:tag 形式（非 DockerHub 镜像，见 launcher-workflow.md 的配置放置注意事项）
nemo_evaluator_config.config.params.extra.num_repeats	每个问题的采样重复次数，本任务固定为 16，直接决定最终指标中的 avg-of-N 的 N 值
extra.args	传给 harness 的 Hydra 风格覆写：++prompt_config=eval/aai/mcq-4choices，即强制使用 AA 的 4 选 1 MCQ 提示模板

在完整模板中拼接：仓库的 example_eval.yaml 已经内置了完全相同的 ns_gpqa 任务块（含 num_repeats: 16 与 mcq-4choices 提示），并把它作为 AA 对齐模板的默认单任务起点。该模板同时定义了配套的部署与运行约定，例如：

• 部署统一放在 deployment.command 的 vllm serve /checkpoint 字符串中（--served-model-name 必填，否则 vLLM 以 /checkpoint 为模型名提供服务和评测请求会 404）；
• 优先使用集群上已有的 checkpoint_path 而非 hf_model_handle（后者在当前 NEL 中不能可靠挂载到 /checkpoint，会触发 HFValidationError）；
• 采样参数 temperature: 1.0、top_p: 0.95、max_new_tokens: 65536（推理模型；非推理模型用 16384）取自模型卡；
• execution.auto_export.destinations: [mlflow] 是自动导出到 MLflow 的必需触发器，缺失则运行结果不会被上传。

关键参数深入：num_repeats 与 avg-of-N

num_repeats: 16 不是随意取值，它与指标的聚合方式直接绑定。任务参考的分数提取一节明确指出：最终指标为 gpqa_pass_at_1_avg-of-N_symbolic_correct，其中 N 即重复次数，因此本任务实际上报的是：

gpqa_pass_at_1_avg-of-16_symbolic_correct

• pass_at_1：单次采样即答对（k=1 的 pass@k 口径）；
• avg-of-N：对同一问题重复采样 N 次后的正确率取平均，用多次采样抑制单次采样方差，得到更稳定的任务级正确率；
• symbolic_correct：采用符号/规则判分（比对标准答案），与 judge 判分（LLM 判官）相对，这也是该任务无需配置 judge 端点、完全离线自洽的原因。

任务参考同时给出兜底规则：如果重复次数未知，就使用 MLflow 中可用的最高 avg-of-N 指标。因此 num_repeats 一旦在配置中改变，提取指标名必须同步改变（例如改为 8 则应读取 gpqa_pass_at_1_avg-of-8_symbolic_correct），否则会把错误口径的分数当作结果。

分数提取：从 MLflow 读取

任务参考定义的规范分数提取方式（0-100 分制）如下：

Result (0-100): gpqa_pass_at_1_avg-of-N_symbolic_correct

操作要点（结合 launcher-workflow.md 的 shortcut 路径说明与 example_eval.yaml 的 export 块）：

1. 确保自动导出生效：execution.auto_export.destinations: [mlflow] 必须存在；且需设置 execution.cpu_partition（自动导出是独立的纯 CPU sbatch，GPU 分区会以 Cannot find GPU specification 拒绝它，导致导出被静默丢弃）。
2. export.mlflow 块使用字面量：experiment_name / description / tags 不得使用 ${deployment.*} / ${evaluation.*} 交叉引用（自动导出在提交时解析，作用域不含这些节点，会报 Interpolation key not found）。其中 temperature / top_p / max_new_tokens 标签是 MLflow 中采样配置的唯一可查询记录（NEL 不把它们记为 run params），必须与顶层 params 保持一致并在同一处编辑同步更新。
3. 读取分数：从对应 MLflow run 中读取 gpqa_pass_at_1_avg-of-16_symbolic_correct 字段，数值已在 0-100 区间内，可直接用于基线 vs 量化模型的对比（对比请使用 compare-results 技能）。

运行流程：dry-run → canary → 全量

ns_gpqa 遵循 NEL 的标准三阶段门控（SKILL.md 与 launcher-workflow.md），建议严格按序执行：

# 1. dry-run：校验配置、部署命令与任务列表
nel run --config recipes/examples/example_eval.yaml --dry-run \
  -o deployment.checkpoint_path=/path/to/quantized/checkpoint \
  -o deployment.served_model_name=my-model-nvfp4 \
  -o execution.hostname=<slurm_host> \
  -o execution.account=<slurm_account> \
  -o execution.output_dir=/path/to/output

# 2. canary：用极少量样本验证日志与并行度（2 samples）
nel run --config ... \
  -o ++evaluation.nemo_evaluator_config.config.params.limit_samples=2

# 3. 全量：正式评分运行
nel run --config ... -t ns_gpqa

其中 -t ns_gpqa 可只运行该单任务。canary 阶段应检查：服务端是否成功加载 checkpoint、评测日志有无 Traceback/OOM/timeout、样本是否全部完成打分。

并行度调优要点

GPQA Diamond 在 AA 套件中属于短上下文、模型/GPU 计算瓶颈型（model-bound）任务，参考 parallelism.md 的套件维度建议：

• 顶层 parallelism（每个 benchmark 客户端保持的在途请求数）按该任务可无抢占的 KV 容量设置即可，无需像 AA-LCR 那样降低覆盖；
• --max-num-seqs（单副本同时解码的序列数）需按所有任务中的最大 parallelism 反算：max-num-seqs = ceil(max parallelism across tasks / DP)，因为部署必须能服务最繁忙的任务；
• 8×B200 的示例参考：dense 9B NVFP4 模型在 num_repeats=1（198 个请求，请求受限）时设 parallelism=256, max-num-seqs=32；num_repeats=16 时请求量约 3168（容量受限），应从较低值起调，仅在 Preempted N 为 0 时上调；
• 拓扑遵循“最小 TP、最大 DP”原则：单卡能放下就用 TP=1, DP=G；MoE 模型需加 --enable-expert-parallel。

运行后验证：不要只看分数

在报告任何分数之前，需按 run-validation.md 完成运行验证——不能因为存在 results.yml 就认定运行有效：

• 扫描 client/server/SLURM/judge/代码执行日志中的 Traceback、Exception、ERROR、FAILED、OOM、Killed、timeout、rate limit 等关键字；
• 核对样本账目：期望样本数/重复数 vs 实际完成并打分的样本数，确认无意外丢弃/跳过/失败的样本；
• 对每个任务完成 Timeout 与 Output-Limit 记账（finish_reason: length 之类终止元数据，区分输出上限、上下文耗尽与 agent 步数/总 token 限制），覆盖率、超时、输出上限各列需要明确的分母；
• 推理模型运行需确认 reasoning 痕迹在打分前被正确剥离，且 use_reasoning: true 与模型类型匹配（推理模型开、instruct 模型关，见 example_eval.yaml 中 adapter_config 注释）；
• SLURM walltime 超时属于预期的续跑事件（NEL 通过依赖作业链从缓存续跑），不要一看到超时就判定运行失败。

对于基线 vs 量化模型对比，还需执行 External Baseline Sanity Check：在模型卡或 Artificial Analysis 上查找同一精确模型（同变体、同基准/版本/指标/推理模式/采样协议）的公开分数，双方换算到 0-100 后绝对差 ≈ 5 个百分点以内才视为通过验证；不匹配的分数不得视为可比。

与其他 AA 任务的取舍

ns_gpqa 常与 AA 套件中的其他任务合并成多任务配置（完整任务参考见 recipes/tasks/aa/），它们在配置形态与瓶颈特征上差异明显，合并前应逐个阅读对应参考：

任务	判分方式	关键配置差异	并行度特征
ns_gpqa（GPQA Diamond）	符号判分（symbolic_correct）	仅需 num_repeats + mcq-4choices 提示	短上下文，可用顶层默认
ns_ifbench	提示遵循宽松正确率（prompt_loose_accuracy）	仅需 num_repeats: 5	短上下文，模型瓶颈
ns_hle_aa（HLE）	judge 判分（judge_correct）	需配置 judge model_id/url/api_key，hle_strict_judge: true	judge 端点限流优先
ns_aa_lcr（AA-LCR）	judge 判分（equality checker）	部署需 --max-model-len 196608 以上；parallelism 必须设低于顶层	长上下文（~120K 输入），KV 受限 + judge 受限
ns_scicode	沙箱代码执行	需要多次提交取均值	沙箱槽位受限

要点：GPQA Diamond 是 AA 套件中唯一既无 judge 依赖又短上下文的符号判分任务，因此它最适合作为端到端验证量化模型部署正确性的“第一块试金石”——配置最简、无外部端点、指标口径固定。但需注意 AA 套件生成的聚合结果不包含 GDPVal，与官方公开的 AA Index（含 GDPVal）不可直接对比，应逐任务报告分数（SKILL.md）。

小结

GPQA Diamond 在 Model-Optimizer 评估体系中的接入路径非常清晰：以 gpqa_diamond.md 的任务参考为基准，在 example_eval.yaml 模板的 evaluation.tasks 列表中放置 ns_gpqa 任务块（num_repeats: 16 + AA 4-choice 提示），经 dry-run → canary → 全量三段门控运行，最终从 MLflow 提取 gpqa_pass_at_1_avg-of-16_symbolic_correct。在整个过程中，num_repeats 决定指标口径（avg-of-N 的 N）、符号判分决定其无需 judge 端点、短上下文决定其并行度可沿用顶层默认值——这三条特征共同构成了该任务“配置最简、最适合作为量化模型评估起点”的定位。