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）

检查清单

• model_path 存在且含 model_index.json（diffusers 布局）
• adapter_path 存在且 model_family 为 dit
• YAML apiversion: multimodal_sd_modelslim_v1
• YAML 显式写 spec.dataset（短名 hunyuanvideo / wan2_2_t2v / wan2_2_i2v / wan2_2_ti2v，或含 index.jsonl 的绝对路径）；不要省略（省略 → 默认 mix_calib.jsonl → 失败）
• 自建校准集时 index.jsonl 每行含非空 text；I2V 场景含 image 且相对路径可解析
• YAML dump_config.enable_dump: false（DiT data-free 不 dump 校准数据；true 仅在确需浮点推理 dump 时显式开启）
• YAML 顶层除 apiversion / metadata / spec 外无额外字段
• YAML act.scope 与 dtype 匹配: dtype=int8 → scope=per_token, dtype=mxfp8 → scope=per_block
• YAML weight.scope 与 dtype 匹配: dtype=int8 → scope=per_channel, dtype=mxfp8 → scope=per_block
• --device npu（不带卡号）；卡号通过 ASCEND_RT_VISIBLE_DEVICES 环境变量指定，优先使用单卡（如 ASCEND_RT_VISIBLE_DEVICES=0）
• save_path 为 {workdir}/round_1/quantized 形式且磁盘空间充足
• msmodelslim quant --help 可正常执行
• 未直接传 smooth / quarot / awq 等抑制策略参数；若需引入，由 orchestrator 直接调 quantization-expert-experience-tuning-rules/scripts/apply_rollback.py（整层回退）在 YAML 上叠加再回到本 skill 执行

参考

• 错误处理与上报格式
• W8A8 动态量化 YAML 示例（INT8）
• W8A8 MXFP8 量化 YAML 示例
• 校准数据 spec.dataset 说明
• index.jsonl 模板
• DiT 适配器模板
• 官方文档：多模态生成接入指南