Module 14：Phase 5 — 运行大于 VRAM 的模型：Layer Streaming

当全部权重无法常驻显存时，将 decoder layer 从 host RAM 流式上传到少量 GPU slot，并用 copy queue 与 compute overlap。

14.1Residency problem：权重不一定都放得下

Resident GPU forward 在实现上最直接：加载时上传所有权重，推理期间不再移动。它的限制也很明确：模型规模增大后，权重本身可能超过可用 VRAM；即使权重勉强放下，KV cache、activation 与临时 buffer 仍需要显存预算。

一个粗略估算：

Decoder-only 模型的权重天然按 layer 组织。一次 forward 中，layer 按 0 到 $L-1$ 顺序执行；第 $i$ 层计算完成后，本轮 forward 不再读取它的权重。这个访问模式允许只在 GPU 上保留少量 layer slots，并在层间复用这些 slots。

14.2Per-layer weight streaming

QwenModel::load_streaming 实现 per-layer weight streaming。完整 ModelWeights 保留在 host RAM；GPU 只分配一个有限的 LayerSlot 池。其基本策略如下：

• 完整权重保存在 CPU host RAM / mmap 文件中；
• GPU 上只分配 $N$ 个 LayerSlot；
• 第 $i$ 层执行前，把第 $i$ 层权重上传到 slot $i\bmod N$；
• 执行完第 $i$ 层后，这个 slot 可以被第 $i+N$ 层重用。

14.3Copy queue 与 persistently-mapped staging buffer

D3D12 default heap 中的权重 buffer 不能直接由普通 CPU 内存填充。xinfer-dml::upload 为 streaming 提供 UploadHeap 与 CopyEngine：前者是 persistently-mapped upload heap，后者拥有 D3D12 COPY-type command queue、command list 与 fence。上传流程如下：

1. 创建 upload heap staging buffer，并保持 mapped；
2. CPU 把 layer 权重写入 staging；
3. copy queue 记录 CopyBufferRegion，从 staging 拷贝到 GPU default heap；
4. copy queue signal fence；
5. direct queue 在使用该 layer 前等待对应 fence。

14.4Double-buffering：上传与计算重叠

若每层都串行为“上传 → 等待 → 计算 → 下一层”，streaming 的时间会接近上传时间与计算时间之和。Double-buffering 将上传放到 dedicated copy queue：direct queue 计算当前层时，copy queue 预取未来会使用的层。

如果 GPU 有 $N$ 个 slots，那么执行完第 $i$ 层后，就可以让 slot $(i\bmod N)$ 开始上传第 $i+N$ 层：

当执行推进到第 $i+N$ 层时，该层权重通常已经在对应 slot 中，direct queue 只需等待该 slot 的 fence 达到目标值。load_streaming 将 resident pool clamp 到至少 2 个 slots，以保证存在基本的双缓冲机会；若传入的 pool 覆盖全部层，则退回 resident 加载。

14.5Cross-queue resource-state correctness

D3D12 的 copy queue 与 direct queue 是独立队列。copy queue 完成 layer slot 写入后，direct queue 才能把这些 buffer 作为 shader resource 读取。因此 streaming 的正确性包含两个层面：

• **同步正确：**direct queue 使用 slot 前，必须等待 copy queue signal 的 fence。
• **状态正确：**copy queue 写入后，buffer 的 tracked state 要回到合适的基础状态，后续 direct queue 再 transition 到 SRV。

StreamingLayers::ensure 会等待 slot 对应的 copy fence，然后对该层所有 buffer 调用 DmlBuffer::assume_common()。这一步把跨队列写入后的资源状态重新纳入本地状态跟踪，使后续 direct queue 能从 COMMON 过渡到 SRV 等实际使用状态。

Lab 14用小 slot pool 证明 streaming == resident

本实验不依赖超大模型。使用 synthetic 6-layer Qwen2 checkpoint，并将 resident pool 设为 2 个 slots，就会强制发生 slot reuse。测试目标是证明 streaming 只改变权重驻留方式，不改变模型计算结果。真实 CLI 中对应开关为 --stream-layers <N>，表示 resident pool 的 layer 数。

# 关键验收测试
cargo test -p xinfer-model --test forward_parity -- --nocapture

# 重点观察：
streaming_matches_resident ... ok
streaming vs resident max abs diff = 0

正确性目标：

测试输出中的 streaming vs resident max abs diff = 0 表明上传、slot 轮转、fence 等待与资源状态处理均与 resident 路径一致。

小结

本章讨论的核心问题是显存 residency。Resident 模式把所有 decoder layer 权重常驻 GPU；streaming 模式把完整权重保留在 host RAM，只在 GPU 上维护少量可复用 LayerSlot。UploadHeap、CopyEngine、copy queue fence 与 assume_common() 共同保证跨队列上传的顺序和资源状态；double-buffering 使未来层的上传尽可能与当前层计算重叠。streaming_matches_resident 的 diff=0 是该路径的主要正确性证据。