量化适配指南¶

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

量化特性介绍¶

量化推理流程¶

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

get_quant_method

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

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

quant_methods_overview

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

quant_method_call_flow

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

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

我们需要针对不同的**层**（attention、mlp、MoE (Mixture of Experts)）实现 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"
}

基于以上内容，我们简要介绍量化算法和量化模型的适配流程。

量化算法适配¶

Step 1: Algorithm Design. Define the algorithm ID (e.g., W4A8_DYNAMIC), determine supported layers (linear, moe, attention), and design the quantization scheme (static/dynamic, Per-Tensor/Per-Channel/Per-Group).
Step 2: Registration. Use the @register_scheme decorator in vllm_ascend/quantization/methods/registry.py to register your quantization scheme class.

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):
    ...

第三步：实现。创建算法实现文件，例如 vllm_ascend/quantization/methods/w4a8.py，并实现方法类和逻辑。
第四步：测试。使用您的算法生成量化配置，并在目标模型和硬件上验证正确性和性能。

量化模型适配¶

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

原始模型已在 vLLM Ascend 中成功适配。
融合模块映射：将模型的 model_type 添加到 packed_modules_model_mapping 中的 vllm_ascend/quantization/modelslim_config.py（例如 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	按组	按张量	静态	4位权重量化与16位激活精度，专为MoE模型专家层设计，支持int32格式的权重打包
`W8A16`	INT8	FP16/BF16	按通道	按张量	静态	8位权重量化与16位激活精度，平衡精度与性能，适用于线性层
`W8A8`	INT8	INT8	按通道	按张量	静态	静态激活量化，适用于需要高精度的场景
`W8A8_DYNAMIC`	INT8	INT8	按通道	按Token	动态	动态激活量化，按Token计算缩放因子
`W4A8_DYNAMIC`	INT4	INT8	按组	按Token	动态	支持直接按通道量化至4位，以及两步量化（先按通道至8位，再按组至4位）
`W4A4_FLATQUANT_DYNAMIC`	INT4	INT4	按通道	按Token	动态	使用FlatQuant对激活分布进行平滑处理后再进行4位动态量化，通过额外矩阵乘法保持精度
`W8A8_MIX`	INT8	INT8	按通道	按张量/Token	混合	支持两种部署模式：PD共部署（P和D均使用动态量化）和PD分离部署（P使用动态量化，D使用静态量化）

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

粒度： 指缩放因子计算的范围（例如 Per-Tensor、Per-Channel、Per-Group）。