eval-model

在 MAX 上评估模型的准确性

模型即使能正常提供服务，也可能答错基准测试问题。这项技能用于衡量 MAX 背后的文本模型在标准数据集上的回答准确性——GSM8K、MMLU、HellaSwag、ARC、AIME、GPQA、TruthfulQA、WinoGrande 和 BABILong。它会在每次运行前检查端点兼容性，区分服务故障和错误回答，并写出可复现的分任务得分，供你与模型卡进行比较。

在以下情况下使用此技能：你要对已部署的模型进行基准测试、将其与模型卡或参考得分进行比较、验证刚导入的 MAX 模型能否正确回答问题，或针对 MAX OpenAI 兼容端点运行可重复的数据集评估。

在以下情况下不要使用此技能：模型尚未提供服务。先启动模型（import-model）；如果模型已提供服务但生成的输出有误，请先使用 debug-model 排查差异，再进行基准测试。

参考资料

文件	阅读时机
references/examples.md	需要更多命令变体时——远程端点、工件路径、长上下文
references/fast-fail-thresholds.md	修改种子下限或添加种子任务之前
references/heartbeat-protocol.md	构建用于消费进度流的程序时

阅读与你正在做的事情相关的参考资料，不必一开始就全部阅读。

设置评估器

解析包含此 SKILL.md 的目录的绝对路径，并将其保存为 SKILL_DIR。以下每条命令都依赖它，因此请从技能的实际位置设置，而不是从用户的工作目录或下方的字面占位符设置。如果已提供技能路径，请直接将其导出；否则根据此文件的路径解析：

export SKILL_DIR="$(cd "$(dirname /path/to/eval-model/SKILL.md)" && pwd)"

继续之前，确认该路径指向清单文件，这样值不正确时会在此处失败，而不是在运行到一半时才失败：

test -f "$SKILL_DIR/pixi.toml" && echo "SKILL_DIR ok: $SKILL_DIR"

根据其 Pixi 清单安装评估器环境：

pixi install --manifest-path "$SKILL_DIR/pixi.toml"

此环境包含评估器自身的依赖项（lm-eval、datasets、transformers）。

某些数据集需要互联网访问、Hugging Face 身份验证或接受许可协议。如果数据集有此要求，请在运行前设置 HF_TOKEN。

提供模型服务

这些任务分为两组，提供模型服务的方式各不相同——请决定要运行哪组，或者按需启动服务以便两组都能运行：

• 生成任务（gsm8k、aime）根据生成的答案评分，使用正常启动的模型。
• 多项选择任务（mmlu、hellaswag、arc_easy、arc_challenge、winogrande、truthfulqa、gpqa）根据提示词的对数概率评分；只有在服务器启动时添加 --enable-echo，MAX 才会返回这些对数概率。

请在安装了 MAX 的环境中提供模型服务。

对于生成任务，正常启动模型：

max serve --model meta-llama/Llama-3.1-8B-Instruct

对于多项选择任务，添加 --enable-echo：

max serve \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --enable-echo

无法在运行中的服务上启用 echo。如果已有服务运行但未添加 --enable-echo，请先停止并重启服务，再评估多项选择任务——无法为正在运行的进程添加此功能。评估器的预检会进行权威检查：在下载数据集前验证提示词对数概率，并在这些概率不可用时报告配置错误。

如果模型的 generation_config.json 设置了非默认的 repetition_penalty（例如，Qwen2.5 系列默认使用 1.05），MAX 会自动启用其惩罚采样路径。该路径与 echo 的形状不兼容，会导致服务工作进程在启动时因 repetition_penalty 张量形状错误而崩溃。未设置 repetition_penalty 的模型（例如 Llama-3.1 和 Qwen3）不会触发此路径。如果遇到崩溃，请评估一个生成配置未设置 repetition_penalty 的模型，或将运行限制为生成任务（gsm8k、aime）。

运行评估

可从任意工作目录通过 Pixi 清单调用评估器：

pixi run --manifest-path "$SKILL_DIR/pixi.toml" eval \
  --model "meta-llama/Llama-3.1-8B-Instruct" \
  --tasks gsm8k

若要快速检查端点和评分，可调低两个限制并使用捆绑的评分器：

pixi run --manifest-path "$SKILL_DIR/pixi.toml" eval \
  --model "meta-llama/Llama-3.1-8B-Instruct" \
  --tasks gsm8k \
  --seed-limit 4 \
  --full-limit 8 \
  --direct-http

仅在此类连通性和解析检查中使用 --direct-http。它捆绑的评分器采用带自定义提示词的 0-shot，因此其分数远低于模型卡上的 few-shot 思维链分数——在一次测量中，同一模型在 direct seed 评分器下得分为 33%，在 lm-eval 完整评估中则为 82%。不要将 --direct-http 的结果与已发布的基准测试进行比较；比较模型卡时请去掉此标志，以运行默认的 lm-eval 评估。

对于使用别名服务模型的多项选择任务，请通过 --tokenizer 传入 Hugging Face 分词器 ID。这是必需项，而非可选项：lm-eval 需要真实的分词器来计算词元边界；若不提供，分词器会默认使用 --model，导致 lm-eval 尝试将别名作为 Hugging Face 仓库加载并失败。

pixi run --manifest-path "$SKILL_DIR/pixi.toml" eval \
  --model "my-served-alias" \
  --tokenizer "meta-llama/Llama-3.1-8B-Instruct" \
  --tasks mmlu,hellaswag

--model 的值必须与 /v1/models 返回的 ID 匹配。

--apply-chat-template 会将每个提示词包装进模型的聊天模板。是否使用取决于你的比较基准，而不仅仅是模型是否经过指令微调：

• 若要复现已发布的多项选择排行榜分数（MMLU、HellaSwag、ARC、WinoGrande），请保持关闭——这些参考分数是在原始补全提示词上测得的。添加此选项虽然可以运行，但所得分数无法与模型卡进行比较。
• 仅当你想测量模型实际聊天时的表现，并与使用聊天模板的基准进行比较时，才使用此选项。

解读结果

此命令使用以下退出代码：

• 0：所有任务均已完成，或所有显式指定的 --target 均已达到。
• 1：设置、依赖项、端点、数据集或 lm-eval 出错。
• 2：至少有一个显式指定的 --target 未达到。
• 3：直接 seed 任务的得分低于快速失败阈值。

未指定 --target 时，有效的完整运行状态为 completed；评估器不会设定与模型无关的准确率目标。completed 或 met 状态表示运行顺利完成——这本身并不代表模型正确或达到基准水平。若要将运行结果判定为通过或失败，或进行比较，请自行提供基准值。

与模型卡比较

评估器不了解任何模型的预期分数，因此实际比较需要几个明确步骤：

1. 在模型卡或参考资料中查找特定指标，并确保匹配此工具生成的变体——对于生成任务，这指 few-shot 思维链（例如，Llama-3.1-8B-Instruct 报告的 GSM8K 分数约为 84.5，采用 8-shot CoT）。记下样本数，以及是否使用了聊天模板。
2. 将该数值作为 --target 传入。请注意，--target 是单侧下限：只有准确率低于该值时，运行才会失败（退出代码 2），因此它用于设定门槛，而不是衡量双向偏差。
3. 从任务的摘要 JSON 中读取 accuracy，并报告与参考值的实际差异。考虑抽样噪声——默认完整运行对每项任务抽取 200 个样本（分组任务则对每个子任务抽取），而非使用完整测试集，因此应将小幅差异视为噪声，而非回退。需要更精确的估计时，可将 --full-limit 调高至接近完整数据集。

pixi run --manifest-path "$SKILL_DIR/pixi.toml" eval \
  --model "meta-llama/Llama-3.1-8B-Instruct" \
  --tasks gsm8k,mmlu \
  --target "gsm8k:0.84,mmlu:0.68"

摘要默认保存在 eval-results/<model-name>/：

eval-results/meta-llama_Llama-3.1-8B-Instruct/
├── eval_summary.json
├── gsm8k_summary.json
└── mmlu_summary.json

使用 --output-dir 选择其他位置，或使用 --run-id 仅更改默认目录标签。合并摘要会记录有效的 CLI 配置及评估器依赖项版本，以便解读运行结果。

选择任务

任务行为如下：

• gsm8k 和 aime：先进行 Direct-HTTP 种子检查，然后通过 lm-eval 完整运行。 添加 --direct-http，以便在完整运行中使用捆绑的精确匹配评分器。
• mmlu、hellaswag、arc_easy、arc_challenge、winogrande 和 truthfulqa：通过 /v1/completions 进行 lm-eval 完整运行；需要 --enable-echo。
• gpqa：通过 /v1/completions 进行 lm-eval 多选题运行；需要 --enable-echo，且数据集可能需要访问 Hugging Face。
• babilong：进行 lm-eval 聊天运行；默认使用 {"max_seq_lengths": "16k"} 元数据。

每次完整运行默认抽取 200 个样本（对于 mmlu 等分组任务，每个子任务抽取 200 个；gpqa 和 babilong 默认抽取 100 个）。这只是抽样检查，并非完整测试集——需要更精确的估算时，请提高 --full-limit，并注意默认样本量下不同运行结果可能略有差异。对于分组任务，摘要会报告有效子样本总数。

只有生成任务（gsm8k、aime）会运行直接种子检查；多选题任务会直接进行完整运行，因此 mmlu 等任务不显示种子准确率是正常的。种子检查的快速失败下限是一个管道检查关卡——它用于捕获不可用的端点、格式错误的请求或损坏的答案提取，而不是衡量模型质量的正常波动。要评估质量，请使用 --target（参见“与模型卡比较”），而不是快速失败下限。

未注册 ChartQA，因为 lm-eval 自带的 ChartQA 提示词格式与 MAX 图像令牌注入不兼容。启用前，请添加经过验证的 MAX 专用任务配置。

无需安装 MAX 或启动服务，即可打印生效的任务配置：

pixi run --manifest-path "$SKILL_DIR/pixi.toml" validate

评估推理模型

对于聊天模板接受 reasoning_effort 的 MAX 模型，请传入以下值之一： low、medium、high 或 xhigh：

pixi run --manifest-path "$SKILL_DIR/pixi.toml" eval \
  --model "<MODEL_ID>" \
  --tasks gsm8k,aime \
  --reasoning-effort low

评估器会通过 chat_template_kwargs={"reasoning_effort": ...} 发送此值，并自动为受支持的生成任务选择直接 HTTP 完整评分器。如果端点不接受该字段，预检请求会明确报错。

监控进度

心跳记录会输出到 stdout；人类可读的日志会输出到 stderr。若要归档，请分别将两个流写入各自的文件：

pixi run --manifest-path "$SKILL_DIR/pixi.toml" eval \
  --model "<MODEL_ID>" \
  --tasks gsm8k \
  > heartbeats.jsonl \
  2> eval.log

若要在运行过程中监控活动状态，请将 stdout 保持为管道，而不是普通文件，这样使用方就能在心跳到达时读取它们——心跳参考中的示例使用方无法单独跟踪文件重定向：

pixi run --manifest-path "$SKILL_DIR/pixi.toml" eval \
  --model "<MODEL_ID>" --tasks gsm8k \
  2> eval.log | tee heartbeats.jsonl | python your_consumer.py

如果连续两倍于 --heartbeat-interval 的时间没有收到心跳，请将其视为可能发生了停滞。对于推理模型，单次生成超过默认的 30 秒间隔完全可能，因此请提高 --heartbeat-interval（停滞阈值也会随之提高），以免将运行缓慢但正常的任务误报为异常。评估器只有在写入相应的任务摘要后才会发出 done。

排查故障

请进行以下检查：

• 连接或模型错误：运行 curl http://localhost:8000/v1/models，并 传入准确的返回模型 ID。
• 缺少提示词 logprobs：使用 --enable-echo 重启 MAX（无法在运行中的服务上 启用）；确认所选运行时支持对数概率。
• 服务工作进程在启动时崩溃，并出现 echo 和 repetition_penalty 张量形状错误：所服务模型的 generation_config.json 设置了非默认的 repetition_penalty（Qwen2.5 中很常见），因此 MAX 会自动启用 echo 不支持的惩罚路径。对于多选任务，请使用生成配置中未设置 repetition_penalty 的模型（Llama-3.1、Qwen3）， 或将运行限制为生成任务（gsm8k、aime）。
• max serve 报错 No module named 'pydantic'：服务环境中安装的是精简版 max 包，而非 max-pipelines。请安装 max-pipelines。
• 缺少软件包：再次运行 pixi install --manifest-path "$SKILL_DIR/pixi.toml"。
• 数据集访问错误：使用 Hugging Face 进行身份验证，并接受数据集条款。
• lm-eval 任务错误：使用以下命令列出已安装 lm-eval 版本的任务： pixi run --manifest-path "$SKILL_DIR/pixi.toml" lm-eval ls tasks，然后使用以下命令打印 生效的任务配置： pixi run --manifest-path "$SKILL_DIR/pixi.toml" validate（validate 任务 会运行脚本的 --validate-thresholds 模式）。
• 内存不足或上下文长度错误：酌情调低 --num-concurrent、 --full-limit，或模型服务的上下文长度。