Skill: DiT 量化（W8A8 动态 / MXFP8）
解决什么
依据 Practice YAML（apiversion: multimodal_sd_modelslim_v1），调用 msmodelslim quant 对 DiT 模型执行 W8A8 动态（data-free） 或 W8A8 MXFP8（data-free） 量化；走 MultimodalPipelineInterface 重构路径。
不解决什么
- 本 skill 不做敏感层分析 / 摸高 / 二分：那些能力由
msmodelslim-model-adapt（DiT 扩展节）+ 经验库 L2 §7 + 直接调 apply_rollback.py 接力；本 skill 只负责按最终 Practice YAML 执行量化
- 本 skill 不消费抑制策略参数：本阶段不直接接受
smooth / quarot / iter_smooth / flex_smooth_quant / awq 等；如需引入，由下游 practice 子能力补齐 YAML 字段后再回到本 skill 重新执行
- 不替代 LLM 量化路径：本 skill 仅服务
model_family ∈ dit
spec.dataset（校准集短名；enable_dump: false 时不参与 dump，仅作回退/复现用）不在此列 —— 它是必填项，见「校准数据 spec.dataset」。
协作关系
quantization-accuracy-tuning-orchestrator (workflow)
│ 按 model_family 路由到 dit 分支
▼ 调用
quant-tuning-quantize-dit (tool)
│
▼ MultimodalSDModelslimV1QuantService
MultimodalPipelineInterface（重构路径）
│
▼ CLI
msmodelslim quant
│
▼ 输出（MindIE-SD 格式）
{workdir}/round_1/quantized/
输入参数
| 参数 | 类型 | 必填 | 说明 |
|---|
model_path | string | ✅ | 原始 DiT 权重目录（diffusers 标准布局） |
adapter_path | string | ✅ | DiT 适配器 .py（来自 msmodelslim-model-adapt 的 DiT 扩展节） |
output_dir | string | ✅ | 量化产物保存路径；推荐 {workdir}/round_1/quantized/ |
model_type | string | ✅ | msModelSlim 注册名（如 HunyuanVideo、Wan2.2-T2V-A14B、Wan2.2-I2V-A14B、Sana）；先前以 flux1 / wan2_1 注册的 model_type 在本项目中按重构路径对待 |
device | string | ✅ | 设备类型；必须传 npu（不要传 npu:0 / npu:x 等带卡号的形式）；具体卡号通过环境变量 ASCEND_RT_VISIBLE_DEVICES 指定，例如 export ASCEND_RT_VISIBLE_DEVICES=0 |
trust_remote_code | bool | | 默认 true |
inference_repo | string | | 推理仓路径（若 adapter 需要注入 sys.path）；需确保该路径已加入 PYTHONPATH，e.g. export PYTHONPATH=/path/to/hunyuan_video:$PYTHONPATH |
calib_dataset | string | | 写入 YAML spec.dataset 的短名或路径；默认按 model_type 取 lab_calib 现成 prompt 集（见「校准数据 spec.dataset」） |
本阶段不直接消费：smooth、quarot、iter_smooth、flex_smooth_quant、awq、kv_quant 等抑制策略参数。这些策略的字段变更由 orchestrator 直接调 quantization-expert-experience-tuning-rules/scripts/apply_rollback.py（整层回退）在 YAML 上叠加 exclude 后再回到本 skill 执行量化。
CLI 调用
方式一：使用 Practice YAML（推荐）
ASCEND_RT_VISIBLE_DEVICES=0 msmodelslim quant \
--model_path "${MODEL_PATH}" \
--config_path "${WORKDIR}/practice.yaml" \
--save_path "${OUTPUT_DIR}" \
--device npu \
--model_type "${MODEL_TYPE}" \
--trust_remote_code True
--device 仅接受字面量 npu；不要传 npu:0 / npu:x 等带卡号的形式。卡号一律通过 ASCEND_RT_VISIBLE_DEVICES 环境变量指定（如 ASCEND_RT_VISIBLE_DEVICES=0,1 多卡）。
YAML apiversion 固定为 multimodal_sd_modelslim_v1，模板见 assets/w8a8_dynamic.example.yaml。
量化方案由 Practice YAML（--config_path）给定，不使用 --quant_type（与非 DIT 的 quant-tuning-quantize 口径一致：--config_path 与 --quant_type 互斥）。
量化方案细节
- 权重：per-channel INT8 / per-block MXFP8
- 激活：动态量化 per-token INT8 / per-block MXFP8
- 不引入外部激活校准数据：data-free 指不引入激活校准集；
spec.dataset 仍必须显式写（省略会落到默认 mix_calib.jsonl 并失败；enable_dump: false 时该集不参与 dump，仅作回退/复现用）
- dynamic 量化需
enable_dump: false：DiT data-free 路径不 dump 校准数据，enable_dump: false 短路 prepare_calib_data、避免无谓浮点推理；true 仅在确需浮点推理 dump 校准数据时显式开启（见 msmodelslim-adapter-verification/references/dit/README.md 硬约束 #2）
- 不直接消费抑制策略：
smooth / quarot / iter_smooth / flex_smooth_quant / awq 等字段不在本 skill CLI 暴露；如需引入，由 orchestrator 直接调 quantization-expert-experience-tuning-rules/scripts/apply_rollback.py（整层回退）在 YAML 上补齐 spec.process / spec.algorithm_config 后再回到本 skill 重新执行
对称 / 非对称：模板已显式固化 symmetric: true（minmax）；如需非对称，先确认 msmodelslim 默认值再修改模板。
校准数据 spec.dataset（必填）
MultimodalSDServiceConfig.dataset 的 Pydantic 默认值是 mix_calib.jsonl —— LLM 文本校准集，每条只有 inputs_pretokenized、无 text，会在 handle_dataset → validate_calib_samples 处 fail-fast（Provide text in dataset entries）。省略 dataset 不等于 data-free，只是静默落到一个错误的默认值。
短名在 msmodelslim/lab_calib/ 下解析，现成 prompt 集：
| 短名 | 场景 | 内容 |
|---|
hunyuanvideo | HunyuanVideo | text |
wan2_2_t2v | Wan2.2-T2V-A14B | text |
wan2_2_i2v | Wan2.2-I2V-A14B | text + image（i2v_input.JPG） |
wan2_2_ti2v | Wan2.2-TI2V-5B | text |
自建校准集：目录内放一个 index.jsonl，每行一个 JSON 对象、至少含非空 text；I2V 等场景追加 image（相对 index.jsonl 所在目录）。模板见 assets/index.example.jsonl，完整说明见 assets/calib_dataset.md。
spec:
dataset: wan2_2_t2v # 或 /abs/path/to/my_calib/index.jsonl
YAML 模板要点
spec.multimodal_sd_config 使用 inference_config（Pydantic 校验，与原推理仓 CLI 对齐）：
| 字段 | 值 |
|---|
dump_config.enable_dump | false（DiT data-free 不 dump 校准数据，短路 prepare_calib_data；勿设 true 触发无谓浮点推理） |
dump_config.capture_mode | "args" |
dump_config.dump_data_dir | ""（留空 → 默认 save_path） |
inference_config | Pydantic BaseModel 子类字段（字段名必须与目标推理仓 parse_args argparse key 一一对应） |
关键约束：
- dynamic 量化需
enable_dump: false：DiT data-free 路径不 dump 校准数据，短路 prepare_calib_data、避免无谓浮点推理；true 仅在确需浮点推理 dump 校准数据时显式开启（详见 msmodelslim-adapter-verification/references/dit/README.md 硬约束 #2）。
- 必须显式写
spec.dataset（短名 / 绝对路径），省略会落到默认 mix_calib.jsonl 并失败，见上节。
spec.process 本阶段仅触发 linear_quant；spec.save 默认 mindie_format_saver。- YAML 顶层除
apiversion / metadata / spec 外禁止额外字段：model_family / inference_repo 通过 subagent_io 协议字段传递，不写入量化 YAML。
- INT8 动态量化推荐
act.scope: "per_token" / weight.scope: "per_channel"；不要用 per_block（那是 mxfp8 配置）。
inference_config 字段名按目标 DiT 推理仓的 argparse 命名差异较大：详见 inference_config_field_map.md（统一字段表 + 默认值 + 入口脚本 + 定位方法）。
- 推理入口脚本名因仓而异（Wan 系
generate.py、FLUX inference_flux.py、HunyuanVideo sample_video.py）；定位方法：在 inference_repo 的 README.md 找推理示例命令，再到 <repo>/config.py / <repo>/hyvideo/config.py 找 parse_args 的 --<key> 列表
- 模板见
assets/w8a8_dynamic.example.yaml（以 HunyuanVideo 为参考）。
save_path 命名
- 与 LLM 路径一致：
{workdir}/round_{N}/quantized（N 为调优轮次，DiT 阶段通常固定为 1）
- 权重目录为 MindIE-SD 格式（与 LLM/VLM 不同），可被
msmodelslim CLI 正常加载（save/load round-trip）
输出结果
成功
{
"protocol": "msagent.subagent_io",
"subagent_type": "quant-tuning-quantize-dit",
"status": "ok",
"output": {
"success": true,
"quantized_path": "<workdir>/round_1/quantized",
"save_format": "mindie_format_saver",
"apiversion": "multimodal_sd_modelslim_v1",
"exit_code": 0,
"duration_sec": 123.4,
"round_trip_check": "passed",
"commands": [
{
"name": "quantize",
"command": "msmodelslim quant --model_path ... --config_path ... --model_type HunyuanVideo ..."
},
{
"name": "round_trip_check",
"command": "msmodelslim quant --model_path <quantized_path> --config_path <practice.yaml> --save_path /tmp/rt_check"
}
]
}
}
失败
立即中止，回传：
{
"protocol": "msagent.subagent_io",
"subagent_type": "quant-tuning-quantize-dit",
"status": "failed",
"error": {
"code": "QUANTIZE_ERROR",
"message": "msmodelslim quant 执行失败摘要",
"suggestion": "报 stderr 摘要，等待 orchestrator 决策"
}
}
不续跑其它命令，不伪造输出。
失败信封格式与 subagent_io_protocol.md 一致（error.code + error.message）；code 枚举、各场景的 suggestion 及处理原则见 references/error_handling.md。
错误处理
| 错误现象 | error.code | 处理 |
|---|
| msmodelslim 未安装 / PYTHONPATH 未设置 | ENV_ERROR | 按 quantization-accuracy-tuning-orchestrator/references/prepare_environment.md 安装后重试 |
model_path / adapter_path / inference_repo 不存在或未加入 PYTHONPATH | PATH_ERROR | 检查路径 / export PYTHONPATH=... 后重试或中止 |
误传 --quant_type 或 --quant_type 值非法；YAML apiversion 不是 multimodal_sd_modelslim_v1 | CONFIG_ERROR | 立即中止（防止误用其它方案 / LLM·VLM YAML），不重试 |
Adapter not registered: <model_type> | ADAPTER_ERROR | 见 msmodelslim-model-adapt/references/registration_guide.md |
Round-trip failed: shape mismatch | ADAPTER_ERROR | 检查 handle_dataset 输出字段是否对齐 forward |
out of memory | OOM_ERROR | 换设备或减小输入尺寸 |
Provide text in dataset entries（漏写 spec.dataset 落到默认 mix_calib.jsonl） | DATASET_ERROR | YAML 显式写 spec.dataset（如 wan2_2_t2v） |
calib_data missing for expert 'low_noise_model' | EXPERT_CONFIG_ERROR | 检查 init_model 返回 dict 与 prepare_calib_data；立即中止 |
| 量化命令非零退出 | QUANTIZE_ERROR | 报 stderr 摘要，等待 orchestrator 决策 |
| round-trip 校验失败 | ROUND_TRIP_ERROR | 报 stderr 摘要，标记 round_trip_check: failed，回传失败 |
各 code 的典型场景、suggestion 与处理原则详见 references/error_handling.md。未命中本表或多次解决仍失败时，按失败信封（code + message + suggestion）回传 orchestrator。
磁盘管理
- 量化产物写入
output_dir
- 由 orchestrator 管理磁盘空间（最多保留 2 份权重）
- 本 skill 不主动清理历史产物
约束
- 错误即停：命令失败后立即中止，不兜底续跑
- 单轮单次：每次调用只执行一次量化
- YAML
apiversion 固定 multimodal_sd_modelslim_v1
- 量化方案由 YAML 给定：Practice YAML 模板即动态配置；
--config_path 与 --quant_type 互斥，不使用 --quant_type
- save_path 命名：每轮使用
{workdir}/round_{N}/quantized
- device：
--device 仅接受字面量 npu（不要传 npu:0 / npu:x）；卡号一律通过 ASCEND_RT_VISIBLE_DEVICES 环境变量指定，优先使用单卡（如 export ASCEND_RT_VISIBLE_DEVICES=0）
检查清单
参考