AWQ 4bit 量化原理揭秘:Qwen3-Coder-30B-A3B-Instruct-AWQ-4bit 的 recipe.yaml 配置逐项解读
AWQ 4bit 量化原理揭秘:Qwen3-Coder-30B-A3B-Instruct-AWQ-4bit 的 recipe.yaml 配置逐项解读
📦 Qwen3-Coder-30B-A3B-Instruct-AWQ-4bit 是通义千问代码模型 Qwen3-Coder-30B-A3B 的 AWQ 4bit 量化版本:把 30.5B 参数的 MoE 模型压缩到约 18.09 GB,让单卡甚至双卡也能流畅运行顶级开源代码模型。本文逐行解读量化配方 recipe.yaml,带你彻底搞懂 AWQ 4bit 量化原理、group_size 32 分组量化、dual smoothing(双重平滑)等每个参数的作用,一文吃透这份配置背后的工程细节。
一、AWQ 4bit 量化到底在做什么?
理解配置前,先花 1 分钟建立概念 👇
| 概念 | 通俗解释 |
|---|---|
| 量化(Quantization) | 把权重从 16 位浮点(bf16)压缩成 4 位整数,体积约为原来的 1/4 |
| AWQ(Activation-aware Weight Quantization) | 激活感知的权重量化:根据激活值的分布找出"重要权重",保护它们少受精度损失 |
| 4bit | 每个权重只用 4 个比特存储,30B 模型可省 20+ GB 显存/磁盘 |
| Group-wise(分组量化) | 每 32 个权重共享一套缩放因子,兼顾精度与体积 |
AWQ 的核心洞察:激活值大的那部分权重,必须量化得更仔细。于是它做了两件事:
- 平滑(Smoothing):调整前后层参数,让敏感权重对应的输入激活变"平滑"(幅度变小),降低量化误差;
- dual scaling(双重缩放):给重要权重一个更大的缩放系数,让它们量化时"分到的精度更多"。
下面这份 recipe.yaml 就是这套流程的"施工图纸"。
二、recipe.yaml 整体结构一览
打开 recipe.yaml,配置只有 37 行,结构非常清晰:
default_stage:
default_modifiers:
AWQModifier: # 量化修改器:整份配置的主角
config_groups: # 量化参数组(group_0)
targets / ignore / mappings
offload_device / duo_scaling / n_grid
可以理解为三段:量什么(targets/ignore)→ 怎么量(weights 参数组)→ 怎么保精度(mappings 平滑 + duo_scaling)。
三、量化参数组:4bit 分组的每一处细节
config_groups.group_0 定义了具体的量化方案,也是最能体现"AWQ 4bit"字面的部分:
weights:
num_bits: 4
type: int
symmetric: true
group_size: 32
strategy: group
observer: mse
| 参数 | 值 | 作用解读 |
|---|---|---|
num_bits: 4 |
4 位 | 每个权重压缩到 4 bit,bf16 → 4bit 体积约缩小 4 倍 |
type: int |
整数 | 使用整数量化而非浮点量化 |
symmetric: true |
对称 | 量化区间关于 0 对称(如 -8~7),无需零点偏移,计算更快 |
group_size: 32 |
32 | 每 32 个权重一组,组内共享一个缩放因子——AWQ 的标准做法 |
strategy: group |
分组 | 确认采用 group-wise 分组量化策略 |
observer: mse |
MSE 观测器 | 用均方误差最优的方式搜索缩放系数,量化误差更小 |
dynamic: false |
静态 | 缩放因子在量化时离线算好,推理时无需动态计算 |
💡 为什么是 32 而不是 64/128?group_size 越小精度越好、但缩放因子占的体积越多。32 是社区验证过的精度/体积平衡点,也是 AWQ 的默认推荐值。
量化落地后的痕迹可以在 model.safetensors.index.json 里看到:每个 Linear 权重都变成了 weight_packed(打包后的 4bit 整数)+ weight_scale(每组缩放因子)+ weight_shape(原始形状)三件套。
四、targets 与 ignore:谁被量化,谁被豁免
targets: [Linear]
ignore: [lm_head, model.embed_tokens, 're:.*input_layernorm$',
're:.*post_attention_layernorm$', model.norm, 're:.*mlp.gate$']
targets: [Linear]:只对线性层(注意力投影、专家 MLP 的 gate/up/down 投影)下手,因为它们占了模型绝大多数的参数量和计算量;ignore(豁免清单):lm_head/model.embed_tokens:词嵌入与输出层,参数量大但对精度敏感,保留原精度;- 各层
input_layernorm/post_attention_layernorm/model.norm:LayerNorm 权重,本来就极小,量化无意义; re:.*mlp.gate$:MoE 路由专家选择器(router gate)——这是最关键的一刀。Qwen3-Coder-30B-A3B 是 MoE 架构(128 个专家、每 token 激活 8 个),路由层决定"哪个专家处理哪个 token",一旦量化出错,专家分配就会错乱,必须保持全精度。
这份 ignore 列表在 config.json 的 quantization_config.ignore 中被固化展开成 48 层的完整层名,与 recipe.yaml 的正则一一对应。
五、mappings 平滑规则:AWQ 保精度的核心 🔧
mappings:
- smooth_layer: re:.*input_layernorm$
balance_layers: ['re:.*q_proj$', 're:.*k_proj$', 're:.*v_proj$']
- smooth_layer: re:.*v_proj$
balance_layers: ['re:.*o_proj$']
- smooth_layer: re:.*post_attention_layernorm$
balance_layers: ['re:.*mlp.experts.*.gate_proj$', 're:.*mlp.experts.*.up_proj$']
- smooth_layer: re:.*up_proj$
balance_layers: ['re:.*down_proj$']
AWQ 的平滑思想是:在数据流相邻的两层之间"转移"数值尺度——把平滑层(如 LayerNorm)的系数调大、把接收层(如 q_proj)的系数调小,使进入敏感权重的激活值幅度变均匀,从而降低 4bit 量化误差。
这 4 组规则恰好覆盖了 Transformer 的每一条数据通路:
| 平滑层(smooth_layer) | 平衡对象(balance_layers) | 对应结构 |
|---|---|---|
input_layernorm |
q/k/v_proj | 自注意力前的输入归一化 |
v_proj |
o_proj | 注意力输出投影 |
post_attention_layernorm |
各专家的 gate/up_proj | FFN 前的归一化(专家 MLP 入口) |
up_proj |
down_proj | 专家 MLP 内部的上/下投影 |
注意第 3 条规则里的 mlp.experts.*:Qwen3-Coder 每个 decoder 层有 128 个专家,每条专家内部的 gate_proj/up_proj 都会参与平滑,这就是 AWQ 针对 MoE 模型的适配。
六、其余关键参数:duo_scaling、n_grid 与 offload
| 参数 | 值 | 作用 |
|---|---|---|
duo_scaling: true |
开启 | 启用双重缩放:给激活大的"敏感权重"单独的缩放保护,是 AWQ 区别于普通 4bit 量化的灵魂开关 |
n_grid: 20 |
20 | 平滑系数在 20 点网格上搜索最优值——点越多精度越好,但校准耗时越长,20 是常用的折中值 |
offload_device: cpu |
CPU | 量化时把大参数卸到内存,避免 GPU 显存不够(30B 模型校准必须用) |
校准所用的数据则记录在 README.md:官方使用了
nvidia/Llama-Nemotron-Post-Training-Dataset作为校准集,量化工具链为 llm-compressor。
七、量化成果验证:从 config.json 看最终产物
量化完成后,配置会写入 config.json,值得核对三个关键字段:
"quantization_config": {
"quant_method": "compressed-tensors",
"format": "pack-quantized",
"version": "0.12.3.a20251114"
}
quant_method: compressed-tensors:vLLM 等主流推理框架原生支持的量化格式,部署即插即用;format: pack-quantized:4 个 4bit 权重打包进 1 个字节,这就是"体积 ÷4"的物理实现;global_compression_ratio与kv_cache_scheme:本次未做 KV Cache 量化,注意力缓存仍按原精度运行。
最终成果一目了然:30.5B 参数的原模型 bf16 权重约 60 GB,量化后 4 个 safetensors 分片(model-00001-of-00004.safetensors ~ model-00004-of-00004.safetensors)合计仅 18.09 GB,且保留了 256K 长上下文、Agentic Coding 工具调用(解析逻辑见 qwen3coder_tool_parser.py)等全部能力。
八、总结:一张表带走全文 🎯
| 配置项 | 一句话解读 |
|---|---|
num_bits: 4 + symmetric: true |
4bit 对称整数量化,体积约 1/4 |
group_size: 32 + strategy: group |
每 32 权重一组共享缩放,AWQ 标准配置 |
observer: mse |
MSE 最优缩放,进一步压低量化误差 |
targets: [Linear] + ignore |
只量化大头 Linear;词嵌入、Norm、MoE 路由全豁免 |
mappings 四条平滑规则 |
覆盖注意力与专家 MLP 全通路,MoE 感知 |
duo_scaling: true |
双重缩放保护敏感权重,AWQ 的灵魂 |
n_grid: 20 + offload_device: cpu |
20 点网格搜索 + 内存卸载,兼顾精度与可行性 |
Qwen3-Coder-30B-A3B-Instruct-AWQ-4bit 的这份 recipe.yaml 是一份教科书级的 AWQ 量化配方:用 37 行配置,把 30.5B 的 MoE 代码模型压进 18 GB,同时通过平滑 + 双重缩放 + 路由豁免三板斧守住精度底线。理解了它,你也基本读懂了当今主流的 4bit 量化工程实践。🚀