msModelSlim 适配器功能性验证 Skill

用于在基础适配器开发完成后，自动帮助用户进行功能性验证。

触发条件

• msmodelslim-model-adapt 已完成适配器开发与注册安装。
• 用户希望确认适配器是否可用，或要求执行标准验证流程。

执行要求

• 必须按顺序执行四步验证，不可跳步。
• 每一步失败都要立即停止并返回失败原因与下一步修复建议。
• 仅当四步全部通过时，返回“功能性验证通过”。
• 修改代码后要执行 bash install.sh 重新安装msModelslim
• NPU 卡号选择（仅 DiT 适用）：执行任何 NPU 步骤前必须先 export ASCEND_RT_VISIBLE_DEVICES=<物理卡号>（如 export ASCEND_RT_VISIBLE_DEVICES=0；不设置时 CANN 默认用 0 号卡且不报错）。--device 仅接受字面量 npu / cpu（不要传 npu:0 / npu:x）。完整说明见 references/verification_guide.md 的"设备与卡号选择"小节。
• 若验证过程中出现模型实现文件（如权重目录内 modeling_*.py）报错，必须先判断是否为 transformers 版本不契合导致。
• 对疑似版本不契合问题，必须先告知用户并确认版本需求（目标版本或可接受版本区间）；未确认前不得切换版本。
• 仅在用户确认后，才可执行 transformers 版本切换与重试验证。

四步验证流程

1. Step1：生成随机权重测试模型。
2. Step2：执行全回退量化，验证流程与注册生效。DiT 先 export ASCEND_RT_VISIBLE_DEVICES=<物理卡号>，再传 --device npu + --inference-repo，配置模板见 references/dit/。
3. Step3：验证 Step2 与 Step1 的权重严格一致，且产物可完整加载/保存。
4. Step4：执行实际量化（W8A8 静态/动态）并校验描述文件规则。

模型族与 Step1 随机权重

族	是否推荐随机权重	备注
LLM	推荐	transformers.AutoModel* 提供统一入口，2 层小模型便宜
VLM	推荐	同上，走 AutoModelForImageTextToText
DiT	不推荐	各厂商 inference repo 加载范式分裂（diffusers / 自定义 class / MoE 子目录），无统一随机权重工厂。请用 step1 --skip-random-model 走零拷贝路径：step1 只校验，step2/step3 直接消费 model_path。

--skip-random-model 行为：

• 不构造随机权重，不复制权重，不写任何东西到 --output-path。
• 只做最小校验：--model-path 是目录；顶层（或 DiT 每个 *_model 子目录的）config.json 存在且为合法 JSON。
• step2 直接消费 --model-path；step3 通过 --reference-weights 指向同一路径做权重对比，避免先复制再比对的多余 IO。
• 设计动机：Wan2.2-T2V-A14B 等大型 DiT 模型动辄几十 GB，复制一份要数分钟并占双倍磁盘；透传原路径实现零拷贝。

Step3 基线来源

参数	含义
--original-path	step2 量化输入的目录。skip 模式下一般传 --model-path 的同值（因为 step2 直接从这里读），但严格说 step2 不强制要求它等于 step1 的输出。
--reference-weights	显式基线目录，覆盖 --original-path 作为对比左值。skip 模式下必须指向用户提供/已下载的真实模型目录（即 --model-path）。

Buffer 权重说明（Step3 常见问题）

• 若 Step3 出现“全回退权重缺失/键不一致”，需优先检查缺失项是否来自模型 buffer。
• msmodelslim 通常不会保存 buffer 类型权重，因此可能导致全回退产物缺少对应键。
• 适配器需要主动将这类关键 buffer 转为 nn.Parameter，以确保量化导出和一致性校验可覆盖该权重。

transformers 版本兼容处理（验证期）

• 触发条件：验证阶段出现模型实现文件导入/模型forward错误，且报错指向 transformers API 变更、缺失符号或签名不匹配。
• 必做沟通：向用户说明“当前报错疑似版本兼容问题”、给出关键报错摘要、请求确认目标版本策略（指定版本或版本区间）。
• 搜索策略：获用户确认后，使用二分法在确认范围内搜索可用 transformers 版本（每次切换版本后需重装并重跑触发失败的验证步骤）。
• 收敛标准：找到“可成功加载并通过对应验证步骤”的版本后停止搜索，并将最终版本写入msModelslim的config.ini。
• 失败处理：若二分搜索后仍无可用版本，返回阻塞结论并要求用户提供官方建议版本或模型实现修订方案。

权重安全（必读）

四步验证不应该碰原始权重。step3 / step4 只读；step1 的 --skip-random-model 只做 JSON 校验、不写盘；step1 随机权重路径与 step2 只写 --output-path。

step1/step2 硬拒绝任何会写进原始权重目录的 --output-path： output_path == model_path、output_path 在 model_path 内部、或 output_path 是 model_path 的父目录，一律 fail-fast。

DiT 永远不要就地改写原始权重——要零拷贝消费真实权重就用 --skip-random-model， 那条路径一个字节都不写。要小模型就写到独立目录。

自动化脚本

• scripts/step1_generate_test_model.py
• scripts/step2_run_quantization.py（LLM / VLM）
• scripts/step2_run_quantization_dit.py（DiT；独立脚本，自带预检与推理仓注入）
• scripts/step3_verify_weights.py
• scripts/step4_verify_quant_description.py

配置模板

step2 的全回退配置不再内联在脚本里，统一从 references/<family>/fallback_config.yaml 读取； step4 的全模型量化模板在同目录。改配置直接改 YAML，不要改脚本。

family	模板目录	apiversion
llm	references/llm/	modelslim_v1
vlm	references/vlm/	multimodal_vlm_modelslim_v1
dit	references/dit/	multimodal_sd_modelslim_v1

DiT 专有参数（见 references/dit/README.md）：

参数	说明
--calib-dataset	写入 spec.dataset。缺省时用 references/dit/index.example.jsonl 在 <output-path>/calib_data/ 生成一份自建校准集并指向它
--inference-config-json	JSON 串或文件，合并进 multimodal_sd_config.inference_config。全回退阶段可不传
--inference-repo	推理仓路径，设 WAN_INFERENCE_REPO 并前插 PYTHONPATH。Wan 系必传，否则 ImportError: Failed to import WanModel

step2 在调用 msmodelslim 之前会对最终配置做一轮预检（spec.dataset 必填且为 str、 enable_dump 应为 false（DiT data-free 不 dump 校准数据，true 会告警）、 apiversion 与 family 匹配、校准集路径可解析）。 --config-path 指定的现成配置同样过预检。

DiT 模板的三条硬约束与 inference_config 字段速查在 references/dit/README.md， 按需读取——非 DiT 任务不必加载。

参考资料

• 适配器验证指南
• DiT 模板三条硬约束与 inference_config 字段速查

输出格式要求

• 给出每一步的执行结果（PASS/FAIL）。
• 若失败，标注失败步骤、错误要点、建议修复方向。
• 最后给出总结结论：通过 / 未通过。