Module 12：Phase 3 — 组装 Qwen2 模型

从算子实现进入完整模型实现：解析 Qwen2 权重命名，建立 CPU reference forward 与 resident GPU forward，并处理 DirectML/D3D12 调试问题。

12.1权重加载与 tensor-name 约定

Phase 3 的输入从单个 kernel 扩展为一组 HuggingFace Qwen2 safetensors。完整 forward 首先依赖稳定的权重寻址：同一层的 norm、attention 与 MLP 张量必须映射到确定的结构字段，否则后续算子即使各自正确，整网也会出错。

crates\xinfer-model\src\names.rs 将 HuggingFace 名称集中封装。第 $i$ 层的 12 个 layer tensor 按如下规范命名：

model.layers.{i}.input_layernorm.weight
model.layers.{i}.self_attn.q_proj.weight
model.layers.{i}.self_attn.q_proj.bias
model.layers.{i}.self_attn.k_proj.weight
model.layers.{i}.self_attn.k_proj.bias
model.layers.{i}.self_attn.v_proj.weight
model.layers.{i}.self_attn.v_proj.bias
model.layers.{i}.self_attn.o_proj.weight
model.layers.{i}.post_attention_layernorm.weight
model.layers.{i}.mlp.gate_proj.weight
model.layers.{i}.mlp.up_proj.weight
model.layers.{i}.mlp.down_proj.weight

另外还有全局权重：

model.embed_tokens.weight
model.norm.weight
lm_head.weight        # 若 tie_word_embeddings=false 才单独存在

gpu_model.rs 中的 LayerWeights 按同一顺序保存这些张量：input_ln, q_w, q_b, k_w, k_b, v_w, v_b, o_w, post_ln, gate_w, up_w, down_w。其中 q/k/v/o 与 gate/up/down 七个矩阵在 GPU 侧以 f16 存放，bias 与 norm weight 保持 f32。lm_head.weight 在 tie_word_embeddings=true 或文件缺失时回退到 model.embed_tokens.weight，这一点与 CPU reference 保持一致。

12.2CPU reference forward：整个网络的 oracle

CPU reference forward 位于 crates\xinfer-model\src\cpu_model.rs。它直接读取 ModelWeights 中的 f32 数据，按照 Qwen2 decoder-only 结构执行 embedding、逐层 attention/MLP、final RMSNorm 与 LM head。对输入 token 序列 $x_1,\ldots,x_S$，计算可概括为：

CPU reference 不追求速度，它的作用是提供 whole-network correctness oracle。单 kernel parity 只能证明某个局部算子满足给定输入输出关系；完整模型还可能在 tensor name、矩阵转置、bias、RoPE 绝对位置、GQA head 映射或残差连接上出错。整网 logits 对比把这些组装错误纳入同一验收口径。

12.3Resident GPU forward：权重留在 GPU 上

GPU forward 的第一版采用 resident 模式。QwenModel::load 在加载阶段上传全部 decoder layer 权重，以及 final norm 与 LM head；推理阶段只为当前 token 序列准备 embedding activation 与中间 buffer，不重复传输权重。该模式显存占用较高，但执行路径固定，适合建立 GPU 与 CPU 的整网 parity。

以一层为例，GPU forward 的顺序与 CPU forward 一致：

1. RMSNorm $X_\ell\rightarrow A$
2. Q/K/V linear + bias
3. RoPE(Q/K)
4. GQA attention
5. o_proj + residual add 得到 $U_\ell$
6. RMSNorm $U_\ell\rightarrow B$
7. gate/up linear、SwiGLU、down linear
8. residual add 得到 $X_{\ell+1}$

12.4调试 GPU hang：debug layer 与 device removed

GPU 错误通常不会以普通 Rust panic 的形式出现。常见现象包括 command queue 提交失败、readback 等待异常、进程挂起以及 device removed。D3D12 调试时至少需要两类信息：

• **D3D12 debug layer：**输出资源状态、binding、非法 API 使用等诊断信息。
• **GetDeviceRemovedReason：**当 device removed 时给出 HRESULT，例如 0x887A0005。

DmlDevice::new(true) 会尝试启用 D3D12 debug layer 与 GPU-based validation；drain_debug_messages 从 ID3D12InfoQueue 输出诊断消息；removed_reason 调用 GetDeviceRemovedReason 返回 HRESULT 字符串。它们使错误定位从“最终 readback 失败”前移到具体 API 使用、资源状态或 device removed 原因。

12.5解决 DirectML GEMM fault：改用自写 HLSL matmul

在本项目的 RDNA4 开发环境中，DirectML GEMM operator 在部分 shape 上会触发 device removed（HRESULT 0x887A0005），例如 $M=5,K=64,N=32$。单独隔离 shape/op 后可以确认，问题出现在特定硬件、驱动或 DirectML fallback 路径组合上。

因此模型主路径改为自写 HLSL matmul，DirectML operator wrapper 保留为 bring-up 与对照实现。后续优化集中在以下方向：

• f16 weights：q/k/v/o 与 gate/up/down 矩阵、LM head 以 f16 存放，降低显存与带宽压力；
• coalesced GEMV：改善权重读取与 reduction 访存模式；
• 2D dispatch grid：覆盖 Qwen2.5 的 151936 维 LM head 输出；
• GPU argmax：greedy decode 时只读回一个 token id，避免每 token 读回完整 logits。

Lab 12synthetic checkpoint：GPU logits 匹配 CPU reference

Lab 12 使用 synthetic tiny Qwen2 checkpoint 建立第一轮验收。该 checkpoint 的 hidden size、层数与词表都很小，但结构覆盖 GQA、QKV bias、SwiGLU 以及 tied/untied LM head，足以暴露模型组装错误，同时避免真实 0.5B 权重带来的加载与定位成本。

验收目标：

# 关键验收命令
cargo test -p xinfer-model --test forward_parity -- --nocapture

# 期望看到类似：
gpu_forward_matches_cpu ... ok
kv_cache_decode_matches_full ... ok
streaming_matches_resident ... ok

小结

本章完成从算子到完整 Qwen2 模型的过渡。核心实现包括：用 names.rs 固化 HuggingFace tensor 命名；用 CPU reference forward 作为整网 oracle；用 resident GPU forward 建立稳定的 GPU 路径；通过 D3D12 debug layer 与 GetDeviceRemovedReason 定位 device removed；在 DirectML GEMM 触发故障的 shape 上改用 shaders\linear*.hlsl 自写 matmul。Lab 12 的验收标准从单个 kernel 扩展到整网层面：GPU logits 必须与 CPU reference 匹配。