Skill: Quant Tuning Evaluate
Overview
解决什么：依据 Evaluation YAML 配置，通过 scripts/run_evaluation.py 对量化模型进行评测。
不解决什么：
- 不生成/修改 Evaluation YAML → 见
quant-tuning-evaluation-generator Agent
- 不执行量化 → 见
quant-tuning-quantizer Agent
- 不做策略决策 → 见
quantization-accuracy-tuning-orchestrator Skill
执行主体：scripts/run_evaluation.py（LLM/VLM 主流程；DiT 路径执行主体为 references/dit/evaluate_workflow.md §3 bash 模板）
按 model_family 分发
orchestrator 委派本 skill 时按分析结论的 model_family 分发：
llm / vlm_text：走本文主流程（Evaluation YAML + run_evaluation.py 服务化评测，产出结构化分数）dit：不进入主流程，走 DiT 扩展节 → references/dit/evaluate_workflow.md（读推理仓 README 拼 vbench.py argv，批量推理产出视频 + run_manifest.json，不评分；评分由 quant-tuning-score-dit 接力）
协作关系
quantization-accuracy-tuning-orchestrator (workflow)
│
▼ 调用
quant-tuning-evaluate (tool)
│
▼ Script
run_evaluation.py
│
▼ 输出
评测结果 (精度分数)
执行步骤
┌─────────────────┐
│ 输入检查 │
│ - config_path │
│ (Evaluation YAML)│
└────────┬────────┘
▼
┌─────────────────┐
│ 服务启动检查 │
│ - 检查 vLLM │
│ 是否就绪 │
└────────┬────────┘
▼
┌─────────────────┐
│ execute: │
│ run_evaluation │
│ .py │
│ (启动推理服务 │
│ + 执行评测) │
└────────┬────────┘
▼
┌─────────────────┐
│ 结果处理 │
│ - 解析精度分数 │
│ - 检查是否达标 │
│ - 错误上报 │
└─────────────────┘
输入参数
| 参数 | 类型 | 必需 | 说明 |
|---|
quant_model_path | string | ✅ | 量化后模型路径 |
evaluate_id | string | ✅ | 本轮评测 ID |
evaluate_config_path | string | ✅ | Evaluation YAML 路径（编排层常称 config_path） |
save_path | string | ✅ | 评测工作目录 |
device | string | ❌ | 设备类型，默认 npu |
device_indices | list[int] | ❌ | 设备索引列表，如 [0,1] |
脚本调用
python skills/quantizer/quant-tuning-evaluate/scripts/run_evaluation.py \
--quant-model-path /path/to/quantized \
--evaluate-id eval-round-1 \
--evaluate-config-path /path/to/evaluate.yaml \
--save-path /path/to/workdir \
--device npu \
--device-indices 0,1
错误处理
| 错误类型 | 处理 |
|---|
| msmodelslim 未安装 | 按 prepare_environment.md 安装 |
| 推理服务启动失败 | 检查端口占用、设备可用性 |
| 评测超时 | 检查 aisbench.timeout 配置 |
| 精度不达标 | 正常返回结果，由 orchestrator 决策 |
输出结果
成功
{
"ok": true,
"results": {
"gsm8k": {
"score": 83.5,
"target": 83.0,
"passed": true
},
"aime25": {
"score": 52.0,
"target": 50.0,
"passed": true
}
},
"overall_passed": true,
"duration": 1800.5
}
失败
{
"ok": false,
"error": "推理服务启动失败",
"error_code": "INFERENCE_ERROR",
"partial_results": {}
}
执行流程
1. 服务启动
调用 scripts/run_evaluation.py（execute）
2. 结果解析
返回每个数据集的分数：
| 字段 | 说明 |
|---|
score | 实际精度（百分比） |
target | 目标精度 |
passed | 是否达标（score >= target - tolerance） |
overall_passed | 所有数据集是否都达标 |
run_evaluation.py 必须在调用公共 emit_result() 前使用 Pydantic JSON 模式序列化 EvaluateResult。禁止直接返回 model_dump() 的 Python 模式结果，因为其中的 Decimal（如 accuracy、target、tolerance）无法由标准 json.dumps() 序列化。JSON 模式会将十进制值无损转换为字符串；下游通过 EvaluateResult.model_validate() 读取时会恢复为 Decimal。
执行示例
标准调用
python skills/quantizer/quant-tuning-evaluate/scripts/run_evaluation.py \
--quant-model-path /workspace/output/round_1/quantized \
--evaluate-id round-1 \
--evaluate-config-path /workspace/output/evaluate.yaml \
--save-path /workspace/output \
--device npu \
--device-indices 0,1
结果返回给 orchestrator
评测完成:
- gsm8k: 83.5% (目标: 83.0%) ✅
- aime25: 52.0% (目标: 50.0%) ✅
- 总体: 达标
- 耗时: 1800.5s
约束
- Script-only：禁止用裸 CLI 替代
run_evaluation.py
- 路径格式：必须是 JSON 字符串
- 单轮单次：每次调用只执行一次完整评测
- 禁止派生或修改评测配置：只能按编排层给定的
evaluate_config_path 执行评测，不得自行派生、修改或生成新的 Evaluation YAML。子集不达标时 fast-fail 跳过后序数据集属正常行为，按原样回传结果，由编排层决策后续流程。评测配置仅由编排层 evaluation-generator 生成。
- 服务生命周期：由脚本内部评测服务管理。如果你需要测多个数据集，请你在测完所有数据集后再关闭服务化，避免重复多次拉起。服务化测评运行时长可能较长，超过 timeout 3600s，务必避免在测评的中途关闭服务化和测评，你应该等待测评完成，必要时可以通过看日志（如vllm_server.log）最新的消息时间来确认测评任务是否还活跃。
常见错误
| 错误 | 原因 | 解决 |
|---|
port already in use | 端口被占用 | 更换端口或等待释放 |
HCCL init failed | NPU 通信失败 | 检查 device_indices 和设备状态 |
evaluate.yaml not found | 配置文件不存在 | 检查 config_path |
out of memory | 设备内存不足 | 换设备 |
Object of type Decimal is not JSON serializable | 使用了 Python 模式 model_dump() | 改用 model_dump(mode="json")，且不得重新执行已完成的评测 |
若错误不在上述常见错误中或者多次解决后依然未解决，依据错误上报，按照错误上报格式返回至quant-tuning-evaluator Agent
检查清单