v08_paged_gqa_py

本版本引入什么

本版本使用可读的 PyTorch 实现，把槽位独占的连续 KV 存储替换为分页 KV 缓存。

请求获得逻辑块，并通过块表映射到物理缓存块。

为什么引入

每个请求独占连续 KV 缓存很容易理解，但当请求长度不同、结束时间不同时会变得难以管理。分页 KV 缓存让内存能以块为粒度复用，并准备好分页注意力 kernel 所需的数据布局。

核心原则

请求看到的是缓存块的逻辑序列：

逻辑块 0, 逻辑块 1, 逻辑块 2, ...

缓存把物理块保存在块池中。块表将每个请求槽位及逻辑块索引映射到物理块 ID。

注意力通过块表恢复请求的逻辑 K/V 顺序。

建议对比的文件

• kvcache.py：块池分配和物理存储。
• scheduler.py：块表构造。
• layer/gqa.py：PyTorch 分页注意力读取。
• engine.py：分页缓存如何与 CUDA Graph 解码共存。

保留的权衡

实现仍使用 Python 循环和 PyTorch gather，让映射关系保持可见。下一步是把相同思路迁移到 Triton kernel。