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

---

检查清单

• config_path 指向的 Evaluation YAML 格式正确
• device 与 device_indices 匹配
• YAML 中的 ASCEND_RT_VISIBLE_DEVICES 与 device_indices 一致
• device_indices 长度与 tensor-parallel-size 对齐
• 目标端口未被占用
• NPU/GPU 设备可用
• msmodelslim 已安装
• 成功结果可被标准 json.dumps() 序列化，并可由 EvaluateResult.model_validate() 重新读取