kali20gakki/msAgent / skills/quantizer/msmodelslim-model-adapt
msmodelslim-model-adapt
Verified为 msModelSlim 创建基础 Transformers 模型适配器(Model Adapter)。 包含创建适配器、实现必需接口与注册安装流程。 适用:Decoder-only LLM、理解类 VLM(仅 LLM/text 部分)。 多模态生成(DiT/扩散,含双/多专家)见下方「多模态生成扩展」节,按需加载。 不适用:Encoder-only、非 Transformers 架构。
references/dit/pitfalls.md
View on GitHub# 多模态生成模型量化通用陷阱清单(适配必查)
> 这份清单从 Wan2.2-T2V-A14B 端到端验收中提取。每条都是**通用**的 —— 任何走 `MultimodalSDModelslimV1QuantService` 的多模态生成模型都会撞到。
> Agent 适配新模型时,**先逐条核对再落盘**。
---
## A. Meta tensor 迁移
### A.1 `Cannot copy out of meta tensor`
**触发**:在 `inference_dump_calib_data` 或 `init_model` 里裸写 `model.to('npu')` 或 `model.to(target_device)`,但模型里有 Parameter 仍落在 meta device。
**通用根因**:diffusers / 推理仓的 `WanModel.from_pretrained` 等加载范式会在量化 hook 注入后**懒**创建部分 Parameter(q/k norm、attn bias 等)。这些 Parameter 在首次 `to('npu')` 时才被复制 —— 但若上游 `materialize` round 没覆盖到它们,就抛 `NotImplementedError`。
**通用修法**(两步):
1. **materialize**:遍历所有 `Parameter`,对 `device.type == 'meta'` 的走 `module._parameters[name] = nn.Parameter(param.to(target_device), requires_grad=...)`;
2. **safe `.to(device)`**:再调一次 `.to(target_device)`(此时已无 meta 参数)。
> 不要在量化路径任何位置写裸 `.to('npu')`;要么走上面两步,要么用推理仓自带的 `convert_model_dtype` flag。
---
## B. 显存碎片化
### B.1 60 GB HBM 仅占 6 GB 就 OOM
**触发**:dump 完 T5/VAE 没有释放 → 量化阶段 `low_noise_model.to('npu')` 找不到连续 30+ GB。
**通用根因**:`prepare_calib_data` 走完 `inference_dump_calib_data` 后,pipeline 的 `text_encoder` / `vae` 仍占着 NPU 显存。后续 `low/high_noise_model.to('npu')` 要 30+ GB 连续空间,HBM 因碎片化无法分配。
**通用修法**:`prepare_calib_data` 末尾**显式**释放辅助模型:
```python
def release_auxiliary_models(self):
"""任何 DiT 通用:dump 完释放 text_encoder / vae / 等与量化无关的子模块。"""
pipeline_attrs = ("wan_t2v", "wan_i2v", "wan_ti2v", "pipeline")
for attr in pipeline_attrs:
pipeline = getattr(self, attr, None)
if pipeline is None:
continue
for sub_name in ("text_encoder", "vae", "image_encoder", "safety_checker"):
sub = getattr(pipeline, sub_name, None)
if sub is not None:
# 子模块若 .model 是真正的 Module,则先把子模块迁 CPU
inner = getattr(sub, "model", None)
if isinstance(inner, nn.Module):
inner.cpu()
del pipeline.__dict__[sub_name]
if hasattr(torch, "npu") and hasattr(torch.npu, "empty_cache"):
torch.npu.empty_cache()
elif torch.cuda.is_available():
torch.cuda.empty_cache()
```
> 新模型若还有别的"量化无关子模块"(如 `image_encoder` / `safety_checker` / `prompt_extender`),**同样**在此函数里释放。
---
## C. `dump_config.enable_dump` 的语义陷阱
### C.1 `enable_dump=False` 仍触发浮点推理 → 崩
**触发**:适配器 `prepare_calib_data` 没读 `dump_config.enable_dump`,永远调 `inference_dump_calib_data` → `WanT2V.generate` → `low_noise_model.to('npu')` → meta tensor 错误。
**根因**:误以为 `enable_dump=False` = "完全跳过 dump"。
**通用语义**:
- `enable_dump=False`(**DiT data-free 默认**):完全跳过 dump,返回 `{expert_name: None}`
- `enable_dump=True`:走 `inference_dump_calib_data`(用模型自身浮点推理产 calib_data;仅在确需 dump 校准数据时显式开启)
**通用修法**(必须):
```python
def prepare_calib_data(self, models, dump_config, save_path, dataset, inference_config):
if not dump_config.enable_dump:
return {expert_name: None for expert_name in models} # P1 短路
# ... 正常路径
```
---
## D. parse_args 单次调用
### D.1 `__init__` + `configure_runtime` 双次 parse_args
**触发**:基类 `__init__` 与 `configure_runtime` 都各自调一次原仓 `parse_args()`。
**根因**:parse_args 内部用 `argparse.ArgumentParser.parse_args()`,其默认会读 `sys.argv[1:]`。双次调用可能在分布式 / 多线程场景下污染全局。
**通用修法**(单次 + 安全包装):
```python
def _parse_args_from_<repo>(self, cli_args: List[str]):
"""通用:临时改写 sys.argv → finally 恢复 → 单次调用 parse_args。"""
original_argv = sys.argv
try:
sys.argv = ["<entry>.py", *cli_args]
return <repo>._parse_args()
finally:
sys.argv = original_argv
```
**调用约定**:
- 基类 `__init__` **不**预解析(避免污染 model_args);
- 仅 `configure_runtime` 调一次;
- 字段白名单探测(`_allowed_*_config_keys`)也在这次解析时一并拿到。
---
## E. 量化固定 flag 缺失
### E.1 量化时受并行 / cache 干扰 → 不收敛 / OOM
**触发**:YAML 写得不完整 → 原仓 CLI 默认打开 `dit_fsdp=True` / `use_attentioncache=True` / `ulysses_size>1` 等 → 量化 stage 触发 DDP 初始化或多卡并行 → 卡死 / OOM。
**通用修法**(注入量化固定覆盖):
```python
quant_overrides = {
# 通用:分布式并行
"cfg_size": 1, "ulysses_size": 1, "ring_size": 1, "tp_size": 1,
# 通用:并行开关
"vae_parallel": False, "t5_fsdp": False, "dit_fsdp": False,
# 通用:cache / fusion
"use_attentioncache": False, "use_rainfusion": False,
# 按模型加:如 Wan2.2 不需要 use_prompt_extend(避免 dashscope 依赖)
"use_prompt_extend": False,
}
argv.extend(self._namespace_to_argv(quant_overrides))
argv.extend(["--task", self.scene_task, "--ckpt_dir", str(self.model_path)])
```
> **字段名按目标 DiT 推理仓 parse_args 实际支持的 key 调整**;找不到对应 key 时 Pydantic/白名单校验会 fail-fast,可定位。
---
## F. 双专家 key 一致性
### F.1 `init_model` dict key 与 `calib_data` key 不一致 → `SchemaValidateError`
**触发**:`init_model` 返回 `{"low_noise_model": ..., "high_noise_model": ...}`,但 `prepare_calib_data` 写出 `calib_data_<task>_low.pth`(key 是 `low` 而非 `low_noise_model`)。
**根因**:expert key 必须全链路一致(`init_model` → `_bind_expert_sub_adapters` → `get_expert_adapter` → `prepare_calib_data` 的 pth 文件名)。
**通用修法**:
1. 基类定义 `DUAL_EXPERT_SCENE_TASKS = frozenset({"<scene_a>", "<scene_b>"})`;
2. 子类 `init_model` 构造 dict 时**完全按 DUAL_EXPERT_SCENE_TASKS 中的 key**;
3. 基类 `get_expert_adapter` 在双专家未绑定时报 `InvalidModelError`(不静默回退父适配器,避免 quantize 走错 context)。
---
## G. 子适配器接口继承
### G.1 QuaRot / FA3 静默失效
**触发**:`Wan2_2ExpertSubAdapter` 只继承 `BaseModelAdapter`,靠 `__getattr__` 把扩展方法代理到父类。结果 `LayerWiseRunner` 的 `isinstance(sub, OnlineQuaRotInterface)` 返回 `False`,量化 service 直接跳过 QuaRot/FA3 算子。
**根因**:isinstance 检查不识别 `__getattr__` 委托。
**通用修法**:子适配器**显式继承**所有扩展接口:
```python
class MyExpertSubAdapter(
BaseModelAdapter,
OnlineQuaRotInterface,
FA3QuantAdapterInterface,
IterSmoothInterface,
):
def __init__(self, parent, expert_name): ...
def get_online_rotation_configs(self, model=None): return self._parent.get_online_rotation_configs(model)
def inject_fa3_placeholders(self, root_name, root_module, should_inject):
return self._parent.inject_fa3_placeholders(root_name, root_module, should_inject)
```
---
## H. `_quantization_context_with_no_sync` 多 expert 包装
### H.1 单层 `with A, B, C` 写死 expert 数量
**触发**:基类量化上下文写 `with self.low_noise_model.no_sync(), self.high_noise_model.no_sync()`,但单专家 / 三专家模型上不存在对应 attribute → AttributeError。
**通用修法**(ExitStack 动态 enter):
```python
@contextmanager
def _quantization_context_with_no_sync(self, *dit_models: nn.Module):
import torch.cuda.amp as amp
# 模块迁移:非 blocks → npu,blocks → cpu(推理仓 block 名通常含 'blocks')
for m in dit_models:
if m is None: continue
for name, module in m.named_modules():
if not name: continue
(module.to('cpu') if name.startswith('blocks') else module.to('npu'))
with amp.autocast(dtype=self.model_args.param_dtype), torch.no_grad(), ExitStack() as stack:
for m in dit_models:
if m is None: continue
stack.enter_context(getattr(m, "no_sync", nullcontext)())
yield
```
> 子类 `quantization_context` 直接 `return self._quantization_context_with_no_sync(*experts)` 即可。
---
## I. Pydantic 校验链与跨场景串扰
> YAML `multimodal_sd_config` 的校验分**两级**(真相源:主仓 `msmodelslim/core/quant_service/multimodal_sd_v1/quant_config.py` 的 `MultimodalSDConfig`):
>
> 1. **YAML schema 层**:`MultimodalSDConfig`(`extra="allow"`,迁移期兼容)。声明字段只有 `dump_config`(必选)和 `inference_config`(Optional dict);任何其它 key 落入 `model_extra`。
> 2. **适配器字段层**:`validate_inference_config` 取 `resolve_inference_raw()` 的 dict,用适配器 `get_inference_config_class()` 的 `InferenceConfig`(`extra="forbid"`)做 `model_validate`。
>
> 两级校验对**任何** YAML 都恒定生效;区别在字段选择:
>
> - YAML 写 `inference_config` → 两级都严格校验(第 1 级 schema + 第 2 级适配器字段,`extra="forbid"` fail-fast)
> - YAML 写 `model_config`(迁移期旧字段)→ 第 1 级经 `extra="allow"` 宽容收纳 + deprecation warning;第 2 级 `validate_inference_config` 仅接受 `MultimodalPipelineInterface`(新接口)适配器,legacy 适配器不经过它
### I.1 `inference_config` 与迁移期 `model_config` 互斥
**触发**:YAML `multimodal_sd_config` 同时写 `inference_config` 和 `model_config`(迁移期旧字段)→
`SchemaValidateError: inference_config and model_config are mutually exclusive; please keep only one.`
**根因**:`MultimodalSDConfig.validate_inference_config_exclusive`(`model_validator`)强制两者互斥。`extra="allow"` 只保证 `model_config` 能**落进** `model_extra` 不报 unknown field,但与 `inference_config` 并存即 fail-fast。
**通用修法**:新模型 YAML 一律只写 `inference_config`。`model_config` 仅主仓历史 YAML 迁移期使用(`resolve_inference_raw` 回退读取时打 deprecation warning),不要出现在任何模板 / 文档 / 新生成的 YAML 里。
> **撞名警告**:适配器 `InferenceConfig` 类体内的 `model_config = ConfigDict(extra="forbid")` 是 **Pydantic 类属性**,与 YAML 的 `model_config` 段毫无关系。排查报错时不要把类属性"补"进 YAML——那正是触发互斥报错的最短路径。
**合法写法对照**:
```yaml
multimodal_sd_config:
dump_config: # 必选
capture_mode: "args"
dump_data_dir: ""
inference_config: # ✅ 新路径:经适配器 InferenceConfig 校验
size: "1280*720"
sample_steps: 40
# model_config: {...} # ❌ 迁移期旧字段;与 inference_config 互斥,勿写
```
### I.2 YAML `task` 字段覆盖 `scene_task`
**触发**:用户用 `Wan2.2-T2V-A14B` 注册名(指向 T2V 适配器),但 YAML `inference_config.task="i2v-A14B"` → 跨场景串扰 → I2V pipeline 被错误地按 T2V 配置加载。
**通用修法**:
```python
class MyInferenceConfig(BaseModel):
model_config = ConfigDict(extra="forbid")
task: Optional[str] = "t2v-A14B" # 必须有默认值 + 校验
@model_validator(mode='before')
@classmethod
def _reject_mismatched_task(cls, data):
expected = "<this_scene_task>"
if isinstance(data, dict) and data.get("task") not in (None, expected):
raise ValueError(
f"task {data['task']!r} does not match this adapter (expected {expected!r}). "
f"Use model_type <other_model_type> for {data['task']!r}."
)
return data
```
---
## J. 样本校验规则
### J.1 T2V 校准收到带 image 的样本
**触发**:dataset 同时含 T2V 校准样本(无 image)和 I2V 校准样本(带 image),T2V 适配器误消费带 image 的 → 推理路径上 image 为空 / 类型错误。
**通用规则**(按场景分类):
| 场景 | text 必填 | image 必填 | image 可选 |
|------|----------|-----------|-----------|
| 文本生视频/图像 (T2V/T2I) | ✅ | ❌ 禁 | — |
| 图生视频/图像 (I2V/I2I) | ✅ | ✅ | — |
| 文本+图像生 (TI2V/TI2I) | ✅ | — | ✅ |
**通用实现模板**:
```python
def validate_calib_samples(self, samples):
rule = self._SAMPLE_RULE # 子类 ClassVar
for idx, sample in enumerate(samples):
if not (isinstance(sample.text, str) and sample.text.strip()):
raise SchemaValidateError(f"{self.scene_task} sample[{idx}] requires non-empty text")
if rule.image_required and sample.image is None:
raise SchemaValidateError(f"{self.scene_task} sample[{idx}] requires image")
if rule.image_forbidden and sample.image is not None:
raise SchemaValidateError(f"{self.scene_task} sample[{idx}] must not include image")
return samples
```
---
## K. KV cache 不应在 DiT 启用
### K.1 启用 KV cache 导致量化时显存爆炸
**触发**:Agent 为"统一"在 DiT 路径启用 KV cache。
**通用原则**:DiT 推理**不依赖 KV cache**(扩散去噪是全序列并行)。模板默认 `pass` 写日志,禁止启用。
---
## L. block_keyword 探测失败
### L.1 自动探测找不到非平凡类名
**触发**:模型 block 类名短 / 不含 "block" / 全部 module 类名都是 trivial(Linear/LayerNorm/...)。
**通用兜底**:子类在 `_load_pipeline` 后直接赋值 `self.block_keyword = "<从 modeling_*.py 读到的子串>"`;不要纯靠自动探测。Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |