读懂convert.log:Qwen3-Coder-30B-A3B-Instruct-GGUF的579个张量逐层拆解与转换原理

原创2026-11-11 15:56:462,211 阅读
文章标签:大模型代码模型模型量化本地部署人工智能

读懂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 的完整旅程:

  1. 579 个张量 = 48 层 × 12 张量 + 3 个全局张量,结构严谨可验证;
  2. MoE 架构体现在 ffn_*_exps 的第三维 128 个专家与 2048×128 的路由门中;
  3. 元数据记录了 262K 上下文、GQA 32/4 头配置与工具调用 chat template;
  4. Q8_0 与 Q4_K_M 均从同一份 BF16 派生,靠"专家激进压缩 + 敏感张量高精度"的混合策略实现 57 GiB → 30 GiB → 17 GiB 的三级瘦身。

下次你拿到任何 GGUF 仓库,只要找到 convert.log,按本文的"579 = 48×12+3"与"BPW 账本"两个抓手,几分钟就能看懂它的转换原理。

登录后查看全文
Qwen3-Coder-30B-A3B-Instruct-GGUF