colibri引擎内部揭秘:qwen36-35b-a3b-colibri-i4-gs64分组缩放GEMV(matmul_q_gs)实现原理与gs64-ab分支开发者指南
colibri引擎内部揭秘:qwen36-35b-a3b-colibri-i4-gs64分组缩放GEMV(matmul_q_gs)实现原理与gs64-ab分支开发者指南
本文拆解 colibri 引擎的分组缩放 GEMV 内核 matmul_q_gs:模型容器 qwen36-35b-a3b-colibri-i4-gs64 为每个专家权重的每 64 个输入元素保留一个 f32 缩放因子(expert_gs=64,即 gs64),在不改变解码速度的前提下,把首 token logit 误差降低了约 44%。文末附 gs64-ab 分支的完整上手步骤与容器文件结构导读。
📦 一、这个模型容器到底是什么
Qwen3.6-35B-A3B 是一个 35B 级别的 MoE 大模型:每层 256 个专家,每个 token 只激活其中 8 个。本仓库就是它为 colibri 引擎准备的自包含 int4 推理容器:
- 内置 tokenizer、扁平化
config.json,一个目录即可运行; - 40 个权重分片 + 1 个全局参数文件;
- 相比 per-row(每行一个缩放因子)的姊妹版本,gs64 把缩放粒度细化到每 64 个输入元素一个 f32 scale,是官方定位的"更高精度"版本。
关键参数速查表
| 参数 | 值 | 含义 |
|---|---|---|
n_layers |
40 | 模型层数(每 4 层一个 full attention 层) |
num_experts |
256 | 每层专家数量 |
topk |
8 | 每 token 激活专家数 |
moe_inter |
512 | 专家中间层宽度 |
ebits |
4 | 专家权重按 int4 量化存储 |
expert_gs |
64 | 分组缩放粒度,即 gs64 |
其中 expert_gs 就写在 qwen36_meta.json 里,它是 colibri 引擎判断"该走哪条量化路径"的唯一开关。
🎯 二、为什么"分组缩放"比 per-row 更准
int4 量化只能存 4 位整数,必须靠缩放因子(scale)把整数映射回真实数值。两条路线的差别在于 scale 的粒度:
| 方案 | scale 粒度 | 存储布局 | 精度表现 |
|---|---|---|---|
| per-row | 每行 1 个 f32 | 每行 1 个 scale | 基线 |
| gs64(本容器) | 每 64 个输入元素 1 个 f32 | [O][I/gs] 行主序 |
更高 |
打个比方:per-row 是用"一把长尺"量整行权重,遇到个别离群值整行都被压扁;gs64 则是"每 64 个元素配一把小尺",量得更贴合实际分布。代价是 scale 数量变多,但 scale 是 f32 且数量仅为权重元素的 1/64,所以整个容器只从 20 GB 增大到约 22 GB(+10%)。
详细的容器格式说明见官方文档 README.md。
⚙️ 三、matmul_q_gs 内核实现原理
LLM 解码阶段每一步只做一次矩阵-向量乘(GEMV),这正是量化开销最敏感的地方。colibri 的 matmul_q_gs 内核大致分四步:
- 解包:每字节里打包着 2 个 4 位权重,按
ebits=4拆出整数; - 取 scale:当前元素属于哪一组(间隔 64),就去
[O][I/gs]布局里取对应的 f32 scale——每 64 次乘法才查一次,几乎不增加访存; - 反量化 + f32 累加:
整数 × scale在 f32 下累加,避免精度在低位上丢失; - 输出:得到该专家这一行的输出向量,交给后续的 top-8 专家加权。
两个工程细节值得注意
- 零配置自动切换:引擎启动时读取 qwen36_meta.json 里的
expert_gs,发现是 64 就自动走matmul_q_gs分组缩放路径,不需要任何额外命令行参数; - 解码速度不变:scale 查找被摊薄到每 64 个元素一次,内存访问模式与 per-row 几乎一致,所以官方 A/B 中 decode 速度没有回退。
📊 四、实测精度:首 token 误差降约 44%
官方在与 int8 锚点模型的受控 A/B 测试(同基座、同引擎、4 条推理类 prompt)中给出:
| 指标(均值,4 prompts) | per-row int4 | gs64 int4 |
|---|---|---|
| 首 token logit 余弦相似度 | 0.98777 | 0.99313 |
| KL 散度 | 0.1091 | 0.0795 |
另外,贪心生成 512 token 的长输出测试中,两种容器均无退化循环——分组缩放在这里带来的确实是纯质量提升,而非修复跑飞问题的补丁。测试细节见 README.md。
🚀 五、gs64-ab 分支三步上手
matmul_q_gs 目前位于 colibri 引擎的 gs64-ab 分支(尚未合入上游主线),per-row 容器才是当前 PR 默认。三步跑起来:
- 拉取分支并编译:在 colibri 引擎仓库检出
gs64-ab分支后执行make -C c qwen36;想用 GPU 档位就追加CUDA=1 CUDA_ARCH=native; - 下载模型容器:用
huggingface_hub.snapshot_download('Kreuzzelg/qwen36-35b-a3b-colibri-i4-gs64')拉取本仓库,得到容器目录路径$SNAP; - 运行推理:
SNAP=$SNAP N_NEW=200 OMP_NUM_THREADS=<物理核心数> ./c/qwen36 256 4 prompt.txt
完整命令序列以 README.md 为准。
🗂️ 六、容器文件结构导读
| 文件 | 作用 |
|---|---|
| qwen36_meta.json | 引擎读取的模型元信息,expert_gs: 64 在此声明(关键行) |
| config.json | 扁平化模型配置:256 专家、top-8、40 层、int4(MoE 参数段) |
| config.hf.json | 上游 HF 原始架构配置(含视觉塔定义) |
| tokenizer.json | 内置分词器,容器自包含的关键 |
| model-00000.safetensors ~ model-00039 | 40 个专家/注意力权重分片(int4 打包 + .qs scale 数组) |
| model-globals.safetensors | 全局参数(词表嵌入等非分片部分) |
| README.md | 官方说明:选型建议、A/B 数据、运行步骤 |
👩💻 七、开发者指南:gs64 改造的三个检查点
如果你在给自己的模型做同类量化改造,对照本容器检查三件事即可:
- meta 声明:
qwen36_meta.json必须写入expert_gs,引擎靠它路由到matmul_q_gs; .qs数组布局:专家 scale 数组为[O][I/gs]行主序、f32 类型——O是输出行、I/gs是每行的分组数,per-row 容器则是每行 1 个,改错布局会静默出乱码;- 用 int8 锚点做 A/B:以"首 token logit 余弦 + KL 散度"双指标对照 int8 锚点,比裸读困惑度更可靠,本容器 44% 的误差降幅就是这么测出来的。
❓ 八、常见问题
Q:不切 gs64-ab 分支能直接用吗?
不能。matmul_q_gs 在 gs64-ab 分支上,主线 colibri 只有 per-row 路径,会读不懂 gs64 容器的 scale 布局。
Q:per-row 和 gs64 到底选哪个? 20 GB 显存/内存够用、追求最省事 → per-row(PR 默认);追求更好质量、能接受 +10% 体积 → 本 gs64 容器,解码速度不变。
Q:为什么 scale 变多,容器只大 10%? scale 数量是权重元素的 1/64 且为 f32,相对 int4 权重本体只是零头,增量几乎全来自 scale。
一句话总结:qwen36-35b-a3b-colibri-i4-gs64 用"每 64 元素一个 f32 scale"的分组缩放 GEMV(matmul_q_gs),以 10% 的体积代价换来了约 44% 的首 token 误差下降——想要更准的 int4 MoE 推理,记得把 colibri 切到 gs64-ab 分支即可。