在 MAX 服务模型后，用标准基准评测文本模型准确率并与模型…

当需要测量 MAX 服务的文本模型在 GSM8K、MMLU、HellaSwag 等标准数据集上的任务准确率，并生成可复现的 per-task 分数以与参考分数比较时使用。

适用场景

解决思路

1. 解析包含此 SKILL.md 的目录的绝对路径并保存为 `SKILL_DIR`；从技能真实位置设置，而不是用户工作目录或字面占位符；若已知技能路径直接导出，否则用 `export SKILL_DIR="$(cd "$(dirname /path/to/eval-model/SKILL.md)" && pwd)"`。
2. 验证 `SKILL_DIR` 指向 manifest：运行 `test -f "$SKILL_DIR/pixi.toml" && echo "SKILL_DIR ok: $SKILL_DIR"`。
3. 安装评估器环境：运行 `pixi install --manifest-path "$SKILL_DIR/pixi.toml"`；该环境包含评估器自己的依赖（lm-eval、datasets、transformers）。
4. 当数据集需要互联网访问、Hugging Face 认证或接受许可证时，在运行前设置 `HF_TOKEN`。
5. 确定要运行生成任务还是多选题，或者服务模型以便两者都能运行；生成任务正常服务模型，多选题需要 `--enable-echo`。
6. 对于生成任务，正常启动模型：`max serve --model meta-llama/Llama-3.1-8B-Instruct`。
7. 对于多选题，启动模型时加 `--enable-echo`：`max serve --model meta-llama/Llama-3.1-8B-Instruct --enable-echo`。
8. 不能在运行中的服务器上切换 echo；如果已有服务器在运行但没有 `--enable-echo`，评估多选题前停止并重启它。
9. 如果模型的 `generation_config.json` 设置了非默认 `repetition_penalty`（例如 Qwen2.5 系列为 1.05），MAX 会自动启用与 echo 形状不兼容的 penalty sampling 路径，并在启动时因 `repetition_penalty` tensor-shape 错误使服务 worker 崩溃；遇到时改用 `repetition_penalty` 未设置的模型（如 Llama-3.1、Qwen3）做多选题，或只运行生成任务 `gsm8k`、`aime`。
10. 运行评估：通过 Pixi manifest 从任意目录调用 `pixi run --manifest-path "$SKILL_DIR/pixi.toml" eval --model "meta-llama/Llama-3.1-8B-Instruct" --tasks gsm8k`。
11. 快速检查端点与评分：降低限制并使用 `--direct-http`，例如 `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`。
12. 仅将 `--direct-http` 用于连接和解析检查；其捆绑 scorer 是 0-shot 且带自定义 prompt，数字远低于模型卡上的 few-shot chain-of-thought 分数；不要将 `--direct-http` 结果与已发布基准比较，卡片比较时去掉该标志以运行默认 lm-eval pass。
13. 对于别名服务模型上的多选题，必须用 `--tokenizer` 传递 Hugging Face tokenizer ID，例如 `pixi run --manifest-path "$SKILL_DIR/pixi.toml" eval --model "my-served-alias" --tokenizer "meta-llama/Llama-3.1-8B-Instruct" --tasks mmlu,hellaswag`；否则 lm-eval 会尝试将别名作为 Hugging Face repo 加载而失败。
14. 确保 `--model` 值匹配 `/v1/models` 返回的 ID。
15. 根据比较基线决定 `--apply-chat-template`：要复现已发布的多选题排行榜分数（MMLU、HellaSwag、ARC、WinoGrande），将其关闭；仅当打算测量模型实际聊天表现并与聊天模板基线比较时才使用。
16. 解释退出码：`0` 所有任务完成或每个显式 `--target` 都满足；`1` 设置、依赖、端点、数据集或 lm-eval 失败；`2` 至少一个显式 `--target` 未命中；`3` 一个 direct seed task 得分低于其 fast-fail floor。
17. 没有 `--target` 时，有效的完整运行状态为 `completed`；它只表示运行干净完成，不表示模型正确或同级；要变成通过/失败或比较，需要自己提供基线。
18. 与模型卡对比时，先查找模型卡或参考上匹配此工具产生变体的特定指标——对于生成任务，是 few-shot chain-of-thought（例如 Llama-3.1-8B-Instruct 报告 GSM8K 约 84.5，8-shot CoT）；记录 shot 数和是否使用了聊天模板。
19. 将该数字作为 `--target` 传递；注意 `--target` 是单侧下限，运行仅在准确度低于它时失败（退出 `2`），所以它起门控作用而非测量双侧差异。
20. 从任务摘要 JSON 读取 `accuracy`，报告与参考的实际差异；默认完整运行是每个任务 200 个样本（分组任务则每个子任务），视为抽查，小差距当噪声而非回归；需要更紧估计时提高 `--full-limit` 接近完整数据集。
21. 使用 `--target` 的示例：`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"`。
22. 摘要默认到 `eval-results/<model-name>/`，包含 `eval_summary.json`、`<task>_summary.json`；用 `--output-dir` 选择另一个位置，或用 `--run-id` 只更改默认目录标签；组合摘要记录解释运行所需的有效 CLI 配置和评估器依赖版本。
23. 任务行为：`gsm8k` 和 `aime` 运行 direct-HTTP seed 检查，然后 lm-eval full 运行；添加 `--direct-http` 可使用捆绑的 exact-match scorer 进行完整运行。
24. `mmlu`、`hellaswag`、`arc_easy`、`arc_challenge`、`winogrande` 和 `truthfulqa` 通过 `/v1/completions` 进行 lm-eval full 运行，需要 `--enable-echo`。
25. `gpqa` 通过 `/v1/completions` 进行 lm-eval 多选题运行，需要 `--enable-echo`，数据集可能需要 Hugging Face 访问。
26. `babilong` 进行 lm-eval chat 运行，默认 `{"max_seq_lengths": "16k"}` 元数据。
27. 每个 full 运行默认 200 个样本（分组任务如 `mmlu` 每个子任务 200；`gpqa` 和 `babilong` 默认 100）；这是抽查，不是整个测试集；需要更紧估计时提高 `--full-limit`，并预期默认大小下有小运行间变化。
28. 只有生成任务 `gsm8k`、`aime` 运行 direct seed pass；多选题跳过直接进入 full 运行，因此看到 `mmlu` 等没有 seed accuracy 是预期；seed 的 fast-fail floor 是管道门，捕获不可用端点、格式错误请求或损坏答案提取，不是正常模型质量变化；判断质量用 `--target`。
29. ChartQA 未注册，因为 stock lm-eval ChartQA prompt 格式与 MAX 图像 token 注入不兼容；启用前添加验证过的 MAX 特定任务配置。
30. 不安装 MAX 或启动服务器即可打印有效任务配置：`pixi run --manifest-path "$SKILL_DIR/pixi.toml" validate`。
31. 评估推理模型时，对于 chat 模板接受 `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`。
32. 评估器通过 `chat_template_kwargs={"reasoning_effort": ...}` 发送该值，并自动为支持的生成任务选择 direct-HTTP full scorer；如果端点不接受该字段，preflight 请求会明确失败。
33. 监控进度时，heartbeat 记录到 stdout，人类可读日志到 stderr；要归档，将每个流捕获到自己的文件，例如 `pixi run --manifest-path "$SKILL_DIR/pixi.toml" eval --model "<MODEL_ID>" --tasks gsm8k > heartbeats.jsonl 2> eval.log`。
34. 要在运行过程中观察存活，保持 stdout 在管道上，以便消费者在 heartbeat 到达时读取，例如 `pixi run --manifest-path "$SKILL_DIR/pixi.toml" eval --model "<MODEL_ID>" --tasks gsm8k 2> eval.log | tee heartbeats.jsonl | python your_consumer.py`。
35. 将缺少 heartbeat 超过 `--heartbeat-interval` 的两倍视为可能停滞；对于推理模型，单个生成可能合法超过默认 30 秒间隔，因此提高 `--heartbeat-interval` 和停滞阈值以避免慢但健康运行的误报。
36. 评估器仅在写入相应任务摘要后发出 `done`。
37. 故障排除连接或模型错误：运行 `curl http://localhost:8000/v1/models` 并传递一个精确返回的模型 ID。
38. 故障排除缺少 prompt logprobs：用 `--enable-echo` 重启 MAX（不能在运行中的服务器上启用）；确认所选运行时支持 log probabilities。
39. 故障排除服务 worker 在启动时崩溃并伴随 echo 和 `repetition_penalty` tensor-shape 错误：所服务模型的 `generation_config.json` 设置了非默认 `repetition_penalty`（Qwen2.5 中常见），MAX 自动启用 echo 不支持的 penalty 路径；对策同前：使用 generation config 未设置 `repetition_penalty` 的模型（Llama-3.1、Qwen3），或将运行限制为生成任务 `gsm8k`、`aime`。
40. 故障排除 `max serve` 出现 `No module named 'pydantic'`：服务环境有 slim `max` 包但没有 `max-pipelines`；安装 `max-pipelines`。
41. 故障排除缺少包：再次运行 `pixi install --manifest-path "$SKILL_DIR/pixi.toml"`。
42. 故障排除数据集访问错误：使用 Hugging Face 认证并接受数据集条款。
43. 故障排除 lm-eval 任务错误：用 `pixi run --manifest-path "$SKILL_DIR/pixi.toml" lm-eval ls tasks` 列出已安装 lm-eval 版本的任务，然后用 `pixi run --manifest-path "$SKILL_DIR/pixi.toml" validate` 打印有效任务配置。
44. 故障排除内存不足或上下文长度错误：适当减少 `--num-concurrent`、`--full-limit` 或模型的服务上下文长度。
45. 参考文件使用：需要更多命令变体时读 `references/examples.md`；在更改 seed floors 或添加 seed task 前读 `references/fast-fail-thresholds.md`；构建消费进度流的程序时读 `references/heartbeat-protocol.md`；读你正在做的参考，不要全部预先读。

适用边界 · 注意事项

• 模型还不能服务时不要用；先通过 import-model 把模型跑起来。
• 模型能服务但生成错误输出时，先用 debug-model 追查分歧，再考虑基准评测。