量化适配指南

本文档提供与 ModelSlim 相关的量化算法和模型适配的指导。

量化特性介绍

量化推理流程

vLLM Ascend 中注册和获取量化方法的当前流程如下：

vLLM Ascend 注册了自定义的 Ascend 量化方法。通过配置 --quantization ascend 参数（离线推理使用 quantization="ascend"），即可启用量化功能。在构建 quant_config 时，会初始化已注册的 AscendModelSlimConfig，并调用 get_quant_method 获取每个权重部分对应的量化方法，存储在 quant_method 属性中。

当前支持的量化方法包括 AscendLinearMethod、AscendFusedMoEMethod、AscendEmbeddingMethod 及其对应的非量化方法：

vLLM 定义的量化方法基类及量化方法的整体调用流程如下：

embedding 方法通常不实现量化，仅关注其他三种方法。

create_weights 方法用于权重初始化；process_weights_after_loading 方法用于权重后处理，例如转置、格式转换、数据类型转换等；apply 方法用于在前向过程中执行激活量化和量化矩阵乘法计算。

我们需要为不同的层（attention、mlp、MoE（混合专家））实现 create_weights、process_weights_after_loading 和 apply 方法。

补充：加载模型时，需要读取量化模型的描述文件 quant_model_description.json。该文件描述了模型各权重部分的量化配置和参数，例如：

{
    "model.layers.0.linear_attn.dt_bias": "FLOAT",
    "model.layers.0.linear_attn.A_log": "FLOAT",
    "model.layers.0.linear_attn.conv1d.weight": "FLOAT",
    "model.layers.0.linear_attn.in_proj_qkvz.weight": "W8A8_DYNAMIC",
    "model.layers.0.linear_attn.in_proj_qkvz.weight_scale": "W8A8_DYNAMIC",
    "model.layers.0.linear_attn.in_proj_qkvz.weight_offset": "W8A8_DYNAMIC",
    "model.layers.0.linear_attn.in_proj_ba.weight": "FLOAT",
    "model.layers.0.linear_attn.norm.weight": "FLOAT",
    "model.layers.0.linear_attn.out_proj.weight": "FLOAT",
    "model.layers.0.mlp.gate.weight": "FLOAT",
    "model.layers.0.mlp.experts.0.gate_proj.weight": "W8A8_DYNAMIC",
    "model.layers.0.mlp.experts.0.gate_proj.weight_scale": "W8A8_DYNAMIC",
    "model.layers.0.mlp.experts.0.gate_proj.weight_offset": "W8A8_DYNAMIC"
}

基于以上内容，我们简要描述量化算法和量化模型的适配过程。

量化算法适配

• 步骤1：算法设计。定义算法ID（例如 W4A8_DYNAMIC），确定支持的层（linear、moe、attention），并设计量化方案（静态/动态、pertensor/perchannel/pergroup）。

• 步骤2：注册。在 vllm_ascend/quantization/methods/registry.py 中使用 @register_scheme 装饰器注册你的量化方案类。

from vllm_ascend.quantization.methods import register_scheme, AscendLinearScheme, AscendMoEScheme

@register_scheme("W4A8_DYNAMIC", "linear")
class AscendW4A8DynamicLinearMethod(AscendLinearScheme):
    ...

@register_scheme("W4A8_DYNAMIC", "moe")
class AscendW4A8DynamicFusedMoEMethod(AscendMoEScheme):
    ...

• 步骤3：实现。创建算法实现文件，例如 vllm_ascend/quantization/methods/w4a8.py，并实现方法类和逻辑。

• 步骤4：测试。使用你的算法生成量化配置，并在目标模型和硬件上验证正确性和性能。

量化模型适配

适配新的量化模型需要确保以下三点：

• 原始模型已在 vLLM Ascend 中成功适配。

• 融合模块映射：将模型的 model_type 添加到 vllm_ascend/quantization/modelslim_config.py 的 packed_modules_model_mapping 中（例如 qkv_proj、gate_up_proj、experts），以确保分片一致性和正确加载。

packed_modules_model_mapping = {
    "qwen3_moe": {
        "qkv_proj": [
            "q_proj",
            "k_proj",
            "v_proj",
        ],
        "gate_up_proj": [
            "gate_proj",
            "up_proj",
        ],
        "experts":
        ["experts.0.gate_proj", "experts.0.up_proj", "experts.0.down_proj"],
    },
}

• 量化模型使用的所有量化算法都已集成到 quantization 模块中。

当前支持的量化算法

vLLM Ascend 支持多种量化算法。下表基于 vllm_ascend.quantization 模块的实现，概述了每种量化算法：

算法	权重	激活值	权重粒度	激活值粒度	类型	描述
W4A16	INT4	FP16/BF16	Per-Group	Per-Tensor	静态	4位权重量化与16位激活精度，专为MoE模型专家层设计，支持int32格式权重打包
W8A16	INT8	FP16/BF16	Per-Channel	Per-Tensor	静态	8位权重量化与16位激活精度，平衡精度与性能，适用于线性层
W8A8	INT8	INT8	Per-Channel	Per-Tensor	静态	静态激活量化，适用于需要高精度的场景
W8A8_DYNAMIC	INT8	INT8	Per-Channel	Per-Token	动态	动态激活量化，按token计算缩放因子
W4A8_DYNAMIC	INT4	INT8	Per-Group	Per-Token	动态	支持直接按通道量化为4位，以及两步量化（先按通道量化为8位，再按组量化为4位）
W4A4_FLATQUANT_DYNAMIC	INT4	INT4	Per-Channel	Per-Token	动态	使用FlatQuant在4位动态量化前对激活分布进行平滑处理，并通过额外矩阵乘法保持精度
W8A8_MIX	INT8	INT8	Per-Channel	按张量/按Token	混合	我们支持两种部署模式：PD共置（P和D均使用动态量化）和PD分离（P使用动态量化，D使用静态量化）

静态量化 vs 动态量化： 静态量化使用预计算的缩放因子，性能更优；动态量化则针对每个token/激活张量实时计算缩放因子，精度更高。

粒度： 指缩放因子计算的范围（例如按张量、按通道、按组）。