msmodelslim

msModelSlim - Ascend 模型压缩工具

MindStudio ModelSlim（msModelSlim）是一款针对 Huawei Ascend AI 处理器优化的模型压缩工具。它支持对大模型、MoE 模型和多模态模型进行量化与压缩。

---

快速入门

一键量化（V1 - 推荐）

V1 自动量化使用 lab_practice/ 目录中的配置文件。

# Basic W8A8 quantization for Qwen2.5-7B-Instruct
# Config files located at: lab_practice/<model_series>/<model>-<quant_type>-v1.yaml
msmodelslim quant \
    --model_path /path/to/Qwen2.5-7B-Instruct \
    --save_path /path/to/output \
    --device npu \
    --model_type Qwen2.5-7B-Instruct \
    --config_path /path/to/msmodelslim/lab_practice/qwen2.5/qwen2.5-7b-w8a8-v1.yaml \
    --trust_remote_code True

# MoE model quantization (Qwen3-30B-A3B W4A8)
msmodelslim quant \
    --model_path /path/to/Qwen3-30B-A3B \
    --save_path /path/to/output \
    --device npu \
    --model_type Qwen3-30B \
    --config_path /path/to/msmodelslim/lab_practice/qwen3_moe/qwen3-30b-w4a8-v1.yaml \
    --trust_remote_code True

# Multi-device distributed quantization
msmodelslim quant \
    --model_path /path/to/model \
    --save_path /path/to/output \
    --device npu:0,1,2,3 \
    --model_type Qwen2.5-72B-Instruct \
    --config_path /path/to/msmodelslim/lab_practice/qwen2.5/qwen2.5-72b-w8a8c8-v1.yaml \
    --trust_remote_code True

注意：在 msmodelslim 仓库的 lab_practice/ 目录中查找配置文件：

• 结构：lab_practice/<model_series>/<model>-<quant_type>-v1.yaml
• 示例：lab_practice/qwen2.5/qwen2.5-7b-w8a8-v1.yaml

传统量化（V0）

cd msmodelslim
python3 example/Qwen/quant_qwen.py \
    --model_path /path/to/Qwen2.5-7B-Instruct \
    --save_directory /path/to/output \
    --calib_file example/common/boolq.jsonl \
    --w_bit 8 --a_bit 8 \
    --device_type npu \
    --trust_remote_code True

---

安装

前置条件

• Python：3.8+（某些环境推荐使用 3.9+）
• CANN：8.2.RC1+（推荐使用 8.3.RC1 或 8.5.0）
• PyTorch Ascend：适用于 PyTorch 的 Ascend 扩展

安装步骤

# 1. Clone repository
git clone https://gitcode.com/Ascend/msmodelslim.git
cd msmodelslim

# 2. Run installation script
bash install.sh

# 3. For Atlas 300I Duo (sparse quantization support)
cd ${PYTHON_SITE_PACKAGES}/msmodelslim/pytorch/weight_compression/compress_graph/
sudo bash build.sh ${CANN_INSTALL_PATH}/ascend-toolkit/latest
chmod -R 550 build

注意：请勿在源代码目录中运行 msmodelslim 命令，以避免模块路径冲突。

有关环境设置的详细信息，请参阅 references/installation.md。

---

量化类型

类型	权重	激活值	描述	使用场景
W8A8	INT8	INT8	标准 8 位量化	通用场景，兼顾精度与性能
W8A16	INT8	FP16	仅权重量化	对精度要求较高的场景（仅限 MindIE）
W4A8	INT4	INT8	低比特权重量化	需要更高压缩率的场景
W8A8C8	INT8	INT8 + KV Cache	搭配 KV Cache 量化	长序列推理
W8A8S	INT8 Sparse	INT8	稀疏量化	Atlas 300I Duo 优化
W16A16S	FP16 Sparse	FP16	浮点稀疏量化	需要高压缩率的场景

量化类型选择

优先级	推荐类型
精度优先	W8A16 > W8A8 > W4A8
内存优先	W4A8 > W8A8 > W8A16
长序列	W8A8C8（搭配 KV Cache 量化）
Atlas 300I Duo	W8A8S 或 W16A16S

BFLOAT16 模型说明

对于权重 torch_dtype=bfloat16 的模型（例如 Qwen3-30B-A3B）：

如果遇到 AclNN_Parameter_Error(EZ1001): Tensor self not implemented for DT_BFLOAT16，这很可能是 Docker 镜像问题，而非 msmodelslim 的限制。

快速诊断：

# Test if torch_npu works correctly
python3 -c "import torch; import torch_npu; a = torch.tensor(1).npu(); print('NPU OK')"

如果此操作失败，说明你的 Docker 镜像存在兼容性问题。请尝试：

1. 使用其他或更新的 Docker 镜像
2. 重新安装与 CANN 版本匹配的 torch_npu
3. 确保使用 CANN 8.3.RC1+ 以支持 BF16

容器设置：有关通过 NPU 设备映射正确创建 Docker 容器的信息，请参阅 ascend-docker。有关 msmodelslim 专用的容器配置，请参阅 references/docker-setup.md。

---

算法选择

离群值抑制算法

算法	描述	使用场景
SmoothQuant	对激活值和权重进行协同缩放	标准离群值抑制
QuaRot	正交旋转矩阵	对精度要求较高的场景
Iterative Smooth	迭代平滑	分布复杂的场景
Flex Smooth	网格搜索以找到最佳 alpha/beta	不同架构
KV Smooth	KV Cache 平滑	KV Cache 量化

量化算法

算法	描述	使用场景
AutoRound	用于舍入的 SignSGD 优化	4 位超低比特量化
GPTQ	按列优化	高精度权重量化
SSZ	迭代搜索比例/偏移量	权重分布不均匀的场景
PDMIX	动态（prefill）+ 静态（decode）	大模型推理
FA3	按头进行 INT8 注意力计算	长序列、MLA 模型
MinMax	最小值-最大值范围统计	基础量化
Histogram	直方图分布分析	过滤离群值

快速选择指南

• 新手：使用一键量化，并通过 --config_path 指向 lab_practice/ 配置文件
• 优先考虑精度：QuaRot + AutoRound
• 长序列：FA3 + KVCache Quant
• 自定义模型：参见 references/model-integration.md

算法详情请参见 references/quantization-algorithms.md。

---

支持的模型

大语言模型

模型系列	一键量化	V0 脚本	备注
Qwen3	✓	example/Qwen/	Qwen3-8B/14B/32B
Qwen2.5	✓	example/Qwen/	7B/32B/72B/Coder
Qwen2	-	example/Qwen/	7B/72B
DeepSeek-V3	✓	example/DeepSeek/	V3/V3.1/V3.2, R1
LLaMA	-	example/Llama/	LLaMA2, LLaMA3.1
GLM	-	example/GLM/	GLM-4, GLM-5
InternLM2	-	example/InternLM2/	InternLM2-20B
Kimi	-	example/Kimi/	Kimi K2
HunYuan	-	example/HunYuan/	HunYuan-A52B

MoE 模型

模型	一键量化	备注
Qwen3-MoE	✓	Qwen3-30B-A3B, Qwen3-235B-A22B
DeepSeek MoE	✓	DeepSeek-V2, V3 系列

多模态模型

类型	模型	示例脚本
视觉语言	Qwen-VL, Qwen2-VL, Qwen3-VL, InternVL2, LLaVA, GLM-4.1V	example/multimodal_vlm/
生成	FLUX, SD3, HunyuanVideo, OpenSoraPlan, Wan2.1	example/multimodal_sd/

完整支持矩阵请参见 references/model-support.md。

---

自定义模型集成

快速概览

1. 创建适配器文件：msmodelslim/model/my_model/model_adapter.py
2. 定义适配器类：继承 TransformersModel + 接口类
3. 实现接口：handle_dataset、init_model、generate_model_visit 等
4. 注册模型：添加到 config/config.ini

示例

from msmodelslim.model.interface_hub import ModelSlimPipelineInterfaceV1
from msmodelslim.model.common.transformers import TransformersModel

class MyModelAdapter(TransformersModel, ModelSlimPipelineInterfaceV1):
    def handle_dataset(self, dataset, device):
        return self._get_tokenized_data(dataset, device)
    
    def init_model(self, device):
        return self._load_model(device)
    
    def generate_model_visit(self, model):
        from msmodelslim.model.common.layer_wise_forward import generated_decoder_layer_visit_func
        yield from generated_decoder_layer_visit_func(model)
    
    def generate_model_forward(self, model, inputs):
        from msmodelslim.model.common.layer_wise_forward import transformers_generated_forward_func
        yield from transformers_generated_forward_func(model, inputs)

完整指南请参见 references/model-integration.md 和 scripts/model_adapter_template.py。

---

精度自动调优

敏感层分析

# Analyze model sensitivity
msmodelslim analyze --model_path /path/to/model --model_type Qwen2.5-7B-Instruct

分析算法：

• std：基于标准差（推荐用于一般场景）
• quantile：基于分位数/IQR（适用于长尾分布）
• kurtosis：基于峰度（用于检测极值）

自动调优策略

Standing High：通过二分搜索，在保持精度的同时尽量减少回退层。

# Use auto-tuning config
msmodelslim quant \
    --model_path /path/to/model \
    --save_path /path/to/output \
    --model_type Qwen2.5-7B-Instruct \
    --config_path /path/to/auto_tuning_config.yaml

调优策略请参见 references/precision-tuning.md。

---

部署

vLLM-Ascend

# Online service
vllm serve /path/to/quantized-model \
    --served-model-name "Qwen2.5-7B-w8a8" \
    --max-model-len 4096 \
    --quantization ascend

# Offline inference (Python)
from vllm import LLM, SamplingParams

llm = LLM(
    model="/path/to/quantized-model",
    max_model_len=4096,
    quantization="ascend"
)
outputs = llm.generate(["Hello"], SamplingParams(temperature=0.6))

MindIE

# Deploy with MindIE
# See MindIE documentation for details

权重转换

# Convert to AutoAWQ/AutoGPTQ format
python3 example/common/ms_to_vllm.py --input /path/to/quantized --output /path/to/converted

部署详情请参见 references/deployment.md。

---

输出文件

量化后，输出目录包含：

output/
├── config.json                      # Original model config
├── generation_config.json           # Generation config
├── quant_model_description.json     # Quantization description
├── quant_model_weight_w8a8.safetensors  # Quantized weights
├── tokenizer_config.json            # Tokenizer config
├── tokenizer.json                   # Tokenizer vocabulary
└── vocab.json                       # Vocabulary (if applicable)

---

故障排除

常见问题

问：量化过程中内存不足？

# Use layer-by-layer quantization (default in V1)
# Or use CPU quantization
msmodelslim quant --device cpu ...

问：量化后精度下降？

• 使用更高精度类型（W8A8，而不是 W4A8）
• 查看 lab_practice/ 中的最佳实践配置
• 启用异常值抑制算法
• 参见 references/precision-tuning.md

问：不支持该模型类型？

• 查看 references/model-support.md
• 实现自定义适配器：references/model-integration.md

问：如何启用调试日志？

export MSMODELSLIM_LOG_LEVEL=DEBUG
msmodelslim quant ...

---

脚本与资源

脚本

• scripts/check_env.sh - 环境检查
• scripts/quantize_model.sh - 量化模板
• scripts/model_adapter_template.py - 模型适配器模板

配置模板（assets/）

• assets/quant_config_w8a8.yaml - W8A8 配置
• assets/quant_config_w4a8.yaml - W4A8 配置
• assets/quant_config_sparse.yaml - 稀疏量化
• assets/quant_config_pdmix.yaml - PDMIX 配置

---

官方参考资料

• 文档：https://msmodelslim.readthedocs.io/zh-cn/latest/
• GitCode 仓库：https://gitcode.com/Ascend/msmodelslim
• vLLM-Ascend：https://docs.vllm.ai/projects/ascend/en/latest/
• 华为昇腾：https://www.hiascend.com/document

---

相关技能

• atc-model-converter - Ascend 模型转换
• npu-smi - NPU 设备管理
• hccl-test - HCCL 性能测试