Skip to content

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/implementation_guide.md

View on GitHub
# 适配器实现指南

## 目录结构(建议)

一个模型适配器目录通常至少包含以下文件:

```text
msmodelslim/model/<model_type>/
├── __init__.py
├── model_adapter.py
└── model.py
```

- `__init__.py`:必须存在,保证目录可作为 Python 包被导入
- `model_adapter.py`:适配器入口与 5 个必需接口实现
- `model.py`:模型结构相关实现(如分层访问/前向辅助逻辑)

如果该模型已有其他依赖文件(如 `utils.py`、`configuration_*.py`),按实际需要补充,但不要省略 `__init__.py`。

## 必需接口

1. `handle_dataset`
2. `init_model`
3. `generate_model_visit`
4. `generate_model_forward`
5. `enable_kv_cache`

## 按模板区分:LLM / VLM 必要接口

以下结论基于 `assets/model_adapter_template.py` 与 `assets/vlm_model_adapter_template.py`。

### LLM(Decoder-only)

- **推荐继承**:`TransformersModel + ModelSlimPipelineInterfaceV1`(`ModelInfoInterface` 可选但建议)
- **必须实现**(5 个):`handle_dataset`、`init_model`、`generate_model_visit`、`generate_model_forward`、`enable_kv_cache`
- **模板中常见辅助方法**(非框架强制):`_create_model_instance` 等模型初始化辅助函数

### VLM(多模态理解,仅图文理解)

- **推荐继承**:`VLMBaseModelAdapter + ModelSlimPipelineInterfaceV1`(`ModelInfoInterface` 可选但建议)
- **必须实现**(5 个):`handle_dataset`、`init_model`、`generate_model_visit`、`generate_model_forward`、`enable_kv_cache`
- **模板中常见辅助方法**(非框架强制):`_create_model_instance` 等模型初始化辅助函数

## 特殊情况(需要单独处理)

### LLM 特殊情况

- **decoder 路径不一致**:不一定是 `model.layers`,也可能是 `model.decoder.layers` 或其他路径;必须改 `_decoder_layer_prefix`。
- **MoE packed 权重**:若为 3D packed experts,需先 unpack,再替换为线性层专家模块。
- **非标准配置字段**:若无 `num_hidden_layers` 或字段名不同,`init_model` 要按目标 config 改写。
- **tokenizer 无 pad_token**:若 `tokenizer.pad_token` / `pad_token_id` 为 `None`,Step2 全回退量化会在 `padding=True` 时报错。需在适配器中重写 `_load_tokenizer`,将 `pad_token` 回退为 `eos_token`(或模型官方推荐 pad token)。

### VLM 特殊情况

- **数据必须图文成对**:`handle_dataset` 需要同时有 `text` 和 `image`,纯文本样本不适配该模板。
- **视觉/文本路径差异**:模板假设 `model.visual` 与 `model.language_model.layers`,目标模型可能不同,需按真实 `modeling` 改。
- **融合逻辑不可套模板**:`generate_model_forward` 中 image embeds 注入规则(token id、位置编码、mask)模型差异大,必须对齐官方 forward。
- **text_config 结构差异**:若不存在 `config.text_config`,需改为模型实际文本配置路径并同步层数字段。
- **processor 行为差异**:不同模型 `AutoProcessor` 的输入键和 `apply_chat_template` 返回字段不同,需按真实返回值调整 keys。

### 接口功能说明(必须落实到代码)

#### 1) `handle_dataset(dataset, device) -> List[Any]`

- **职责**:把原始校准样本转成模型可直接消费的输入列表。
- **输入**:原始数据集(通常是文本 list)和目标设备。
- **输出**:`List[Any]`,每个元素可直接用于一次前向(如 `model(*data)` 或 `model(**data)`)。
- **实现建议**:优先复用基类 tokenization 能力(如 `_get_tokenized_data`),保证字段名与模型 forward 参数对齐。
- **完成判定**:量化流程读取该列表后,无需额外数据转换即可进入 `generate_model_forward`。

#### 2) `init_model(device) -> nn.Module`

- **职责**:初始化并返回可参与量化流程的模型实例。
- **输入**:目标设备(NPU/CPU)。
- **输出**:`nn.Module`(`eval()` 状态)。
- **实现建议**:按模型真实结构加载,确保后续 visit/forward 可访问到目标层。
- **完成判定**:返回模型后,`generate_model_visit` 能遍历目标量化层,且前向可执行。

#### 3) `generate_model_visit(model) -> Generator[ProcessRequest, Any, None]`

- **职责**:定义"按什么顺序遍历哪些模块"进行逐层处理。
- **输入**:初始化后的模型。
- **输出**:按顺序 `yield ProcessRequest`(每个 request 对应一个待处理模块)。
- **实现建议**:以真实 decoder/block 顺序输出,不跳层、不重排;名称路径应可唯一定位模块。
- **完成判定**:产出的层序列与 `generate_model_forward` 一一对应。

#### 4) `generate_model_forward(model, inputs) -> Generator[ProcessRequest, Any, None]`

- **职责**:定义与 `visit` 对齐的分段前向,用于逐层校准。
- **输入**:模型 + 单条校准输入。
- **输出**:按顺序 `yield ProcessRequest`(包含该层执行所需输入)。
- **实现建议**:层顺序、分段边界、张量传递路径与 `generate_model_visit` 严格一致。
- **完成判定**:同一层在 visit/forward 的索引和语义完全匹配,不出现错位。

#### 5) `enable_kv_cache(model, need_kv_cache) -> None`

- **职责**:统一控制 KV Cache 开关。
- **输入**:模型实例与布尔开关。
- **输出**:无返回(原地修改)。
- **实现建议**:优先复用基类 `_enable_kv_cache`;至少确保主干模型 config 中 `use_cache` 被正确设置。
- **完成判定**:开关后模型行为与预期一致,校准场景下通常可关闭以降低内存占用。

## 关键实现原则

### 1) `generate_model_visit` 与 `generate_model_forward` 必须严格一致

- 遍历层集合一致
- 顺序一致
- 分层输入输出传递一致

这是最容易出错、也最影响量化正确性的部分。

### 2) 不要靠模型名猜结构

必须以真实 `modeling` 代码为准,确认层路径、命名和 forward 行为后再写适配器。

### 3) VLM 只走"视觉整体 + 文本逐层"

- 优先复用 VLM 基类
- visit/forward 中视觉模块与文本层顺序保持一致
- 图文融合逻辑需对齐目标模型官方 forward

### 4) MoE 融合结构优先按"unpack 后纯线性层"适配

很多新模型的 MoE 使用融合/打包权重(常见为 3D 张量),而量化流程通常更适合 `nn.Linear` 形式的专家实现。

实现要求:
- 先判断原始实现是否为 3D packed experts(不要假设所有 MoE 都一样)
- 若是 packed 结构,不仅要在加载时 unpack,还要实现对应的 MoE 拆分 module
- unpack 后专家应落到纯线性层(`gate_proj` / `up_proj` / `down_proj`),避免后续流程直接依赖 3D 权重
- 推荐结构:`moe_utils.py` 提供拆分后的 MoE module,`model_adapter.py` 负责权重 unpack 与模块替换

可参考 `qwen3_5` 的实现思路(`moe_utils.py`、`modeling_qwen3_5_mtp.py`):先识别 packed 权重,再拆分为逐 expert 线性层。

示例代码请参考:
- `references/moe_unpacked_module_example.py`
- `references/moe_unpacked_adapter_example.py`

## 可选高阶特性

逐层量化(按层加载/懒加载)相关实现、工作流与示例已迁移到独立 Skill:
- `msmodelslim-layer-wise-quantization`
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall