Skip to content

WeLM Sparse Attention:计算、分页与缓存恢复 ​

稀疏推理需要把三个环节接起来:Indexer 选择历史位置,主 Attention 通过页表读取选中的 KV,前缀缓存则保存并恢复下一次计算仍要用到的状态。Indexer-K、主 Attention KV 和一次 query 的 selection 因此有不同的职责与生命周期。

下文先用共享 selection 的 GQA 解释通用计算与张量关系,再沿 WeLM Sparse 的 HiCache 实现追踪缓存恢复。通用公式与伪代码不代表特定 WeLM 版本的全部模型实现,尤其不能据此推定实际 selection 的 head/group 轴。

HiCache 源码固定于 PR !497 的 f96e0205bb312894edef6ec308fd04290931dfff,比较基点为 daa5fb89b3441b39ed61fa1fbcede40ac9ac5551。该版本的 WeLM sparse 集成限于单体 Host L2;现有证据为该版本源码,未包含模型或 GPU 实测。

Sparse Attention Dataflow ​

正在渲染流程图…

Indexer 产生用于选位置的分数;主 Attention 在选中位置上重新计算正式的 attention logits,并对 V 加权求和。两部分的 Q/K 应分别命名,不能把 indexer score 当作主 Attention 的 softmax 权重。

记号含义
N当前 query token 行数
Hᵢ、DᵢIndexer 的 head 数和 head dimension
Hq、Hkv当前设备上主 Attention 的 Q / KV head 数
Dq、Dv主 Attention 的 QK / V 特征维度
B每个 KV block 的 token 数
T每个 query 选择的 block 数上限

一个请求在 prefill 或 verify 中可以对应多个 query 行,所以 N 不等于请求 batch size。

Head Layout ​

假设同一 GQA 组内的 query heads 共享一份 selection;GQA 本身只定义 KV 共享,不自动保证稀疏选择也共享。

概念职责
主 Attention Q heads每个 head 独立计算 attention 分布和输出
主 Attention KV heads为映射到该组的 Q heads 提供 K/V 向量
Indexer heads参与相关性打分;不是主 Attention Q heads 的另一个名称

GQA 将多个 Q heads 映射到较少的 KV heads。在均匀分组的情形下,每组 Q heads 数为:

G=Hq/Hkv.

公开定义与模型背景见 GQA 论文。分布式实现中,应区分全模型和设备本地的 head 数;KV 切分或复制会影响本地分组关系。

同一 GQA 组使用同一个 KV head 的向量,但 GQA 本身没有定义稀疏选块方式。Selection 可以按 query 共享,也可以带 head/group 轴。

Selection 表示描述的共享范围
[query, selected_blocks]每个 query 共用一份块列表
[query, group, selected_blocks]每个 query、每个 group 有自己的列表
[query, head, selected_blocks]每个 query、每个 head 有自己的列表

在本文假设下,固定一个 GQA 组,query t 的集合记为 St。不含 sink、softcap 或其他附加项的基本表达式是:

ot,h=softmax(qt,hKSt⊤/Dq)VSt.

集合不带组内 head 下标,但不同 head 的 Q 不同。因此访问相同 K/V 和相同 token IDs,不要求 attention logits、权重或输出相同。

不同 KV groups 即使选中相同 token IDs,其 K/V 向量也不要求相同,不能把它们无条件合并成针对同一份 K/V 的矩阵行。

固定一个 query 和一个含 B 个 token 的 KV block:

Qt∈RG×Dq,Kb∈RB×Dq,Vb∈RB×Dv.

Q 的每一行是一个独立 head,不是沿 head 求和或把所有 heads 合成一个长向量。QK 的形状为:

St,b=QtKb⊤∈RG×B.

softmax 沿该 head 的全部选中 KV tokens 归一化。令 Pt,b 为完整归一化权重在 block b 上的切片,则:

Ot,b=Pt,bVb∈RG×Dv,Ot=∑bOt,b.

增加 B、Dq 或 Dv,不会改变组内 Q 行数 G。这是矩阵形状的关系,不是 kernel latency 或 Tensor Core 利用率的测量。

各 block 分别 softmax 后直接相加,一般不等价于对完整选中集合归一化。在线分块计算需要维护跨块的归一化与输出状态。FlashAttention 论文解释了这种分块计算的基本机制。

Dense attention 的多个 query 可以对同一个 K/V block 计算,再处理各自的 mask。逐 query 的 sparse Selection 则不要求相同,例如:

text
query A → blocks {a, c}
query B → blocks {b, c}

普通 GEMM 的所有行共享右操作数。将两个 query 的 Q 堆叠,不会让两份不同的紧凑 KV 列表自动成为同一矩阵。相同的列下标必须有一致的 K/V 含义。

因此需要分别确认:

  • 有多少 query 行。
  • 哪些 Q heads 使用同一份 K/V 向量。
  • 哪些 query/head 的 Selection 相同。
  • 实际 kernel 如何组织这些行和列。

这些条件不能由模型的总 Q-head 数代替。在逐 query 页表接口中,多个 query 是独立的逻辑序列;接口本身不规定它们在 GPU 上如何分配 CTA、warp 或 MMA tile。

例如 Hq=32,Hkv=8 时,每组 G=4。取 B=128,Dq=Dv=64,则组内 Q 为 4×64,QK 输出为 4×128,PV 输出为 4×64;四个 heads 访问同一份 K/V,仍各自保留一行输出。

Indexer ​

Lightning indexer 的 weighted-ReLU MQA score 可表示为:

rt,j=α∑a=1Hiwt,aReLU(qt,aI⋅kjI).

其中 qI、kI 是 indexer 的 Q/K,w 是 head 权重,α 表示采用的缩放约定。对 head 的归约完成后,输出是每个 query 对历史位置的一个 score。公开的 DeepGEMM MQA scoring 接口提供这一类打分,并区分 paged 与 non-paged 形式。

FP8 路径需要同时处理量化数据和 scale。投影、位置编码、量化、写 cache、打分、选块是不同职责;一个 Python 调用不一定对应一个 GPU kernel,融合 kernel 也不意味着整条 Indexer 路径已经融合。

主 Attention 的 Hq/Hkv 与 indexer 的 Hᵢ 是不同参数。某个 scorer 的 head 对齐限制不能直接当作主 Attention kernel 的限制。

Block Selection ​

对按 block 选择、使用 max pooling 的形式,定义 query t 的可见集合为 Vt,block b 的位置集合为 Bb:

rt,j′={rt,j,j∈Vt,−∞,otherwise,mt,b=maxj∈Bbrt,j′.

然后沿 block 维做 top-k,得到逻辑块号。先处理可见性,再做 block max,可保证未来位置不会影响当前块的分数。

python
# 机制伪代码:省略 dtype、padding 和有效块数处理
visible_scores = token_scores.masked_fill(~visible, -float("inf"))
block_scores = visible_scores.reshape(N, num_blocks, B).amax(-1)
selected_blocks = block_scores.topk(min(T, num_blocks), dim=-1).indices

top-k 的 index 是逻辑块号,不是物理 cache 页号。若可见块少于 T,还需要约定有效数量或无效 sentinel;不能把填充项解释成真实 KV。

这是 block-max 选块形式的定义。其他算法可以按 token 选择、采用其他 pooling,或使用不同的 head/group Selection 语义,不能从“DSA”这个名称推断它们相同。

Paged KV Cache ​

分页 KV cache 通过请求页表把逻辑块映射到物理页。若 block 和 cache page 大小一致,映射关系可写成:

text
selected physical page[t, k]
    = request page table[request_of(t), selected logical block[t, k]]

这个步骤只重组页号,不要求把选中的 K/V 复制到一块新的连续显存。

如果接口用“页表 + 一个有效长度”表示选中集合,且只有最后一个有效页可以不满,则被选中的当前尾页需要放在有效页表末尾。举一个与模型配置无关的页表示例:page size=4,历史长度=10,三个逻辑页的有效长度分别是 4、4、2。

选中的逻辑页合适的页表顺序选中 KV 的有效长度
2、00、26
0、10、18

因此稀疏有效长度不等于原请求长度,也不总是“选择页数 × page size”。上表仅演示页表语义,不表示某个设备 kernel 支持 page size=4。

FlashAttention 的 KV-cache 接口支持分页 KV 与 GQA/MQA;具体参数名和支持范围应以所用版本为准。公开接口见 FA3 Python API。

在逐 query 页表的表示方式中,数据关系是:

输入形状含义
Q[N, Hq, Dq]主 Attention query
K cache[num_pages, B, Hkv, Dq]分页 Key
V cache[num_pages, B, Hkv, Dv]分页 Value
page table[N, T]各 query 选中的物理页
cache lengths[N]各 query 的稀疏 KV 有效长度
cumulative query lengths[0,1,...,N]各 query 表示为长度 1 的序列

“一个 query 一份页表”描述的是接口的数据组织,不表示为每个 token 发起一次 Python 调用或一次 GPU launch。

当每份页表和有效长度已经完整表达该 query 可见的历史位置时,主 Attention 可在这个集合内做非因果矩阵计算;原序列的因果约束由集合构造保证。只有满足这个前提,关闭 kernel 内部的 causal mask 才保留原有语义。

如果启用了 attention sink、softcap、位置偏置等机制,还需保留相应的数值定义。页表只能描述访问哪些 KV,不能替代这些计算。

HiCache ​

单体 Host L2 缓存适配复用了既有调度器、控制器和前缀树机制。计算路径决定了恢复前缀时不仅需要主 KV,还需要历史 Indexer-K。

Indexer-K 保存的是历史 token 用于打分的向量,不是 Top-K 编号,不是主 Attention 的 K,也不是最终 attention 权重。当前 Query 的变化会改变打分和选择结果,因此保存可复用的历史 K,比把某次选择结果当作长期缓存更合理。这个 PR 的 L2 sidecar 保存 Indexer-K,不持久化 selection。

源码入口:WeLMSparseIndexer.store_key / forward。

store_key() 的主要步骤如下:

  1. 从 backend metadata 中取得当前需要写入的 token 行与位置。
  2. 对 hidden state 做 wk 投影。
  3. 按特征维做 RMS 归一化,再应用 gamma_k;是否加 1 取决于 zero-centered 配置。
  4. 转为 BF16,应用 RoPE。
  5. 通过 set_index_k_buffer(),写入 out_cache_loc 对应的 GPU token 槽。

forward() 则生成 Indexer Query 和 head weights,读取历史 Indexer-K,将它们交给 runtime.select(),得到这次 Query 的选择结果。

text
历史 token hidden ── wk / 归一化 / RoPE ──→ Indexer-K cache
                                                   ↓
当前 token hidden ── wq / ww ──→ Query、weights ──→ 打分与选块
                                                   ↓
主 Attention 自己的 Query、K、V ────────────────→ 稀疏 Attention

解释性例子:已经缓存 100 个历史 token,现在处理第 101 个 token。Indexer 用当前 Query 与历史 Indexer-K 比较,选出相关历史块;主 Attention 再读取那些块中的主 K/V。下一 token 可以复用这 100 个历史 Indexer-K,但通常需要重新计算选择结果。

Indexer 只承担打分,不需要像主 Attention 那样对自己的 V 做加权汇总,所以这里没有 Indexer-V。名称里的 K 是相似度匹配中的 Key,不意味着必须有一个配套 V buffer。

GPU L1 容量不足时,可把前缀备份到 Host L2,以主机内存和 Host↔GPU 搬运成本换取少做前缀重算。能否缩短请求时间取决于前缀命中与搬运、重算的相对成本。

模型执行需要 GPU 上的缓存。此前初始化已建立的 GPU 池包括主 Attention KV、Indexer-K,以及配置启用时的 SWA 和 MTP draft 池。build_welm_sparse_stack() 并不重新创建这些 GPU 池,而是为它们建立配套 Host 存储与搬运控制器。

这要求恢复对象与计算依赖一致:主 KV、Indexer-K,以及启用 MTP 时的 draft 状态需要覆盖同一有效前缀。由此引出下面的容量关联与完成事件,而不是把几个 buffer 各自复制回来就结束。

Initialization ​

调用链发生在服务初始化阶段;每个相关执行进程建立自己的缓存资源,并不是每次请求都调用 builder。

text
Scheduler 创建 UnifiedRadixCache,启用 hierarchical cache
  → UnifiedRadixCache.init_hicache()
  → attach_hybrid_pool_to_unified_cache()
  → 识别 WeLMSparseKVPool / WeLMSparseSWAKVPool
  → build_welm_sparse_stack()
  → 绑定 HostPoolGroup、HybridCacheController、INDEXER sidecar

源码入口:Scheduler 初始化入口、build_welm_sparse_stack。

builder 的输入包括已存在的 kvcache、缓存与模型初始化参数、server args、加载事件和通信组;输出是 Host pool group、controller 和传输层数。

开头要求:

  • storage_backend is None,不接入 L3。
  • hicache_load_end_layer is None,不接入 Deferred。
  • pp_size == 1。
  • write policy 为 write_through。
  • layout 为 layer_first 或 layer_page_first。
  • IO backend 为 kernel 或 direct。

这些是当前集成边界,不是 sparse attention 算法必然只能这样实现。更外层还有其他组合限制;尤其不能由此推出 PD + HiCache 已支持。

Cache Pools ​

Attention KV 和 Indexer-K 有独立 buffer,不共享同一块物理内存;关联的是同一批 token 的页面身份与生命周期。

INDEXER sidecar 跟随 KV anchor,使用 ALL_PAGES 命中策略。SWA 有自己的窗口语义,不能因为主模型存在 SWA,就只保留窗口内的 Indexer 历史。源码绑定见 INDEXER sidecar 注册。

“相同页数”不等于“相同字节数”。page size 在这里首先表达每页容纳多少 token;不同池的每个 token 内容大小可以不同。

解释性例子:每页 64 token。假设主 KV 每个 token 占 4096 B,Indexer-K 每个 token 占 256 B,则一页分别占 256 KiB 和 16 KiB。两者都分配 100 页,能覆盖同样 6400 个 token 槽,但占用内存不同。这个主 KV 大小仅用于示例,不代表具体 checkpoint。

在实际 WeLM Index-K 配置中,单层每 token 为一个 128 维 BF16 向量,即 256 B。跨层总量还需要乘以 Indexer 层数。

Host 页号与 GPU 页号也不要求相同。恢复时可以将 Host 页 2 搬到 GPU 页 5;关键是对应 KV 和 Indexer-K 的映射与生命周期保持一致。

builder 对主 Full/SWA 池逐个统计实际 K/V buffer 的字节数,并把 Indexer-K 和 draft 的字节数加入总量。这里不直接使用 Full wrapper 可能包含 sidecar 的大小,避免把 Indexer-K 重复计费。

显式设置 hicache_size 时,主池预算的核心关系是:

python
host_size_for_pool = hicache_size * sizes[name] / total_bytes

接着由 build_kv_host_pool() 把字节预算转换成池容量。Indexer Host 不再独立按一份任意预算决定 token 容量,而是复制 Full anchor 的 size、page_num 和 page_size;draft sidecar 也按所跟随的主池建立容量。

解释性例子:假设 GPU 实际存储中主 KV 占 8 GiB、Index-K 占 2 GiB,无 SWA/draft,总 Host 预算按比例扩大到 30 GiB。主 KV 分到约 24 GiB,Index-K 通过匹配主池容量占约 6 GiB,二者覆盖同样的 token 槽。实际配置中的 hicache_size 采用代码的十进制 GB 换算,示例只说明比例关系。

未使用绝对预算时,主池沿用 Host/GPU 容量 ratio。页对齐、取整和现有备用页规则意味着总分配不是对预算的逐字节精确切分;理解预算时应区分目标预算、逻辑 token 容量与实际 buffer 大小。

MHATokenToKOnlyPoolHost 是本 PR 新增的 class。它既负责 Host Indexer-K 的内存组织,也提供既有缓存框架需要的备份、逐层恢复和页面访问接口。

关键成员来自两类对象:

来源属性用途
GPU Index-K 池dtype、head_num、head_dim、layer_num决定每 token 的实际存储大小
Full Host anchorsize、page_num、page_size保持可覆盖的 token 页容量一致

每 token 跨所有层的字节数是 head_dim * head_num * layer_num * dtype.itemsize。layer_first 可理解为按 [layer, token, head, dim] 组织;layer_page_first 将 token 拆为 page 和页内 token 维。

这里的 MHA 是存储家族的命名,不代表 WeLM 主 Attention 一定使用等量 Q/KV heads。GQA 也可以使用这个普通 head 布局的池,实际存储由 KV head 数决定。

不能直接替换为已有的 NSAIndexerPoolHost:后者适配 NSATokenToKVPool 的量化 Index-K 与 scale 打包表示,访问的是另一套字段和物理布局;WeLM 这里使用普通 BF16 K-only buffer。差异落在数据表示与接口契约,而不只是“模型算法名字不同”。

同理,复用名称带 _mla 的搬运函数也不意味着 WeLM 使用 MLA。搬运层可以复用单 buffer plane 的复制能力;MLA 的压缩 latent 表示与 WeLM 的 BF16 Index-K 在算法语义上仍不同。

page_transfer.py 将一次搬运拆成静态资源和动态映射:

对象职责
PageTransferBinding保存池的 buffer planes、指针表、每页字节数等长期信息
PageTransferMap保存本次 Host/GPU 页对应关系;direct 路径生成连续拷贝段
PreparedPageTransfer结合 binding 和 map,执行所有层或指定层的搬运
PageTransferGroup把多个池按同一次缓存操作组织起来

以前主 KV 每层两个 plane:K、V。本 PR 允许 Indexer 每层只有一个 K plane,主要修改 _select_planes()、planes_per_layer 和逐层偏移计算。

python
width = binding.planes_per_layer
start, count = (0, binding.plane_count) if layer is None else (layer * width, width)

解释性例子:三层主 KV 的 planes 为 [K0, V0, K1, V1, K2, V2],第 1 层从位置 2 复制两个 plane;三层 Indexer 为 [K0, K1, K2],第 1 层从位置 1 复制一个 plane。若仍固定乘 2,Index-K 的逐层恢复就会错位。

两种路径都实现 Host↔GPU 搬运,主要区别在执行方式。

  • kernel:通过 GPU SM 执行复制 kernel。page 路径调用 module.sm,进入 launch_hicache_pages / hicache_copy_pages。
  • direct:通过 CUDA memcpy API 提交复制。默认实现使用 cudaMemcpyBatchAsync;该代码还有其他实现分支。实际 CUDA 版本与 API 支持需要匹配,不应假设不支持时自动 fallback。

底层入口见 hicache_pages.cuh。本 PR 主要补齐 K-only 接线,没有新增这套 CUDA 页复制 kernel。layer_first 还通过 Host 类的既有 JIT/传统搬运函数执行,不能将所有 layout 都简化为同一个 PageTransferGroup 路径。

direct 不代表固定使用某个硬件引擎,也不能仅凭名字断言总比 kernel 快;碎片程度、连续段数量、调度开销和链路情况都会影响性能。

Prefix Restore ​

运行时链路与初始化不同:

text
请求匹配缓存前缀
  → 判定需要的 Host 数据已就绪
  → 分配 GPU 目标槽,建立 Host/GPU 映射
  → 提交加载操作
  → HybridCacheController.start_loading()
  → load stream 上按层恢复所需 pools
  → 记录对应层的完成事件
  → 模型消费者等待事件,再读取恢复的数据

HybridCacheController 的 start_loading() 是既有逻辑,不是本 PR 新增的主功能。新池接入这个控制器后,Index-K 与主 KV、必要 draft 状态一起参与所需的加载与同步。

记录完成事件不等于 CPU 当时已经等待复制完成。正确性来自 CUDA stream/event 顺序:消费者在使用某层数据前,必须等待覆盖该层必要 planes 的事件。

备份方向由 controller 的写入路径组织,通常将所需层从 GPU 搬到 Host;Host 数据完成并被确认后才可作为可用命中来源。备份已提交、Host ready、GPU 恢复已提交、模型可读取,是不同状态。

Validation ​

通常 decode 每请求处理一个新 query,verify 每请求可以处理多个候选 query。共用一个请求的历史 KV cache,不意味着各候选的 Selection 相同。

只知道 head 数、query 数或推理阶段,不能确定实际运行是访存瓶颈还是计算瓶颈。矩阵的数学形状也不能直接说明设备指令 padding、有效吞吐或加速比。

阅读 profile 时需要区分:

观测量含义
单个 kernel duration对应设备 kernel 的执行时间
多个 kernel duration 之和各次执行时间累计,可能包含互相重叠的区间
GPU annotation 跨度一个标注范围的起止时间差,可包含 kernel 间隙
请求延迟用户请求的端到端时间,不能由某个局部累计值直接替代

比较不同实现时,输入形状、Selection、dtype、数值语义和计时边界必须一致,性能差异才有可解释的含义。实际设备模板、MMA 形状、split 数与 launch 数还需由所用构建和运行记录确定。

PR 验收文档 报告了历史实机验收;其中取消观测发生时 CUDA 事件已完成。这能支持该记录中的完成后取消场景,尚不能证明 DMA 仍在进行时的资源回收也已覆盖。恢复链路中的“已提交”和“可读取”必须由前述事件区分,真实在途取消仍需额外证据。

同一 PR 的 Mooncake 修改处理 PD 分离中取消、状态发布和源页回收的竞争。它与 Host L2 都涉及异步传输的生命周期,但该固定版本拒绝 PD + HiCache,不能将两条修改拼成一条可运行的端到端链路。

Mooncake:GPU-source 传输取消与资源回收 独立讨论通用 PD 并发正确性。算法背景见 DSA、MSA 与 DSA 的比较,主注意力接口见 SGLang Attention backend。

记录原理、连接知识、积累实践。