msModelSlim 插件开发指导

概述

msModelSlim 内置了 Qwen、LLaMA、GLM 等主流模型的量化支持。模型出新速度远大于主仓发版速度。每接一个模型就改主仓，会导致主仓难以维护。

插件解开了这个耦合。主仓只管理量化引擎和接口契约。插件在外部实现接口，通过 entry points 向框架注册。主仓无需修改，插件独立开发、独立发布。

graph LR
    M[模型适配器<br/>模型结构] --> E[量化引擎]
    P[量化策略 YAML<br/>量化方案] --> E
    C[校准数据] --> E
    E --> O[(量化产物)]
    style M fill:#4A90D9,color:#fff
    style P fill:#4A90D9,color:#fff
    style C fill:#6B8E23,color:#fff

插件将多个扩展点打包在一起。每个扩展点通过 entry point 向框架注册，框架按需加载。当前已开放 extension point 的扩展点包括模型适配器、量化策略等。校准数据当前通过目录约定提供（calib_data/），独立扩展点规划中。适配器描述模型结构，YAML 描述量化方案，校准数据用于统计激活值 scale/zero_point。

mindmap
  root((可扩展维度))
    模型适配器
      DeepSeek
      Qwen
      Kimi
      MiniMax
    量化策略
      W8A8 / W4A8
      MXFP4 / FP8
    校准数据 规划中
      文本
      图片
      视频
      音频
    导出格式 规划中
      ascend_v1
      custom
      llm_compressor
    量化算法 规划中
      Processor

模型适配器和量化策略当前已开放扩展点。校准数据、导出格式和量化算法规划中。

量化方案开发工作流

将模型跑通量化需要五个步骤：

graph TB
    A[模型适配] --> B[策略制定]
    B --> C[数据校准]
    C --> D[权重导出]
    D --> E[精度测评]
    E -->|精度不达标| B
    E -->|适配器有缺陷| A
    style A fill:#4A90D9,color:#fff
    style B fill:#4A90D9,color:#fff
    style C fill:#6B8E23,color:#fff
    style D fill:#8B4513,color:#fff
    style E fill:#E8850C,color:#fff

五步并非严格串行。策略不达标则回到第二步修改 YAML，适配器有缺陷则回到第一步修复代码。迭代直到精度满意。

插件定位

插件不是量化引擎，而是量化引擎的原料包。它封装了前三步的成果：

graph LR
    subgraph 插件
        ADAPTER[模型适配器] -->|描述模型结构| PEDIGREE[pedigree]
        YAML[量化策略] -->|指定量化方案| CONFIG_ID[config_id]
        CALIB[校准数据] -->|提供校准样本| CALIB_DIR[calib_data]
    end
    ADAPTER -.-> ENGINE
    YAML -.-> ENGINE
    CALIB -.-> ENGINE
    ENGINE[量化引擎] --> EXPORT[权重导出]
    EXPORT --> EVAL[精度测评]
    style ADAPTER fill:#4A90D9,color:#fff
    style YAML fill:#4A90D9,color:#fff
    style CALIB fill:#6B8E23,color:#fff
    style ENGINE fill:#E8850C,color:#fff

量化引擎负责后两步（导出 + 测评），插件负责前三步（适配 + 策略 + 数据）。一个模型对应一个插件，一个插件可包含多种量化方案（多个 YAML）。

插件系统的核心思想：主仓管流程，插件管配置。 量化引擎的逻辑在主仓迭代，每个模型的适配细节和量化方案由插件独立维护。

插件制作

流程一览

graph LR
    START([开始]) --> CREATE[一、创建骨架]
    CREATE --> FILL[二、填充内容]
    FILL --> TEST[三、安装验证]
    TEST --> PACK[四、打包分发]
    style START fill:#E8850C,color:#fff
    style PACK fill:#4A90D9,color:#fff

一、创建骨架

graph LR
    START([开始]) --> CLONE[克隆仓库]
    CLONE --> INSTALL[安装元包]
    INSTALL --> CMD[执行 create 命令]
    CMD --> STRUCT[生成骨架结构]
    STRUCT --> DONE[骨架就绪]
    style DONE fill:#4A90D9,color:#fff

安装工具

git clone https://gitcode.com/rookie_hongchuan/msmodelslim-plugins
cd msmodelslim-plugins
pip install -e .
msmodelslim-plugins --help

生成骨架

msmodelslim-plugins create Minimax-2.5 w8a8

create 将模型名和量化类型翻译为包结构、命名和配置入口。

plugins/modelslim-plugin-minimax-2.5-w8a8/
├── pyproject.toml
├── README.md
└── src/
    └── msmodelslim_plugin_minimax_2_5_w8a8/
        ├── __init__.py
        ├── adapter/
        │   ├── __init__.py
        │   └── model_adapter.py      # 待填充
        ├── practice/
        │   └── __init__.py
        ├── calib_data/
        │   └── .gitkeep
        └── practice_data/
            └── minimax-2.5/
                └── minimax-2.5-w8a8.yaml  # 待配置

命名转换规则：

graph LR
    A["Minimax-2.5"] -->|pedigree| B["minimax-2.5"]
    A -->|display_name| C["Minimax-2.5"]
    B -->|+ w8a8| D["config_id: minimax-2.5-w8a8"]
    B -->|包名| E["msmodelslim_plugin_minimax_2_5_w8a8"]
    B -->|类名| F["Minimax25W8a8Adapter"]

pedigree 是核心概念：模型名小写化、特殊字符转短横线后的字符串。它出现在适配器的 get_model_pedigree()、策略目录名和 entry point 中，是插件的"主键"。config_id 是 pedigree 加量化类型的组合，标识一个具体策略。

骨架不只搭建目录结构，还填写了 entry points 和默认 W8A8 策略。

二、填充内容

骨架创建完成后，需要填充三类材料：

1. 模型适配器

graph LR
    subgraph 量化引擎视角
        V[遍历模型各层] --> F[逐层前向]
        F --> Q[逐层量化]
    end
    ADAPTER[model_adapter.py] -.->|描述模型结构| V
    ADAPTER -.->|描述前向过程| F
    style ADAPTER fill:#4A90D9,color:#fff

量化引擎对模型做两件事：遍历每一层、逐层前向拿到中间状态。不同模型的遍历方式不同——有的用 model.layers，有的用 transformer.blocks。适配器封装这层差异。

标准情况

如果 Minimax-2.5 是标准 HuggingFace DecoderLayer（与 Qwen、LLaMA 一致），骨架模板可直接使用：

from msmodelslim.model.common.transformers import TransformersModel
from msmodelslim.model.interface_hub import ModelSlimPipelineInterfaceV1
from msmodelslim.app.naive_quantization.model_info_interface import ModelInfoInterface
from msmodelslim.model.common.layer_wise_forward import (
    generated_decoder_layer_visit_func,
    transformers_generated_forward_func,
)


class Minimax25W8a8Adapter(TransformersModel, ModelSlimPipelineInterfaceV1, ModelInfoInterface):
    def get_model_pedigree(self):
        return "minimax-2.5"

    def init_model(self, device):
        return self._load_model(device)

    def generate_model_visit(self, model):
        yield from generated_decoder_layer_visit_func(model)

    def generate_model_forward(self, model, inputs):
        yield from transformers_generated_forward_func(model, inputs)

非标准情况

不确定属于哪种情况时，先在标准模板下执行 msmodelslim quant。报错信息会指示未匹配的模块。

适配器在 pyproject.toml 中通过 entry point 注册。骨架已自动生成注册信息：

[project.entry-points."msmodelslim.model_adapter.plugins"]
"Minimax-2.5" = "msmodelslim_plugin_minimax_2_5_w8a8.adapter.model_adapter:Minimax25W8a8Adapter"

含义：查询 Minimax-2.5 适配器时，从该模块路径加载对应类。

entry point 是插件系统的核心机制。每个扩展点对应一个 entry point 组：

三类扩展点彼此独立。一个插件可以注册其中一个或多个。后续新增扩展点也通过新增 entry point 组实现。

参考：

• plugins/hunyuan-image3-w8a8-dynamic/
• msmodelslim/model/adapters/

2. 最佳实践

graph LR
    subgraph "practice_data/<pedigree>/"
        A[w8a8.yaml]
        B[w4a8.yaml]
    end
    A --> ENGINE[量化引擎按 score 择优]
    B --> ENGINE
    ENGINE --> Q[msmodelslim quant]

同一模型可能适合不同场景：追求速度用 W8A8，精度敏感用 W4A8。插件支持在一个目录下放多个 YAML，引擎通过 score 字段自动选最优。用户也可用 --config_path 指定具体文件。

practice_data/
└── <pedigree>/
    ├── <config_id>-w8a8.yaml
    ├── <config_id>-w4a8.yaml
    └── <config_id>-w8a8_dynamic.yaml

骨架已生成 minimax-2.5-w8a8.yaml。要增加 W4A8 方案，在同目录放置 minimax-2.5-w4a8.yaml 即可。

YAML 编写参考已有插件的 practice_data，或 lab_practice/ 下的官方示例。

最佳实践目录同样在 pyproject.toml 中注册：

[project.entry-points."msmodelslim.naive_quantization.practice_dirs"]
"minimax-2.5-w8a8" = "msmodelslim_plugin_minimax_2_5_w8a8.practice:get_practice_dir"

入口函数仅返回 practice_data/ 路径：

def get_practice_dir() -> Path:
    return Path(__file__).resolve().parent.parent / "practice_data"

3. 校准集

校准集是量化引擎统计激活值 scale/zero_point 时使用的样本数据。当前通过目录约定存放（calib_data/），独立扩展点规划中。如果不需要静态量化校准，此步骤可跳过。

数据格式：

校准数据放置在 calib_data/ 目录下。骨架已创建 calib_data/.gitkeep，直接替换为实际数据即可。

三、安装验证

graph LR
    PLUGIN[插件目录] -->|pip install -e .| INSTALLED[已安装]
    INSTALLED -->|msmodelslim quant| RUN[量化]

# 开发安装（源码模式，修改即时生效）
cd plugins/modelslim-plugin-minimax-2.5-w8a8
pip install -e .

# 确认框架可发现插件
msmodelslim-plugins list
# 列表中应包含 Minimax-2.5

# 执行量化
msmodelslim quant \
    --model_path /path/to/model \
    --save_path ./output \
    --model_type "Minimax-2.5" \
    --quant_type w8a8 \
    --trust_remote_code True

四、打包分发

flowchart LR
    subgraph 开发者
        DEV(开发者)
    end
    subgraph GitCode
        WHEEL[(.whl)]
        RELEASE(Release)
        ISSUE(Plugin Issue)
    end
    subgraph Marketplace
        INDEX(插件索引)
    end
    subgraph 用户
        USER(用户)
    end

    DEV -->|patch| WHEEL
    WHEEL -->|上传| RELEASE
    RELEASE -->|提交 Issue| ISSUE
    ISSUE -->|更新索引| INDEX
    USER -->|发现 + 下载| ISSUE
    INDEX -->|msplugin install| USER
    USER -->|pip install| Q(msmodelslim quant)

分发方式

打包

msmodelslim-plugins patch plugins/modelslim-plugin-minimax-2.5-w8a8/

产物在 dist/ 下。

发布

1. 上传 .whl 到 GitCode Release，获取公开下载链接。
2. 在 Ascend/msmodelslim Issues 提交 Plugin Release Issue，填写链接、使用说明、精度数据。
3. （可选）更新 marketplace 索引。

Issue 模板中下载链接是必填项。GitCode Issue 不支持附件上传，wheel 需先托管到 Release。

插件使用

插件使用面向终端用户，不涉及开发。已安装的插件可通过 msmodelslim quant 直接使用。

发现插件

# 列出已安装的插件
msplugin list

# 从 marketplace 搜索远程插件
msplugin search <关键词>

# 列出 marketplace 所有插件
msplugin list --remote

安装插件

# 从 marketplace 安装（推荐）
msplugin install <插件名>

# 从 wheel 文件安装
pip install <name>.whl

# 从源码安装（开发模式）
pip install -e <插件目录>

使用插件

安装后直接通过模型类型名调用：

msmodelslim quant \
    --model_path /path/to/model \
    --save_path ./output \
    --model_type "Minimax-2.5" \
    --quant_type w8a8 \
    --trust_remote_code True

管理插件

# 卸载
msplugin remove <插件名>

# 查看 marketplace 配置
msplugin marketplace list

# 添加自定义 marketplace
msplugin marketplace add <名称> <索引 URL>

# 切换默认 marketplace
msplugin marketplace use <名称>