Module 7：模型选择 — Qwen2 / Qwen2.5

把抽象 transformer 落到一个真实 checkpoint：读懂 Qwen2 的 config、张量命名、权重格式与显存规模。

7.1Qwen2 decoder 架构与 config.json

前几章使用的是 decoder-only transformer 的通用描述。实现推理引擎时，还必须选择一个具体模型族，因为权重名称、config 字段、attention head 划分、normalization 细节都会进入代码。本项目以 Qwen2 / Qwen2.5 为目标：公开 checkpoint 容易取得，0.5B 规模适合调试，同时保留了现代 LLM 中常见的 GQA、RoPE、RMSNorm、SwiGLU、QKV bias 与 tied embeddings。

xinfer-core 中的 QwenConfig 只保留推理需要的字段；xinfer-loader 从模型目录读取 config.json 并反序列化为该结构。以仓库中的 Qwen2.5-0.5B-Instruct 为例，关键配置如下：

这些字段直接决定运行时 buffer 的大小。单个 attention head 的维度为：

因此 Q 的 shape 是 $[S,14,64]$。GQA 使 K/V 只保留 2 个 KV head，shape 为 $[S,2,64]$。代码中的 head_dim() 与 kv_group_size() 正是从这些字段推导得到，而不是写死在 kernel 或模型逻辑中。

7.2Qwen2 的关键结构

Qwen2 的 decoder layer 仍由 attention、MLP、residual 与 normalization 组成。与抽象公式相比，工程实现需要特别处理以下结构，否则张量 shape 或权重名称会与 checkpoint 不一致。

RMSNorm

Qwen2 使用 RMSNorm。配置中的 rms_norm_eps 进入每一层的 input layernorm、post-attention layernorm，以及最终的 model.norm.weight：

RoPE 与 rope_theta

Qwen2 对 Q/K 使用 RoPE。rope_theta 给出频率基底，0.5B Instruct checkpoint 中该值为 1,000,000：

GQA head counts

Qwen2.5-0.5B 有 14 个 query heads，但只有 2 个 KV heads，因此每个 KV head 被 7 个 query head 共享：

这样可以减少 K/V projection 输出维度和 KV cache 规模，同时保留较多 query heads。

QKV bias

许多 Llama 系模型的 Q/K/V projection 不带 bias；Qwen2 的 Q、K、V projection 带 bias：

因此模型装配必须读取 q_proj.bias、k_proj.bias、v_proj.bias。xinfer-model 的 CPU reference 与 GPU forward 都按这些名称加载 bias；忽略 bias 会使 logits parity 失效。

SwiGLU

MLP 使用 gate/up/down 三个矩阵，激活函数由 config 中的 hidden_act: "silu" 对应到 SiLU：

7.3Tied vs untied LM head 与词表规模

tie_word_embeddings=true 表示输出 LM head 与输入 embedding table 共享同一份权重：

对 Qwen2.5-0.5B，这一张表的元素数为：

若以 f16 存储，大小为：

按 MiB 计约为 260 MiB。tied embeddings 使这份权重同时用于 token embedding 与 logits projection；xinfer-model 在 tie_word_embeddings 为 true 或 checkpoint 中没有 lm_head.weight 时，使用 model.embed_tokens.weight 作为 LM head。

7.4权重格式：safetensors、dtype 与 memory mapping

HuggingFace checkpoint 通常由 config.json、tokenizer.json 和一个或多个 *.safetensors 文件组成。safetensors 的文件头记录 tensor 名称、dtype、shape 与 byte offset，数据区连续存放原始 bytes。xinfer-loader 遍历模型目录中的全部 *.safetensors 文件，用 memmap2 建立 memory mapping，再交给 safetensors 解析。

加载阶段支持 f32、f16、bf16 三种权重 dtype，并统一转换为 f32 host tensor。GPU 侧再根据用途选择存储格式：decoder layer 中 q/k/v/o 与 gate/up/down 七类线性层权重以 f16 上传，bias 与 norm weight 保持 f32；shared LM head 也以 f16 上传。这样可以保留 CPU reference 的简单性，同时降低 GPU 权重显存和带宽。

7.5选择一个合适大小：为什么从 0.5B 开始？

教学模型需要同时满足两个约束：结构必须接近实际 LLM，规模又要允许频繁运行 parity test、GPU kernel test 与端到端生成。Qwen2.5-0.5B 有 24 层、真实 tokenizer、真实 Qwen2 结构，适合作为从 CPU reference 迁移到 D3D12 backend 的基线。README 中的运行示例显示，f16 权重常驻 GPU 后，0.5B checkpoint 的 GPU resident weights 约为 942 MiB。

随模型规模增长，主要增长项包括：

• 层数 $L$：所有 per-layer 权重、KV cache 都随 $L$ 线性增长；
• hidden size $H$：线性层权重通常随 $H^2$ 或 $H\cdot I$ 增长；
• intermediate size $I$：MLP gate/up/down 权重随 $H\cdot I$ 增长；
• 词表大小 $|V|$：embedding / LM head 随 $|V|\cdot H$ 增长；
• 上下文长度 $T$：KV cache 随 $T$ 线性增长。

这些量的增长方式决定了课程中的实验顺序。先在 0.5B 上建立正确性与性能测量，再讨论 layer streaming、copy queue 与更大模型，比直接从大模型开始更容易定位错误。

Lab 7解析真实 config 并检查 safetensors

本实验要求你写一个小工具，读取模型目录中的 config.json 和 model.safetensors，输出关键字段和若干 tensor 的 shape。若 checkpoint 被拆成多个 *.safetensors 文件，也应逐个读取并合并名称列表。

# 示例输出（格式可自定义）
model_type: qwen2
hidden_size: 896
layers: 24
heads: 14
kv_heads: 2
head_dim: 64
vocab_size: 151936

model.embed_tokens.weight: [151936, 896]
model.layers.0.self_attn.q_proj.weight: [896, 896]
model.layers.0.self_attn.k_proj.weight: [128, 896]
model.layers.0.mlp.gate_proj.weight: [4864, 896]

你也应该验证这些 shape 能从 config 推导出来。例如：

小结

本章把通用 decoder-only transformer 约束到 Qwen2 / Qwen2.5 的具体实现。config.json 决定 hidden size、层数、head 数、GQA 比例、词表大小、RoPE 基底和 tied embeddings；safetensors 提供可 memory-map 的权重布局，loader 将 f16/bf16/f32 权重转换为 f32 host tensor；GPU 路径再将主要线性层权重和 LM head 压到 f16。选择 0.5B 模型的目的在于：保留真实结构，同时控制显存、加载时间和调试成本。