colibri引擎内部揭秘:qwen36-35b-a3b-colibri-i4-gs64分组缩放GEMV(matmul_q_gs)实现原理与gs64-ab分支开发者指南

原创2026-11-09 13:45:331,961 阅读

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 内核大致分四步:

  1. 解包:每字节里打包着 2 个 4 位权重,按 ebits=4 拆出整数;
  2. 取 scale:当前元素属于哪一组(间隔 64),就去 [O][I/gs] 布局里取对应的 f32 scale——每 64 次乘法才查一次,几乎不增加访存;
  3. 反量化 + f32 累加:整数 × scale 在 f32 下累加,避免精度在低位上丢失;
  4. 输出:得到该专家这一行的输出向量,交给后续的 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 默认。三步跑起来:

  1. 拉取分支并编译:在 colibri 引擎仓库检出 gs64-ab 分支后执行 make -C c qwen36;想用 GPU 档位就追加 CUDA=1 CUDA_ARCH=native;
  2. 下载模型容器:用 huggingface_hub.snapshot_download('Kreuzzelg/qwen36-35b-a3b-colibri-i4-gs64') 拉取本仓库,得到容器目录路径 $SNAP;
  3. 运行推理:
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 改造的三个检查点

如果你在给自己的模型做同类量化改造,对照本容器检查三件事即可:

  1. meta 声明:qwen36_meta.json 必须写入 expert_gs,引擎靠它路由到 matmul_q_gs;
  2. .qs 数组布局:专家 scale 数组为 [O][I/gs] 行主序、f32 类型——O 是输出行、I/gs 是每行的分组数,per-row 容器则是每行 1 个,改错布局会静默出乱码;
  3. 用 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 分支即可。

登录后查看全文
qwen36-35b-a3b-colibri-i4-gs64