逐行读懂Qwen3-30B-A3B-Instruct-2507-quantized.w4a8的recipe.yaml:llmcompressor量化配方详解

原创2026-10-16 23:30:431,984 阅读

逐行读懂Qwen3-30B-A3B-Instruct-2507-quantized.w4a8的recipe.yaml:llmcompressor量化配方详解

Qwen3-30B-A3B-Instruct-2507-quantized.w4a8 是 Qwen3-30B-A3B(MoE 混合专家)模型经 llmcompressor 量化后的 W4A8 版本。仓库根目录的 recipe.yaml 就是这次量化的"配方":它记录了哪些层被量化、权重压到几比特、激活如何量化。本文带你逐行读懂这份 llmcompressor 量化配方,帮助你理解 W4A8 量化是如何配置出来的。

recipe.yaml 是干什么的?

在深度学习模型压缩领域,量化配方(recipe) 是 llmcompressor 框架用来描述"量化什么、怎么量化"的 YAML 配置。本仓库的 README.md 说明了量化环境:

llmcompressor==0.8.2
compressed-tensors==0.12.2

也就是说,量化结果以 compressed-tensors 格式保存在 7 个分片文件中(model-00001-of-00007.safetensors ~ model-00007-of-00007.safetensors),而 recipe.yaml 保留了完整的量化参数,方便复现和审计。

recipe.yaml 全文逐行解析

下面是 recipe.yaml 的结构,共 60 行,分为三层嵌套:quant_stage → quant_modifiers → QuantizationModifier。

第 1 行:量化阶段 quant_stage

quant_stage:
  quant_modifiers:
    QuantizationModifier:
  • quant_stage:llmcompressor 的标准流程是 recipe → stage → modifier 三级结构,quant_stage 声明当前是量化阶段(相对的还有 sparsity_stage 稀疏化阶段)。
  • QuantizationModifier:执行量化操作的"修改器",后面所有参数都属于它。

第 4-5 行:config_groups 分组策略

config_groups:
  group_0:

config_groups 允许为不同层指定不同的量化方案。本配方分成两组:

分组 覆盖的层 权重方案 激活方案
group_0 自注意力层 q/k/v/o_proj 8-bit(W8) 8-bit 动态(A8)
group_1 MLP 层 gate/up/down_proj 4-bit 分组(W4,group_size=128) 8-bit 动态(A8)

这就是模型名"W4A8"的由来:主干 MLP 权重用 4-bit 存储,所有层激活统一按 8-bit 动态量化。

第 6-7 行:group_0 的 targets 正则匹配

targets: ['re:.*self_attn.k_proj.*', 're:.*self_attn.o_proj.*',
          're:.*self_attn.q_proj.*', 're:.*self_attn.v_proj.*']

re: 前缀表示正则表达式,.* 会匹配任意层数。这 4 个 pattern 对应 Qwen3 每层注意力模块的 4 个线性投影:

  • q_proj / k_proj / v_proj:Query、Key、Value 投影
  • o_proj:注意力输出投影

结合 config.json 可知该模型有 48 层(num_hidden_layers: 48),每层都有这些层被 W8A8 量化。

第 8-18 行:group_0 的权重量化 weights

weights:
  num_bits: 8
  type: int
  symmetric: true
  group_size: null
  strategy: channel
  block_structure: null
  dynamic: false
  actorder: null
  observer: minmax
  observer_kwargs: {}

逐个参数看:

参数 值 含义
num_bits 8 每个权重用 8 比特整数表示
type int 量化类型:整型(而非浮点 fp8)
symmetric true 对称量化,零点固定为 0,无需存储零点偏移
group_size null 不分组,整层共享一组缩放因子
strategy channel 按输出通道计算缩放因子(per-channel),精度高于 per-tensor
dynamic false 缩放因子在量化时静态计算好并随权重保存
observer minmax 用"最小值-最大值"观测器确定量化范围
actorder null 不启用激活排序(GPTQ 风格的排序优化)

第 19-28 行:group_0 的激活量化 input_activations

input_activations:
  num_bits: 8
  type: int
  symmetric: true
  strategy: token
  dynamic: true
  observer: null

关键区别在这一组:

  • strategy: token:按 token 维度量化激活——每个 token 的输入向量单独计算缩放因子,精度更高;
  • dynamic: true:动态量化,不预先校准,推理时根据实际输入现算缩放因子,因此 observer 为 null;
  • output_activations: null:不量化层输出激活。

第 32-57 行:group_1——4-bit 分组的 MLP 权重

group_1:
  targets: ['re:.*down_proj.*', 're:.*gate_proj.*', 're:.*up_proj.*']

gate_proj、up_proj、down_proj 是 MoE 模型中每个专家(expert)MLP 的 3 个线性层。该模型共 128 个专家(见 config.json 中 num_experts: 128),每个 token 只激活其中 8 个,所以这些层参数占比最大,是压缩的重点。

group_1 的 weights 与 group_0 的关键差异只有两处:

num_bits: 4        # 4 比特,体积直接缩小一半
group_size: 128    # 每 128 个权重共享一个缩放因子
strategy: group    # 分组量化

strategy: group + group_size: 128 是典型的 GPTQ 风格分组量化:把权重矩阵按 128 个元素切成小组,每组独立计算缩放因子。相比 per-channel,分组量化在 4-bit 这种低位宽下能显著减少精度损失——这也是 W4A8 方案里"4-bit 还能保持质量"的核心技巧。

input_activations 与 group_0 完全相同:8-bit、token 级、动态量化。

第 58-60 行:全局 targets 与 ignore 白名单

targets: ['re:.*self_attn.k_proj.*', 're:.*self_attn.o_proj.*',
  're:.*self_attn.q_proj.*', 're:.*self_attn.v_proj.*', 're:.*down_proj.*',
  're:.*gate_proj.*', 're:.*up_proj.*']
ignore: [lm_head, 're:.*mlp.gate$']
  • 顶层 targets 是 7 个 pattern 的并集,等价于两个分组的汇总;
  • ignore 明确排除两类模块不量化:
    • lm_head:输出层词表投影(词表 151936 维,体积大且对生成质量敏感,保留全精度);
    • re:.*mlp.gate$:MoE 的路由门(router gate)——它决定 token 被分发给哪些专家,只有少量标量权重,量化它容易破坏路由决策,所以保持原精度。

量化结果如何落盘?

recipe.yaml 描述"怎么量化",而量化完成后的模型配置则写在 config.json 的 quantization_config 字段里。可以看到:

  • quant_method: "compressed-tensors":推理框架据此加载量化权重;
  • config_groups.group_0 / group_1:与 recipe.yaml 完全对应的两组参数;
  • ignore 字段:正则 re:.*mlp.gate$ 被展开成了 48 个具体层名(model.layers.0.mlp.gate ~ model.layers.47.mlp.gate)外加 lm_head;
  • quantization_status: "compressed":确认模型已是压缩(量化)状态。

权重索引文件 model.safetensors.index.json 则把每个量化张量映射到对应的 safetensors 分片中。

常见疑问解答

Q1:为什么注意力层用 8-bit、MLP 层用 4-bit?

注意力投影对数值精度更敏感,8-bit per-channel 已足够稳定;MLP 专家占模型参数的大头(128 个专家 × 3 个投影),用 4-bit 分组量化能省下最多显存,且 group_size=128 的分组粒度足以兜住精度。

Q2:dynamic: true 的激活量化需要什么额外成本吗?

不需要校准数据集。动态量化在推理时按 token 现算缩放因子,属于"免校准"路线,这也是 llmcompressor 的 oneshot 接口(见 README.md 中的量化脚本)能快速完成量化的原因。

Q3:symmetric: true 有什么好处?

对称量化没有零点参数,反量化只需"乘缩放因子"一步,算子更轻量,对 Ascend NPU / GPU 上的量化 kernel 更友好。

Q4:我想复现这个配方,该关注哪些文件?

小结

📌 Qwen3-30B-A3B-Instruct-2507-quantized.w4a8 的 recipe.yaml 是一份典型的 llmcompressor 分组量化配方:

  1. 两级分组:注意力层走 W8A8(per-channel),MLP 专家层走 W4A8(group 128);
  2. 动态激活量化:所有层输入激活按 token 维度 8-bit 动态量化,无需校准数据;
  3. 白名单保护:lm_head 与 MoE 路由 mlp.gate 保持全精度,守住生成质量与路由决策。

读懂这份配方,你就能在 config.json 中对照出量化配置的实际落盘形态,也能按同样思路为自己的模型编写 W4A8 量化 recipe 了。

登录后查看全文
Qwen3-30B-A3B-Instruct-2507-quantized.w4a8