逐行读懂Qwen3-30B-A3B-Instruct-2507-quantized.w4a8的recipe.yaml:llmcompressor量化配方详解
逐行读懂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:我想复现这个配方,该关注哪些文件?
- 量化配方本体:recipe.yaml
- 量化脚本与依赖版本:README.md
- 模型结构参数(48 层、128 专家等):config.json
小结
📌 Qwen3-30B-A3B-Instruct-2507-quantized.w4a8 的 recipe.yaml 是一份典型的 llmcompressor 分组量化配方:
- 两级分组:注意力层走 W8A8(per-channel),MLP 专家层走 W4A8(group 128);
- 动态激活量化:所有层输入激活按 token 维度 8-bit 动态量化,无需校准数据;
- 白名单保护:
lm_head与 MoE 路由mlp.gate保持全精度,守住生成质量与路由决策。
读懂这份配方,你就能在 config.json 中对照出量化配置的实际落盘形态,也能按同样思路为自己的模型编写 W4A8 量化 recipe 了。