1314521gjy / ninfer-fusion-kvmem

# NInfer Fusion KVMem
**面向 Windows / NVIDIA GPU 的长上下文推理实验：以 KVMem 环为主线，融合流式（streaming）的「缺页可拉回、容量不够就按账让位」，让设备 KV 池可以小于逻辑上下文；配主机 KV 存储、按需检索与分段注入网关，多轮仍能复用上下文，超出池的题面走分片而不是静默错。**
本项目基于 NInfer `0.11.0` 线（KVMem 融合线；2026-10-19 的 sm86 / sm89 / sm120a 三份引擎由同一份源码各自编译），发布融合后的源码、复现记录和验证工具。它是 NInfer 的**下游衍生项目**；基座与第三方算法来源见 署名与改动声明。
> **2026-10-19 更新**：本版已并入 **KV 流式（streaming）机制**与 **Bonsai 27B ternary** 模型线，并给出 sm86 / sm89 / sm120a 三 arch 的实编记录与两套 8 GB 配方 —— 见下方 本次更新。下方其余章节记录的是旧线（PQ2 + dflash2）口径，两者不要混用。
> [!WARNING]
> 本版是**经过修复、比早期版本更稳定**的版本，**但仍存在一些已知 bug 未修复** —— 使用前请读 Bug 账本 与 修复清单（2026-10-19）。该说明不改变 Apache-2.0 许可。
获取引擎 · 编译指南 · 复现白皮书 · 实测回执 · 问题反馈
## 这个项目做了什么
长上下文会增加 KV 缓存占用。本项目将三个容量分别配置：
| 配置 | 含义 | 示例 |
|---|---|---|
| `--max-context` | 单序列的逻辑上下文上限 | 262,144 token |
| `--kv-capacity` | 设备端 KV 池容量 | 17,920 token（280 页） |
| `--host-kv-mib` | 主机端 KV 存储预算 | 16,384 MiB |
KVMem 环保留常驻窗口，将其他页降到主机层；需要时按内容相关性选页、搬回设备并装配注意力窗口。host-backed 复用与惰性物化让后续轮次可以继续使用主机驻留的检查点。按卡档位则为内核调度选择路由。
**小 KV 池不代表模型权重也能装进小显存**，也不代表检索与完整注意力在任意任务上质量等价。模型权重、运行工作区、投机头、CUDA Graph 和主机内存都需要单独预算。机制、容量公式与负控见 白皮书 §2–§4。
## 本次更新（2026-10-19）：把 streaming 的思路接进 KVMem
这一版做的是**架构融合**，不是修单个 bug：把流式（streaming）里"缺页可拉回、容量不够时谁让位"的机制接到 KVMem 环上，同时新增 **Bonsai 27B ternary**（`qwen3_5`）这条模型线。
**加了什么**
| 机制 | 做什么 | 解决什么 |
|---|---|---|
| 设备环池 + 宿主权威副本 | 设备只留窗口，页降到主机；需要时按内容相关性 H2D 检索回来 | 设备池可以远小于逻辑上下文，而不等于"看不见" |
| 四桶预算 `protect / skeleton / evidence / recent / free` | 每轮显存按桶分配，恒等式 `sum == pool` 违反即硬抛 | 让位有账、可判据（不是"看起来没崩"） |
| 头部保护（`protect`） | sink ∪ 头部段常驻，`first_hidden` 可自证 | 检索预算不足时保住题面开头的事实 |
| 前缀复用（host-backed） | 共享前缀走宿主副本，`cached_tokens` 不回落 | 多轮/换问句不重新 prefill |
| MTP 投机 | `--spec mtp --draft-tokens 1 --mtp-attention-window 8` | 解码吞吐翻倍级（本机实测 `mtp accepted 77–92%`） |
| 分段注入网关 | 超池题面按结构单元分片、逐片摘要回注；含 `L2z` 强制重建与 `L3` 可见拒答 | 题面 > 池时**不静默错**：要么分片答对，要么明确拒答 |
**27B ternary 几何**：64 层 = 3×linear_attention + 1×full_attention ⇒ **只有 16 层带 KV**，25,728 B/token；`context_window 262144`。本机（RTX 4080 SUPER / `sm_89`）8 GiB 快档实测 `engine ≈7,365 MiB`、decode 100–275 tok/s、TTFT 10 s 量级（20K 题面）；8 GiB 长档为预测值。
**硬边界（读这一版必须先知道）**：**题面 token > 池 token ⇒ 单请求答案不可信**（引擎会打 `unverified` 告警；"没打警告"不等于安全，见 `src/serve/generation_service.cpp` 的注释）。超池题面必须走分片网关、每片 ≤ 池。分片聚合已实测精确（94K 题面 / 池 32,768 ⇒ `n=3`、`final=3241` = 真值）。
**这一版与下方旧口径的关系**：下方"获取与启动 / 8 GB 档 / 实测结果"记录的是**旧线（PQ2 + dflash2 + `start-8g.bat`）**，仍然有效但**不要与新线配方混用**；新线的两套 8 GB 配方见"当前边界与排错"里新增的小节。
### 另支持：Qwen4 预览架构（`Qwen4Exp` / `qwen3_8_flash_next`）
本版同时支持 **Qwen4 预览架构** —— 即 Qwen3.8-Flash-Next。artifact 里 `architectures = Qwen4ExpForConditionalGeneration`、`model_type = qwen4_exp` 会被识别成 `Architecture::Qwen4Exp`（`src/models/registry.cpp:15-20`，实现目录 `src/models/qwen3_8_flash_next/`）。
**它与本文主线的 27B ternary 是两条不同架构线，配方与 env 不可混用；本轮三 arch 引擎只针对 27B 线构建。**
| | Qwen4 预览线（`Qwen4Exp`） | 本文主线（`qwen3_5` / 27B ternary） |
|---|---|---|
| 实现目录 | `src/models/qwen3_8_flash_next/` | `src/models/qwen3_5/` |
| 几何 | **48 层 × 每层 512 专家 = 24,576 专家，router top-10**；每专家帧 2,764,800 B ⇒ 主专家库 **63.3 GiB**（离线闭合验证：48 ×