读懂convert.log:Qwen3-Coder-30B-A3B-Instruct-GGUF的579个张量逐层拆解与转换原理
读懂convert.log:Qwen3-Coder-30B-A3B-Instruct-GGUF的579个张量逐层拆解与转换原理
本文带你逐行读懂 Qwen3-Coder-30B-A3B-Instruct-GGUF 仓库里的 convert.log:这份 2471 行的日志完整记录了该 MoE 大模型从 Hugging Face 权重转换为 GGUF 格式并量化的全过程——579 个张量是如何逐层导出、以何种精度保存、又如何派生出 BF16、Q8_0、Q4_K_M 三种体积版本的。
📦 convert.log 是什么:一条完整的 GGUF 转换流水线
打开仓库,除了三个 .gguf 文件与 README.md,还有一份容易被忽略的 convert.log。它就是整条自动转换流水线的"黑匣子记录仪",共三个大阶段:
| 阶段 | 工具 | 日志位置 | 产物 |
|---|---|---|---|
| ① 权重导出 | convert_hf_to_gguf.py |
第 5–881 行 | BF16 版 GGUF(61.1G) |
| ② 第一次量化 | llama-quantize |
第 883–1513 行 | Q8_0 版(约 30 GiB) |
| ③ 第二次量化 | llama-quantize |
第 1514–2338 行 | Q4_K_M 版(约 17 GiB) |
最终产物正是仓库里的三个文件:Qwen3-Coder-30B-A3B-Instruct-BF16.gguf、Qwen3-Coder-30B-A3B-Instruct-Q8_0.gguf、Qwen3-Coder-30B-A3B-Instruct-Q4_K_M.gguf。
启动命令在日志第 5 行,核心参数一目了然:
python3 llama.cpp/convert_hf_to_gguf.py ./model-temp-... --outtype bf16 \
--outfile ./upload-.../Qwen3-Coder-30B-A3B-Instruct-BF16.gguf \
--model-name Qwen3-Coder-30B-A3B-Instruct
随后脚本识别出模型架构 Qwen3MoeForCausalLM,并按 model.safetensors.index.json 的索引把 16 个 safetensors 分片逐一读取(第 8–24 行),这就是 30B 参数需要分片存储的原因。
🧮 579 个张量的数学:48 层 × 12 + 3 = 579
日志中最密集的 第 27–605 行 共 579 行张量导出记录,其数量并非巧合,而是一道精确的算术题:
48 个 Transformer 层(blk.0 ~ blk.47)× 每层 12 个张量 = 576,再加 3 个全局张量 = 579 ✅
3 个全局张量负责"输入与输出":
| 张量 | 形状 | 作用 |
|---|---|---|
token_embd |
2048 × 151936 | 词表 151936 个 token 的嵌入矩阵(第 27 行) |
output |
2048 × 151936 | 最后一层 LM Head,把隐藏态映回词表 |
output_norm |
2048 | 输出前的全局 RMSNorm |
任意一层的 12 个张量高度规整,以 blk.10 为例(第 142–153 行):
blk.10.attn_norm.weight --> F32, shape = {2048}
blk.10.ffn_down_exps.weight --> BF16, shape = {768, 2048, 128}
blk.10.ffn_gate_exps.weight --> BF16, shape = {2048, 768, 128}
blk.10.ffn_up_exps.weight --> BF16, shape = {2048, 768, 128}
blk.10.ffn_gate_inp.weight --> F32, shape = {2048, 128}
blk.10.ffn_norm.weight --> F32, shape = {2048}
blk.10.attn_k_norm.weight --> F32, shape = {128}
blk.10.attn_k.weight --> BF16, shape = {2048, 512}
blk.10.attn_output.weight --> BF16, shape = {4096, 2048}
blk.10.attn_q_norm.weight --> F32, shape = {128}
blk.10.attn_q.weight --> BF16, shape = {2048, 4096}
blk.10.attn_v.weight --> BF16, shape = {2048, 512}
🔍 逐层拆解:每个张量在 MoE 架构中的角色
注意力组(7 个张量)
隐藏维度 2048,注意力头 32 个、每头维度 128,KV 头只有 4 个(GQA,8:1 压缩)。把形状"翻译"一下就很直观:
attn_q:2048 × 4096 → 4096 = 32 头 × 128,查询投影;attn_k/attn_v:2048 × 512 → 512 = 4 个 KV 头 × 128,键值投影;attn_output:4096 × 2048,注意力结果投影回隐藏维度;attn_q_norm/attn_k_norm:每头 128 维的 QK-Norm,稳定注意力分数。
MoE 专家与路由组(4 个张量)——30B 的"秘密"
第三维的 128 就是本层的 128 个路由专家,每个 token 只激活其中 8 个("30B 总参数、3B 激活"由此而来):
ffn_gate_exps/ffn_up_exps:2048 × 768 × 128,SwiGLU 的门控与上投影;ffn_down_exps:768 × 2048 × 128,下投影;ffn_gate_inp:2048 × 128,路由门——把 2048 维输入打分到 128 个专家,选出 top-8。
三个专家矩阵每层约 1.15G 参数,48 层 × 128 专家 ≈ 29.2B,这正是"30B"总参数的大头。
Norm 组与精度分配(BF16 vs F32)
注意一个规律:attn_norm、ffn_norm、attn_q/k_norm、ffn_gate_inp 这 6 个小张量全部从 torch.bfloat16 升为 F32 保存,而大矩阵保持 BF16。原因是归一化和路由打分对数值精度极其敏感,但参数量极小(每层仅几 MB),升为全精度几乎不占空间,却能避免精度损失。
⚙️ 元数据与分词器:藏在日志里的"模型身份证"
579 个张量写完后,第 606–628 行 写入 GGUF 头部的关键元数据:
| 元数据 | 值 | 含义 |
|---|---|---|
| context length | 262144 | 262K 上下文窗口 |
| embedding length | 2048 | 隐藏维度 |
| expert count / experts used | 128 / 8 | 路由专家数 / 每 token 激活数 |
| head count / kv head count | 32 / 4 | GQA 注意力头配置 |
| expert feed forward length | 768 | 专家中间维度 |
| rope theta | 10000000 | 位置编码基频 |
| tokenizer merges | 151387 | BPE 合并规则数 |
紧接着写入特殊 token(eos = 151645、bos/pad = 151643)和完整的 Jinja chat template,包括系统提示与函数调用(<tools>/<function>)格式——这是 Coder 模型支持工具调用的关键配置。日志第 613 行的 WARNING: Unknown RoPE type: default 属于无害告警(默认 RoPE 按 NONE 缩放处理),可以忽略。
⚡ 量化拆解:Q8_0 与 Q4_K_M 如何从同一份 BF16 派生
两份量化版本都以 BF16 版为输入,日志中的汇总数字是最直观的"体积账本":
| 版本 | 总大小 | 每参数位宽 BPW | 量化耗时 | 策略 |
|---|---|---|---|---|
| BF16 | 58259.80 MiB ≈ 57 GiB | 16.01 | — | 基线,全精度 |
| Q8_0 | 30973.40 MiB ≈ 30 GiB | 8.51 | 21.6 s | 所有 BF16 → q8_0 |
| Q4_K_M | 17149.40 MiB ≈ 17 GiB | 4.71 | 123.3 s | 混合精度,见下 |
Q8_0(第 883–1513 行):规则最简单,凡是 BF16 张量一律压成 8 位块量化。典型如 第 930 行:output.weight 从 593.50 MiB 降到 315.30 MiB,近乎减半;F32 小张量原样保留。
Q4_K_M(第 1514–2338 行):通过 --tensor-type 参数对张量"分组点菜"(第 1514 行):
llama-quantize --pure \
--tensor-type token_embd.weight=q8_0 \
--tensor-type '^output.weight=q8_0' \
--tensor-type attn_=q8_0 \
...BF16.gguf ...Q4_K_M.gguf Q4_K_M
- MoE 专家(
ffn_*_exps)走基础类型 q4_K:单个 384 MiB → 108 MiB(第 2399 行),是体积大头,激进压缩; - 嵌入、LM Head、注意力(
token_embd、output、所有attn_*)保持 q8_0,守护质量下限; - Norm 与路由门继续保留 F32。
这种"专家 4-bit + 敏感张量 8-bit"的混合策略,正是 Q4_K_M 能把 57 GiB 压到 17 GiB 却仍保持可用质量的核心原理。
🚀 快速阅读 convert.log 的实用技巧
不必通读 2471 行,抓住几个"路标"即可:
- 看流水线全貌:
grep -n "llama-quantize\|convert_hf_to_gguf" convert.log - 确认张量总数:
grep -n "n_tensors" convert.log→ 命中n_tensors = 579, total_size = 61.1G(第 750 行) - 看某一层结构:
grep -n "blk.25\." convert.log - 看量化成果:
grep -n "BPW" convert.log→ 三个版本的位宽一目了然(第 1509–1510 行、第 2334–2335 行) - 看进度终点:
grep -n "\[579/ 579\]" convert.log
✅ 小结
convert.log 用 2471 行日志讲清了 Qwen3-Coder-30B-A3B-Instruct 从 Hugging Face 权重到 GGUF 的完整旅程:
- 579 个张量 = 48 层 × 12 张量 + 3 个全局张量,结构严谨可验证;
- MoE 架构体现在
ffn_*_exps的第三维 128 个专家与 2048×128 的路由门中; - 元数据记录了 262K 上下文、GQA 32/4 头配置与工具调用 chat template;
- Q8_0 与 Q4_K_M 均从同一份 BF16 派生,靠"专家激进压缩 + 敏感张量高精度"的混合策略实现 57 GiB → 30 GiB → 17 GiB 的三级瘦身。
下次你拿到任何 GGUF 仓库,只要找到 convert.log,按本文的"579 = 48×12+3"与"BPW 账本"两个抓手,几分钟就能看懂它的转换原理。