d1a-e2b-it-qat-4bit的MLX 4-bit逐比特移植原理:276个int4层如何实现0.0反量化误差
d1a-e2b-it-qat-4bit的MLX 4-bit逐比特移植原理:276个int4层如何实现0.0反量化误差
d1a-e2b-it-qat-4bit 是一个运行在 Apple Silicon 上的 MLX 4-bit 量化决策模型,它基于 Google 的量化感知训练(QAT)权重,把 276 个 int4 线性层逐比特原样搬进 MLX 格式,实现 0.0 反量化误差。这篇文章用大白话讲清楚它的移植原理:为什么"直接拷贝"比"重新量化"更好,4-bit 分组量化到底怎么工作,以及模型文件里各部分的来历。
先搞懂两个概念:QAT 和普通 4-bit 量化有什么不同
大多数人接触到的"4-bit 模型"是这样做出来的:先有一个 bf16(16 位浮点)的完整模型,再把它"压"成 4-bit,这个过程叫训练后量化(PTQ)。压的时候每个权重都要四舍五入,舍入会累积误差,模型效果会掉。
而 d1a-e2b-it-qat-4bit 的底座 google/gemma-4-E2B-it-qat-w4a16-ct 走的是另一条路——QAT(Quantization-Aware Training,量化感知训练):
| 对比项 | 普通 PTQ 量化 | QAT(本项目的做法) |
|---|---|---|
| 什么时候定权值 | 训练完之后压 | 训练过程中就按 int4 来学 |
| 4-bit 值怎么来 | 从 bf16 舍入得到 | 模型自己学出来的整数值 |
| 额外舍入误差 | 有 | 无——权重天生就是 int4 |
| 命名含义(w4a16) | 权重 4-bit、激活 16-bit | 相同 |
QAT 的产物里,权重本身就是 int4 整数加一组缩放参数,根本不存在一个"更精确的 bf16 原版"需要你去压。这正是"逐比特移植"成为可能的原因:既然权重天生就是整数,那把它原样搬走,一个比特都不会变。
4-bit 分组量化:每 32 个权重配一套"尺子"
MLX 里的 4-bit 存储采用分组仿射量化(affine),本项目在 config.json 中声明了这套规则:
- group_size = 32:每 32 个 int4 权重为一组;
- 每组配一个 **scale(标度)**和一个 bias(零点偏移),均以 bf16 存储;
- 还原时:
权重 ≈ scale × (int4 值 + bias)。
可以把它理解成:32 个格子共享一把尺子,整数只记录"第几格",尺子负责还原真实大小。这样 32 个 bf16 权重占 64 字节,换成 int4 后只需 16 字节加 4 字节参数,体积大约压到原来的 1/3。
这套规则在 d1a_config.json 的 quantization 字段里也有完整记录,其中 grid: "ct-int4" 表示权值网格与 Google 的 QAT 检查点完全一致。
276 个 int4 层是从哪里来的
打开 model.safetensors.index.json 的权重映射表可以数出来:底座 Gemma 4 E2B-it 共有 35 个隐藏层,其中带缩放参数的线性层恰好是 276 个,分布为:
- 每层的 7 个主干线性层 × 35 层 = 245 个(
q_proj、o_proj、mlp.gate_proj、mlp.up_proj、mlp.down_proj、per_layer_input_gate、per_layer_projection); k_proj与v_proj各 15 个(仅部分层量化);- 1 个
per_layer_model_projection。
245 + 30 + 1 = 276,与 README 声称的数量完全吻合。
除了这 276 个线性层,还有 2 张嵌入表(embed_tokens 与 embed_tokens_per_layer)也量化成了 4-bit,但用的是 group_size = 64 的分组——QAT 只负责线性层的 32 分组,嵌入表是发布方自己量化的。改用 64 分组后体积再小 0.17 GB,各测试集精度基本不变(hard-v1 71.1 → 71.1,documents-v1 86.8 → 86.8)。
最终整个文本主干只有 model.safetensors 2.7 GB(4.6B 参数),加上 media/ 目录下 1.0 GB 的视觉/音频编码器(保持 bf16),全部装进 Apple Silicon 的统一内存。
0.0 反量化误差是怎么做到的:不量化,只搬运
关键就在"逐比特"三个字。传统移植流程是:
- 拿到 bf16 权重 → 2. 重新分组 → 3. 重新计算 scale/bias → 4. 重新舍入为 int4。
每一步都可能引入新的舍入。而本项目的做法是跳过全部重算:
- 直接读取 QAT 检查点里已经打好的 int4 packed words(打包后的整数);
- 连同每组的 scales 和 biases 原封不动写入 MLX 的 safetensors;
- 反量化公式
scale × 整数与 Google 训练时用的完全一致。
因为一个字都没重写过,所以做逐层比对时,276/276 个量化线性层的"词(整数)、标度、偏置"三方全部相同,反量化误差就是 0.0。这不是"误差很小",而是"根本没有发生量化"。
为什么 D1A 适配层必须跟着重训
既然主干"一个比特都没变",为什么还要重训适配层?因为 QAT 权重和 bf16 权重并不相同——两者逐元素余弦相似度只有 0.992。旧的 v0.6 适配层是配合 bf16 主干调的,原样搬过来后精度直接掉了:
| v0.6 适配层放在 | hard-v1 | devtools-v1 | documents-v1 |
|---|---|---|---|
| bf16 主干(原版) | 0.689 | 0.709 | 0.862 |
| 本 QAT 主干(未重训) | 0.669 | 0.683 | 0.857 |
所以适配层在 QAT 主干上重训了一轮:主干冻结在 QAT 检查点的值上(按 scale × 整数 精确反量化),2,929 步,在 M1 Max 上跑了 12.5 小时。重训后 22 个测试集合并 +0.40,PR 严重度 +3.5,每次决策还快 11%(延迟比 0.89),整体替换了旧版 v0.6。
重训后的适配层以 LoRA(rank 16,97 MB)形式放在 adapter/ 中未合并,关掉适配层它就是一个能聊天的 Gemma 4 E2B-it QAT;head.safetensors 则是指向头,配合 d1a_config.json 里拟合出的校准温度 1.55(把预期校准误差 ECE 从 0.064 压到 0.018),让模型对每个选项给出的概率更"靠谱"。
文件都放在哪里
| 文件 | 作用 |
|---|---|
| model.safetensors / model.safetensors.index.json | 2.7 GB 的 4-bit 主干与权重索引(276 个 int4 层 + 2 张嵌入表) |
| config.json | 模型架构与量化配置(group_size、bits、affine 模式) |
| d1a_config.json | D1A 格式声明:LoRA 16、温度 1.551、grid: ct-int4、温度拟合记录 |
| adapter/adapter_model.safetensors | 在 QAT 主干上重训的 LoRA 适配层 |
| head.safetensors | 指向头(pointer head) |
| media/ | 视觉与音频编码器(bf16,1.0 GB)及其配置 |
| tokenizer.json / chat_template.jinja | 分词器与对话模板 |
快速跑起来
依赖 d1a 包(含 MLX 后端)后,一条命令即可在本机起服务:
python -m d1a.serving.serve --run mlx-community/d1a-e2b-it-qat-4bit --port 8009
随后通过 /v1/systemone 做决策、/v1/chat/completions 聊天(此时自动关闭适配层)、/v1/systemone/media 处理照片、语音和视频,详见 README.md 中的示例请求。
小结
d1a-e2b-it-qat-4bit 的核心思路一句话就能讲完:QAT 权重天生是 int4,所以不量化、只搬运。276 个线性层的打包整数、标度和偏置逐比特照抄,换来 0.0 的反量化误差;再配合在 QAT 主干上重训的适配层与 1.55 的校准温度,最终得到一个 2.7 GB、比旧版快 11% 的 MLX 4-bit 决策模型。对新手来说,这也是一个值得记住的模式:当源权重本身就是量化格式时,"精确搬运"永远优于"重新压缩"。