逐行解读Qwen3.6-27B-GPTQ-4bit的quantize.py:校准集构建、Token分桶与防OOM技巧
逐行解读Qwen3.6-27B-GPTQ-4bit的quantize.py:校准集构建、Token分桶与防OOM技巧
Qwen3.6-27B-GPTQ-4bit 是 270 亿参数多模态模型 Qwen3.6-27B 的 GPTQ 4-bit 量化版本,体积从约 50 GB 压缩到 21 GB,而困惑度只增加 1.95%。仓库里的 quantize.py 就是完成这次"无损压缩"的完整脚本:它构建混合校准集、按 Token 长度分桶采样、并用一系列技巧绕过显存不足(OOM)。本文带你逐段读懂这个脚本,让你能把它改造成自己模型的量化配方。
一、脚本整体结构:一段代码做了哪几件事?
先建立全局观。quantize.py 从上到下只干 4 件事:
| 阶段 | 代码位置 | 做什么 |
|---|---|---|
| 参数与日志 | quantize.py#L48-L74 | 解析 --bits,创建带时间戳的日志文件 |
| 环境配置 | quantize.py#L76-L92 | 设置 AMD GPU 显存分配策略、禁用 tokenizer 并行 |
| 校准集构建 | quantize.py#L121-L262 | 加载代码+文本双数据集,Token 分桶,均匀采样 |
| 量化与保存 | quantize.py#L280-L342 | 配置 GPTQ + FOEM,加载模型、量化、落盘 |
💡 量化不是"一刀切"地把数字变小。GPTQ 需要"喂"一批有代表性的校准数据(calibration data),用它统计每层权重的误差分布,再逐层求解最优的低位近似。校准集的质量直接决定量化后的模型质量。
核心配置一览
脚本开头的常量定义了整次量化的"配方":
MODEL_ID = "Qwen/Qwen3.6-27B" # 原始模型
NUM_CALIBRATION_SAMPLES = 256 # 校准样本数(从 512 降下来防 OOM)
MAX_SEQ_LENGTH = 2048 # 最长序列长度
GROUP_SIZE = 32 # GPTQ 分组大小
TOKEN_BINS = [(256, 512), (512, 1024), (1024, 1536), (1536, 2048)] # 4 个长度桶
- 256 个样本:注释里写得很直白——512 个样本时 FOEM 在第一层就会 OOM。因为 FOEM 要额外在每层保存一阶误差张量,吃掉了原本就紧张的显存余量,所以降到 groxaxo 验证过的 256。
- 4 个 Token 桶:把 256~2048 的序列长度切成 4 段,目标是让每个长度区间内的样本数量尽量均匀,避免校准数据全是短句子。
二、校准集构建:代码 + 通用文本双料混合
核心函数 prepare_calibration_dataset 负责造出最终喂给 GPTQ 的 256 条数据,流程分三步。
第 1 步:加载两个互补数据集
| 数据集 | 类型 | 作用 |
|---|---|---|
theblackcat102/evol-codealpaca-v1 |
代码指令数据 | 让量化后的模型保留代码能力 |
allenai/c4(英文子集) |
通用网页文本 | 覆盖日常语言分布 |
只校准代码数据会让模型"变代码机器",只用 C4 则代码能力下降。两者混合是通用场景下的稳妥选择。
第 2 步:预分词并过滤短样本
脚本对每条样本做两件事(见 quantize.py#L155-L179):
- 格式统一:代码样本被包装成
### Instruction: ... ### Response: ...的对话格式,模拟真实推理时的输入样式; - 提前 tokenize 计数:立刻用 tokenizer 算出每条样本的 Token 数,后续分桶直接用这个数,避免重复编码。同时过滤掉不足 50 字符的碎片样本。
⚠️ 注意一个成本细节:C4 数据只取前 50000 条就停止(quantize.py#L169)。分桶只需要"够用的池子",全量加载 100 多 GB 的 C4 纯属浪费。
第 3 步:样本入桶
for text, token_count, source in all_samples:
for bin_idx, (min_tok, max_tok) in enumerate(token_bins):
if min_tok <= token_count < max_tok:
binned_samples[bin_idx].append(text)
break
逻辑很简单:每条样本按 Token 数落入 256-512、512-1024、1024-1536、1536-2048 四个桶之一。
三、Token 分桶的关键:长桶"断档"怎么办?
真实数据分布是右偏的:几百 Token 的样本一抓一大把,接近 2000 Token 的长样本却稀少。如果长桶样本不够,直接后果就是"256 个样本里 250 个都是短句"——长上下文的量化质量就没有保障了。
脚本用"短样本拼接"(chaining)来补齐长桶(quantize.py#L194-L226):
create_chained_sample(min_tokens, max_tokens):
随机抽取样本 → 累加 Token 数 → 不超上限就拼接
用 "\n\n---\n\n" 分隔 → 拼到达到目标区间即返回
细节值得注意:
- 防死循环:连续 50 次抽到"放不进去"的样本就放弃这次尝试(quantize.py#L199);
- 超额生成:每个桶需要
256 // 4 + 1 = 65条,缺口就循环调用拼接函数补齐(最多尝试缺口 × 20 次); - 均匀采样收尾:每个桶最终只随机抽
64条(余数 0 分配给前几个桶),拼起来打散,得到长度分布均匀的 256 条校准集; - 自检日志:脚本还会重新编码前 100 条样本、统计它们落入各桶的数量并打印出来(quantize.py#L252-L260)——量化这种"跑完才知道结果对不对"的长任务,留好校验日志非常重要。
📌 分桶 + 均匀采样的本质:让 GPTQ 在"短对话"和"长文档"两种长度尺度上都拿到足够的误差信号,避免模型在某一长度区间量化后明显劣化。
四、防 OOM 技巧清单:27B 模型如何在 4 卡 32GB 上跑起来
27B 模型 BF16 权重约 50 GB,远超单卡 32 GB。脚本用了四招组合拳(quantize.py#L280-L306):
技巧 1:offload_to_disk=True 把不用的层挪去磁盘
量化是逐层进行的——当前层在 GPU 上计算,其余层完全可以待在磁盘里。开启后中间落盘用量约 50 GB(脚本注释里确认 / 盘有 622 GB 空闲,quantize.py#L286-L289),GPU 上永远只驻留"活跃层"。这是大模型量化最经典、也最该优先开的开关,quantize_config.json 里的 "offload_to_disk": true 就是它的最终记录。
技巧 2:auto_forward_data_parallel=False 关掉多卡数据并行
默认情况下 GPTQModel 会把每层副本同时复制到 4 张卡并行前向,速度快,但"每层 × 每卡"的显存占用叠加上 FOEM 的一阶误差缓存,第 0 层的 linear_attn.conv1d 就把 GPU 1 推过了 32 GB(quantize.py#L292-L298)。关闭后退化为单卡逐 batch 前向——牺牲速度换稳定,是量化脚本调试期的正确取舍。
技巧 3:校准样本数从 512 降到 256
FOEM 相比标准 GPTQ 要在每层额外保存一阶误差张量。512 样本时激活缓存 + 误差缓存把显存余量吃光,256 样本是"FOEM 能跑"的临界值。这也说明:开启新的量化增强项时,第一件事是重估校准集规模。
技巧 4:本地修补 FOEM 的设备错位 Bug
注释(quantize.py#L79-L81)提到 GPTQModel v6.0.3 的 foem.py:203 存在设备不一致问题:模型被 device_map='auto' 切分到多卡后,self.dXXT 和 Hinv 落在不同设备上。作者本地加了一行 .to(Hinv.device) 守卫,让 4 张卡都能用。这类"上游小 bug + 本地小补丁"是复现量化配方的常态,读懂注释能帮你少走很多弯路。
辅助配置
| 环境变量 | 作用 |
|---|---|
PYTORCH_HIP_ALLOC_CONF=expandable_segments:True |
AMD GPU 显存分段分配,缓解碎片化(quantize.py#L77) |
TOKENIZERS_PARALLELISM=false |
避免多进程下 tokenizer 警告刷屏 |
🔧 新手建议:如果照着本文复现时遇到 OOM,按这个顺序排查——① 开
offload_to_disk② 关auto_forward_data_parallel③ 降NUM_CALIBRATION_SAMPLES④ 降MAX_SEQ_LENGTH。
五、QuantizeConfig:一行看懂 4-bit + FOEM 配方
配置对象 quantize.py#L280-L306 是全文的"灵魂",参数与最终产物 quantize_config.json 完全对应:
| 参数 | 值 | 为什么这么设 |
|---|---|---|
bits |
4 | 目标位宽,配合 FOEM 才能做到纯 4-bit 不跳点 |
group_size |
32 | 每 32 个权重共享一组量化参数,精度与开销的平衡点 |
sym |
True | 对称量化,兼容性更好 |
true_sequential |
True | 真正逐层量化,配合磁盘卸载省显存 |
foem |
alpha=0.25, beta=0.2 |
groxaxo 的 GPTQ-Pro 生产配方;4-bit 才启用,8-bit 不用 |
mse |
2.0 | 激活值加权 MSE,专门压住 outlier 敏感层(down/output 投影) |
lm_head |
False | 输出头不量化,保持精度 |
脚本头部注释(quantize.py#L24-L28)记录了一段非常珍贵的"踩坑史":同一模型早期用 v5.7.1 无 FOEM 时,纯 4-bit 困惑度恶化 +8.45%;加 FP16 跳点降到 +2.38% 但体积反而比 8-bit 还大;引入 FOEM 后纯 4-bit 做到 +1.95%,且体积与 vLLM 内核兼容性全部保住。"少量化几个模块"是旧思路,"用误差补偿换精度"才是新思路。
哪些模块参与量化、哪些保持高精度,可在 README.md 的量化明细表中核对,并与 config.json 里的架构信息(64 层、248320 词表、256K 上下文)相互印证。
六、执行流程与产物
主流程只有 4 行核心调用(quantize.py#L314-L331):
model = GPTQModel.load(MODEL_ID, quant_config, trust_remote_code=True)
model.quantize(calibration_data, batch_size=1)
model.save(OUTPUT_DIR)
tokenizer.save_pretrained(OUTPUT_DIR)
几个值得记住的点:
batch_size=1:校准前向逐条进行,显存峰值最低(速度换空间);- 多模态无损保留:v6.0.3 上游的
Qwen3_5QModel定义会完整保留model.language_model.*前缀,视觉编码器(333 个张量)和 MTP 模块(15 个张量)保持 BF16 原样通过,无需任何"量化后补丁还原"步骤; - 容错设计:整段包在
try/except里,失败时打印完整堆栈并以非零码退出,方便日志回溯(quantize.py#L338-L342); - 最终产物:本仓库的 6 个分片(model-00001-of-00006.safetensors ~ model-00006-of-00006.safetensors)共约 21 GB,权重索引见 model.safetensors.index.json。
七、总结:这份脚本值得抄的 5 个习惯
- 混合校准:代码 + 通用文本双数据集,覆盖你的真实使用分布;
- Token 分桶 + 短样本拼接:让长短上下文在校准集中均匀分布;
- 磁盘卸载优先:
offload_to_disk是大模型量化的第一开关; - 显存吃紧时逐级降档:关多卡并行 → 降样本数 → 降序列长度,别先动量化配方;
- 把踩坑写进注释:样本数为什么是 256、并行为什么关掉、FOEM 参数为什么是 (0.25, 0.2)——注释里的"踩坑史"比参数本身更有价值。
掌握这套方法论后,无论是 7B 还是 70B 模型,你都能基于 quantize.py 快速改出自己的量化脚本,在"体积"和"精度"之间画出最优的权衡曲线。