flash-sparse-attention 核心概念:Dense、Sparse 与 Gated 三种注意力内核全解析
flash-sparse-attention 核心概念:Dense、Sparse 与 Gated 三种注意力内核全解析
flash-sparse-attention 是一个高性能的、可训练的稀疏注意力库,在 Flash Attention 内存效率的基础上引入稀疏计算,用于高效处理 Transformer 中的超长序列。本文将一次讲清它的三大核心注意力内核——Dense(稠密)、Sparse(稀疏)、Gated(门控)——各自的原理、差异与适用场景,帮助新手快速建立对 flash-sparse-attention 的整体认知。
一、为什么需要三种注意力内核?
在 Transformer 中,注意力的计算量随序列长度平方增长:一个 128K 长度的序列,全量注意力矩阵高达 128K × 128K。flash-sparse-attention 的解题思路是:把序列按块(block)切分,在计算时动态跳过"贡献很小"的块,从而在保证可训练(支持反向传播)的前提下大幅降低计算量。
它为此提供了三种内核(kernel)家族:
| 内核 | 一句话定位 | 稀疏来源 | 额外输入 |
|---|---|---|---|
| Dense | 标准全量注意力,功能最全的"基准版" | 无(可结合局部窗口) | 无 |
| Sparse | 基于 softmax 阈值的动态稀疏 | 注意力分数本身 | 无 |
| Gated | 基于可学习门控的可训练稀疏 | 模型学会的门控值 | alpha + delta |
三种内核在代码中一一对应,位于 flash_sparse_attn/ops/triton/ 目录:
flash_dense_fwd.py/flash_dense_bwd.py/flash_dense_dec.py—— Dense 内核flash_sparse_fwd.py/flash_sparse_bwd.py/flash_sparse_dec.py—— Sparse 内核flash_gated_fwd.py/flash_gated_bwd.py/flash_gated_dec.py—— Gated 内核
💡 后缀含义:
_fwd是前向传播(训练)、_bwd是反向传播(求梯度)、_dec是 decode(带 KV cache 的推理阶段)。
二、Dense 内核:标准全量注意力
Dense 内核就是大家最熟悉的 Flash Attention:Q·K 得到全部注意力分数,再做 online softmax 加权求和,逐块扫描整个 KV 序列。它不做任何块级跳过,适合序列较短、或者需要精确全量注意力的场景。
其训练入口函数定义在 interface.py:
flash_dense_attn_func(query, key, value,
is_causal=True, # 因果掩码
is_local=False, # 局部窗口注意力
is_quant=False, # FP8 低精度
is_split_kv=True) # 切分 KV 均衡负载
Dense 的常见"性能开关":
is_causal:因果掩码,自回归模型必选is_local/window_sizes:局部窗口注意力(如 sliding window),把计算范围限制在窗口内is_quant:融合 FP8 量化,降低显存带宽压力is_split_kv/is_split_qo:切分 KV(前向)或切分 QO(反向)以均衡 GPU 负载pack_gqa:GQA(分组查询注意力)打包优化
三、Sparse 内核:softmax 阈值动态跳过
Sparse 是 flash-sparse-attention 最核心的内核。它的巧妙之处在于:不需要任何额外输入,仅靠一个 softmax_threshold 参数(默认 1.0),就能动态判断哪些 KV 块"不重要"并跳过。
3.1 工作原理
计算时,内核逐块处理 KV 块,每处理一块都会在线维护 row_max(本行最大分数)和 row_sum(本行概率和)。对于新的 KV 块,先估计它"最多能贡献多少概率",然后与阈值比较——完整逻辑见 activations.py 的 online_sparse_softmax:
# 估计该块最大可能贡献(log2 域),与阈值比较
row_max_diff_log2 -= tl.log2(row_sum)
skip_softmax = tl.max(row_max_diff_log2 - softmax_threshold_log2) < 0.0
if skip_softmax:
# 贡献太小,整块跳过:不加载 V,不做累加,直接零权重
p = acc_s * 0.0
也就是说:当某个 KV 块对输出的最大可能贡献低于 softmax_threshold 时,整块直接跳过。块跳得越多,序列越长,加速越明显。
3.2 使用方式
Sparse 的入口函数在 interface.py:
flash_sparse_attn_func(query, key, value,
is_causal=True,
softmax_threshold=1.0, # 稀疏度旋钮:越大越稀疏
is_local=True,
is_quant=True,
is_split_kv=True)
softmax_threshold 可以理解为"稀疏度旋钮":调大它会跳过更多块(更快、更省显存),调小则更接近 Dense 的精确结果,二者之间是一个速度-精度的可调权衡。
四、Gated 内核:可学习的门控稀疏
Gated 内核在 Sparse 的基础上更进一步:稀疏模式不再由分数隐式决定,而是由模型显式学习。这也是 flash-sparse-attention "trainable(可训练)"特性的核心体现。
4.1 工作原理:alpha 与 delta 双门控
Gated 内核需要额外两个输入张量(定义见 interface.py):
alpha:形状[batch, seqlen_q, num_heads],query 侧的稀疏门delta:形状[batch, seqlen_k, num_kv_heads],key/value 侧的稀疏门
内核先计算门控值 alpha·delta(可选再过 log-sigmoid),并用它决定是否值得计算 Q·K 矩阵乘——见 flash_gated_fwd.py:
# 先只算门控,判断下一个块是否值得算
d_tile = ptrs_sched.load_d(config, d_ptrs, n_block - 1)
gate_max, skip_gate_next = softmax_sched.online_gate(...)
if not skip_gate_next:
# 门控通过,才计算 alpha·delta 与 Q·K
acc_s = a_tile[:, None] * d_tile[None, :]
if config.IS_LOGSIGMOID_GATE:
acc_s = softmax_sched.log_sigmoid(acc_s=acc_s)
acc_s += tl.dot(q_tile, k_tile.T)
跳过的判据在 activations.py 的 online_gate 中:先仅用 alpha、delta 的块级极值估算最大门控值,若低于 gate_threshold 则整块跳过——连代价最高的 Q·K 矩阵乘都省掉了,这比 Sparse 的跳过更激进(Sparse 是在算完 Q·K 之后才跳过 V 的累加)。
4.2 门控从哪来?
在官方示例模块 modules/flash_sparse_attention.py 中,alpha 和 delta 分别由两个线性投影从 hidden states 中生成:
self.a_proj = nn.Linear(config.hidden_size, self.num_attention_heads, bias=False)
self.d_proj = nn.Linear(config.hidden_size, self.num_key_value_heads, bias=False)
...
alpha_states = self.a_proj(hidden_states)
delta_states = self.d_proj(hidden_states)
由于 a_proj、d_proj 是可训练参数,模型在训练中会自动学会"在哪里稀疏、稀疏多少",无需人工设定稀疏结构。
4.3 使用方式
flash_gated_attn_func(query, key, value, alpha, delta,
is_causal=True,
softmax_threshold=1.0,
gate_threshold=None, # 门控阈值,默认 1/seqlen_k
is_logsigmoid_gate=True, # 门控函数:log-sigmoid 或线性
is_adapt_gate=True) # 按序列长度自适应阈值
五、三种内核怎么选?
| 场景 | 推荐内核 | 理由 |
|---|---|---|
| 短序列、追求精确结果 | Dense | 无跳过机制,结果与标准注意力一致 |
| 中长序列、推理/训练兼顾 | Sparse | 零额外输入,softmax_threshold 一个旋钮控制稀疏度 |
| 超长序列、希望模型自适应稀疏 | Gated | 门控可端到端训练,稀疏模式由数据决定 |
📌 简单记忆:Dense 是基准,Sparse 是"免费加速",Gated 是"学会加速"。
六、上手:12 个 API 函数与安装
flash-sparse-attention 的公共 API 全部从 flash_sparse_attn/init.py 导出,共 12 个函数,正好是"3 种内核 × 4 种调用形式":
| 训练(base) | 训练(变长 varlen) | Decode(base) | Decode(varlen) | |
|---|---|---|---|---|
| Dense | flash_dense_attn_func |
flash_dense_attn_varlen_func |
flash_dense_attn_with_kvcache_func |
flash_dense_attn_varlen_with_kvcache_func |
| Sparse | flash_sparse_attn_func |
flash_sparse_attn_varlen_func |
flash_sparse_attn_with_kvcache_func |
flash_sparse_attn_varlen_with_kvcache_func |
| Gated | flash_gated_attn_func |
flash_gated_attn_varlen_func |
flash_gated_attn_with_kvcache_func |
flash_gated_attn_varlen_with_kvcache_func |
安装方式:
# 从 PyPI 安装
pip install flash-sparse-attn
# 或从源码安装
git clone https://gitcode.com/gh_mirrors/fl/flash-sparse-attention
cd flash-sparse-attention
pip install .
⚠️ 运行环境要求:NVIDIA GPU(compute capability ≥ 8.0)、Python ≥ 3.9、PyTorch ≥ 2.5.1、Triton ≥ 3.6.0。
最小示例(Sparse 前向,参考 README.md):
import torch
from flash_sparse_attn import flash_sparse_attn_func
dtype = torch.bfloat16
q = torch.randn(2, 4096, 32, 128, dtype=dtype, device="cuda")
k = torch.randn(2, 4096, 8, 128, dtype=dtype, device="cuda")
v = torch.randn(2, 4096, 8, 128, dtype=dtype, device="cuda")
out = flash_sparse_attn_func(q, k, v,
is_causal=True,
softmax_threshold=1.0,
is_local=True, is_quant=True, is_split_kv=True)
张量布局为 (batch, seqlen, num_heads, head_dim),head_dim 最高支持 256,KV 头数少于 Q 头数时自动走 GQA 路径。
七、小结
- Dense:标准 Flash Attention 式全量计算,精确性基准,功能开关最全
- Sparse:靠
softmax_threshold在线估计块级贡献并跳过,零额外输入即可加速长序列 - Gated:引入可训练的
alpha/delta门控,连 Q·K 矩阵乘都能跳过,稀疏模式端到端学习
三者在代码上组织得非常清晰——flash_sparse_attn/ops/triton/ 下每族三个文件(fwd/bwd/dec),公共入口集中在 interface.py,想深入某个内核的细节,直接按上文的文件路径对照阅读即可。选对内核、调好阈值,flash-sparse-attention 能帮你把超长序列的注意力开销降下来一个量级。🚀