msmodelslim-model-adapt

name: msmodelslim-model-adapt description: 为 msModelSlim 创建基础 Transformers 模型适配器（Model Adapter）。包含创建适配器、实现必需接口与注册安装流程。适用：Decoder-only LLM、理解类 VLM（仅 LLM/text 部分）。不适用：多模态生成模型（图像/视频/语音生成）、Encoder-only、非 Transformers 架构。

msModelSlim 基础模型适配 Skill

本 Skill 指导如何为新模型创建基础适配器，使其跑通 W8A8/W4A16 量化流程。

说明：逐层量化（按层加载/懒加载）属于高阶可选特性，不是基础适配必需项。仅当 CPU 内存无法全量加载权重，或用户明确要求时，再在基础适配和四步验证（由 msmodelslim-adapter-verification 执行）完成后启用。

适用范围

支持：Decoder-only LLM、理解类 VLM（只处理文本/LLM 主干）
不支持：多模态生成（如 Stable Diffusion/Flux/Wan）、Encoder-only、非 Transformers

核心工作流

1. 权重来源确认（新增必做提示）

先询问并优先使用用户自有权重：要求用户先提供本地模型权重路径（或已下载模型目录）。
仅在用户确认“没有权重”时再下载：再协助用户执行下载流程，不要默认直接下载。
下载建议：
- 若先做结构分析，可先下载非权重文件：modelscope download --model <org>/<model> --local_dir ./models/<name> --exclude '*.safetensors'
- 若进入完整量化/验证流程，需补齐可用权重文件。

2. 准备工作

分析模型：阅读 config.json 与 modeling_*.py，确认结构与实现。
- 详见：模型结构分析指南

3. 创建适配器

使用模板：
- LLM: assets/model_adapter_template.py
- VLM: assets/vlm_model_adapter_template.py
实现接口：实现 handle_dataset, init_model, generate_model_visit, generate_model_forward, enable_kv_cache。
关键原则：
- visit 与 forward 必须严格一致。
- MoE 模型建议 unpack 为纯线性层。
- 若原始模型存在需要保留的 buffer 权重，需在适配器中将其转换为 nn.Parameter；否则量化导出阶段通常不会保存 buffer 权重。
- Tokenizer pad_token 兼容性必查：若 tokenizer.pad_token / pad_token_id 为 None，必须在适配器中重写 _load_tokenizer，将 pad_token 回退到 eos_token，避免量化过程中在 padding=True 时直接报错。
- 常见报错：
  - ValueError: Asking to pad but the tokenizer does not have a padding token.
- 根因链路：
  - adapter.handle_dataset(...) -> _get_tokenized_data(...) -> tokenizer(..., padding=True, ...)
  - 某些模型（如 MiniMax 系列）原生 tokenizer 未设置 pad_token。
- 推荐修复模板：
```
def _load_tokenizer(self, trust_remote_code=False):
    """Ensure tokenizer has a pad token for quantization dataset padding."""
    tokenizer = super()._load_tokenizer(trust_remote_code=trust_remote_code)
    if tokenizer.pad_token is None:
        tokenizer.pad_token = tokenizer.eos_token
    return tokenizer
```
- 说明：优先使用 eos_token 作为回退；若目标模型有更合适的专用 pad token，可按模型官方约定替换。
- 详见：适配器实现指南

4. 注册与安装

在 config/config.ini 注册模型与入口，并执行 bash install.sh 安装msModelSlim。
详见：适配器注册指南

5. 功能性验证（独立 Skill）

适配器开发完成后，告知用户可自动执行功能性验证。
验证流程已独立为：msmodelslim-adapter-verification。
该验证 Skill 会自动按四步执行：生成测试模型 -> 全回退量化 -> 权重一致性与可加载/保存验证 -> 实际量化与描述文件规则校验。

6. 可选高阶特性：逐层量化

触发时机：
- CPU 内存无法全量加载模型权重。
- 用户明确要求“逐层量化/逐层加载/懒加载/按层加载”。
启用顺序：
- 必须先完成基础适配与四步验证，再进入逐层量化改造。
实现与验证指引：
- 详见独立 Skill：msmodelslim-layer-wise-quantization

msModelSlim 基础模型适配 Skill

适用范围

核心工作流

1. 权重来源确认（新增必做提示）

2. 准备工作

3. 创建适配器

4. 注册与安装

5. 功能性验证（独立 Skill）

6. 可选高阶特性：逐层量化

参考资料