滑动窗口注意力的实现原理:逐行解读 Qwen3.8-Flash-Next-singprobe 的 _sliding_window_attention
滑动窗口注意力的实现原理:逐行解读 Qwen3.8-Flash-Next-singprobe 的 _sliding_window_attention
本文以 Qwen3.8-Flash-Next-singprobe(一个流式护栏安全探针模型)为例,逐行解读 modeling_sing_probe.py 中的 _sliding_window_attention 方法,讲清滑动窗口注意力的分块策略、注意力掩码构造,以及它与 PyTorch 融合注意力内核(SDPA)的协作方式。
什么是滑动窗口注意力:从因果注意力到窗口注意力
在 Transformer 中,因果注意力(causal attention) 要求每个 token 只能关注它自己及之前的所有 token。对于长度为 n 的序列,需要计算 n×n 个位置对的得分,计算量是 O(n²) —— 序列越长,开销增长越快。
滑动窗口注意力(Sliding Window Attention) 在此基础上加了一条限制:每个 token 最多只回看最近 w 个位置(w 即窗口大小,sliding window)。这样计算量降为 O(n×w),并且无论序列多长,单 token 的注意力开销都是常数。
| 注意力方式 | 单 token 关注范围 | 序列总计算量 | 特点 |
|---|---|---|---|
| 因果注意力 | 全部历史 | O(n²) | 看得最远,最贵 |
| 滑动窗口注意力 | 最近 w 个 | O(n×w) | 范围受限,可控 |
🪟 一个直观类比:因果注意力像「回顾全文」,滑动窗口注意力像「只回顾最近几页笔记」。对大多数局部判断任务来说,最近几页往往就足够了。
为什么安全探针敢用窗口?SingProbe 的任务是在生成过程中逐 token 打分:查询意图、响应不安全性、幻觉风险。这类信号高度依赖局部上下文——「这句话是否安全」主要由它前后几十个 token 决定,而不是整篇文档。因此用 config.json 中配置的 2048 token 窗口,即可在几乎不损失判断力的前提下,把注意力开销钉死在常数级别。
它在哪里:3 个文件定义滑动窗口机制
这个项目非常小巧,滑动窗口机制涉及的文件一目了然:
| 文件 | 作用 |
|---|---|
| modeling_sing_probe.py | 模型主体,_sliding_window_attention 在 第 80-109 行 |
| configuration_sing_probe.py | 配置类,sliding_window 参数在这里声明 |
| config.json | 实际生效的超参数 |
config.json 中与本文直接相关的参数:
| 参数 | 值 | 含义 |
|---|---|---|
sliding_window |
2048 | 每个 token 最多回看 2048 个位置 |
num_attention_heads |
8 | Query 头数 |
head_dim |
64 | 每个头的维度 |
base_model_layer_ids |
[15, 31, 47] | 从基座模型抽取隐状态的层 |
注意:K/V 的投影维度只有 head_dim(1 个头),而 Q 是 8 个头——这是一个「多 Q 头共享单 K/V 头」的分组查询注意力(GQA)设计,后面会看到它在代码里如何落地。
逐行解读 _sliding_window_attention
完整实现如下(位于 SingProbeAttnModel 内):
def _sliding_window_attention(
self,
query: torch.Tensor,
key: torch.Tensor,
value: torch.Tensor,
) -> torch.Tensor:
seq_len = query.shape[2]
window = self.config.sliding_window
assert window is not None
outputs = []
for start in range(0, seq_len, window):
end = min(start + window, seq_len)
key_start = max(0, start - window + 1)
query_positions = torch.arange(start, end, device=query.device)
key_positions = torch.arange(key_start, end, device=query.device)
relative_positions = query_positions[:, None] - key_positions
attention_mask = (relative_positions >= 0) & (relative_positions < window)
attention_mask = attention_mask[None, None]
query_block = query[:, :, start:end]
key_block = key[:, :, key_start:end]
value_block = value[:, :, key_start:end]
attention_output = F.scaled_dot_product_attention(
query_block,
key_block,
value_block,
attn_mask=attention_mask,
enable_gqa=self.num_attention_heads > 1,
)
outputs.append(attention_output)
return torch.cat(outputs, dim=2)
整体思路一句话:把长序列切成窗口大小的块,每块独立做一次「带掩码的融合注意力」,最后拼回来。 下面分五步拆解。
第 1 步:拿序列长度和窗口大小(L86-L88)
seq_len = query.shape[2]
window = self.config.sliding_window
assert window is not None
query的形状是(batch, heads, seq_len, head_dim),所以shape[2]就是序列长度 n;window来自配置(本项目为 2048),也就是「窗口大小」这个核心超参数;assert window is not None是防御性写法:调用方(forward)已保证只有窗口生效时才进来,这里只是兜底。
第 2 步:按窗口切块,算出每块的 K/V 边界(L89-L94)
for start in range(0, seq_len, window):
end = min(start + window, seq_len)
key_start = max(0, start - window + 1)
这是整个函数的分块策略,两个边界值各有讲究:
end = min(start + window, seq_len):块的右端点,最后一块可能不足一个完整窗口,用min截断;key_start = max(0, start - window + 1):块的 K/V 左端点。它比块的起点start还要往左多取window - 1个位置。
为什么要多取?因为块内第一个 query(位置 start)最多能回看 window 个位置(含自身),即最远到 start - (window - 1)。若 K/V 只从 start 开始,块首 token 的合法注意力范围就被截断了。
用 window=4、seq_len=10 举个小例子:
| 块 | query 位置 | key/value 位置 | 说明 |
|---|---|---|---|
| 1 | 0-3 | 0-3 | 首块,key_start = max(0, 0-3) = 0 |
| 2 | 4-7 | 1-7 | key_start = 4-3 = 1,多带上一块尾部 |
| 3 | 8-9 | 5-9 | 末块长度不足窗口,自动截短 |
可以看到相邻块的 K/V 范围有 重叠——这正是「滑动」的含义:窗口从左向右滑,每块都能看到窗口范围内的完整历史。
随后的两行用 torch.arange 在 query.device 上生成 query 与 key 的绝对位置索引。强调 device 是为了保证索引张量和张量同设备(GPU 上不会触发隐式的 CPU↔GPU 拷贝)。
第 3 步:用「相对位置」构造注意力掩码(L95-L97)
relative_positions = query_positions[:, None] - key_positions
attention_mask = (relative_positions >= 0) & (relative_positions < window)
attention_mask = attention_mask[None, None]
这是掩码构造最精巧的地方——不写死绝对规则,而是用相对偏移一条式表达两条规则:
relative_positions >= 0:key 位置 ≤ query 位置 → 因果性,禁止看到未来;relative_positions < window:query 最多回看 window 个位置 → 窗口上限。
query_positions[:, None] - key_positions 利用广播生成一个 (q_len, k_len) 的相对偏移矩阵,两个布尔条件相与得到掩码。最后 attention_mask[None, None] 补出两个维度,形状变为 (1, 1, q_len, k_len),可以沿 batch 和 head 维度自由广播。
💡 PyTorch 的布尔掩码约定:True = 保留参与注意力,False = 屏蔽。
第 4 步:切片 Q/K/V,交给融合注意力内核(L98-L107)
query_block = query[:, :, start:end]
key_block = key[:, :, key_start:end]
value_block = value[:, :, key_start:end]
attention_output = F.scaled_dot_product_attention(
query_block,
key_block,
value_block,
attn_mask=attention_mask,
enable_gqa=self.num_attention_heads > 1,
)
- 按第 2 步算出的边界把本块的 Q/K/V 切出来,K/V 的范围比 Q 宽,正好覆盖窗口回看距离;
F.scaled_dot_product_attention(SDPA)是 PyTorch 的融合注意力入口,内部会自动选择 FlashAttention 等高效内核,完成「缩放点积 → 掩码 → softmax → 加权求和」全流程;enable_gqa=True是关键一笔:本模型的 Q 有 8 个头,而 K/V 只有 1 个头(见 forward 中的 kv_shape)。开启 GQA 后,内核会自动让 8 个 Q 头共享同一份 K/V,省下的正是 K/V 的显存与带宽——探针只有 5.18M 参数,每一分开销都计较。
第 5 步:拼接各块输出(L108-L109)
outputs.append(attention_output)
return torch.cat(outputs, dim=2)
每块的输出形状为 (batch, heads, block_len, head_dim)。由于分块是无 query 重叠的连续切分(只有 K/V 范围重叠),各块输出在序列维度首尾相接,torch.cat(outputs, dim=2) 沿 seq 维拼接即还原出完整形状的注意力结果。
何时触发滑动窗口:forward 中的分流逻辑
窗口路径并非无条件走,forward 主流程 里有一个判断:
if self.config.sliding_window and self.config.sliding_window < seq_len:
context = self._sliding_window_attention(query, key, value)
else:
context = F.scaled_dot_product_attention(
query=query, key=key, value=value,
is_causal=True, enable_gqa=self.num_attention_heads > 1,
)
逻辑非常朴素:
- 序列长度 ≤ 窗口(如 2048)时,一次标准因果注意力(
is_causal=True)就能覆盖全部合法范围,无需分块,直接走 else 分支——短序列下这还更快; - 序列长度 > 窗口 时,才启用
_sliding_window_attention分块处理。
窗口之后的流程与常规 Transformer 一致:把注意力输出重塑回 (batch, seq, 512),经 o_proj 并与 query 特征做残差相加,再过 RMSNorm 与分类头,输出 10 个标签的 logits(8 种意图 + 不安全 + 幻觉,见 README.md)。
为什么这样设计:3 个工程要点
⚡ 要点一:算力从平方级降为线性级。 以 32768 长序列、窗口 2048 为例:全因果注意力约需 10.7 亿个位置对的得分,滑动窗口只需约 6700 万——注意力开销降为 1/16,且序列再变长也不再增加。这是探针能「每 token 都打分、解码开销 < 0.5%」的底层原因之一。
🧩 要点二:块内掩码小且稠密,友好于 Flash 内核。 若对整条序列构造一个 n×n 的带状掩码,掩码本身就要 O(n²) 显存;本实现每块只构造 window × 2×window 级别的小掩码,每次 SDPA 调用都是一个紧凑、局部的问题,内核命中率更高。
🔍 要点三:因果性在窗口内依然严格成立。 掩码由「绝对位置差」算出,切块只是分块计算的手段,不改变可见范围——块首 token 通过 key_start 的多带窗口,依然能看到完整回看距离,不泄露未来信息,也不丢失边界信息。
总结
_sliding_window_attention的核心是三步:按窗口切块 → 用相对位置一条式生成「因果 + 窗口」掩码 → 每块调用 SDPA 融合内核,最后沿序列维拼接;key_start = start - window + 1这一行保证了块间 K/V 重叠,块首 token 的回看范围不被截断;- 触发条件写在 forward:仅当
seq_len > sliding_window时启用,短序列直接走标准因果注意力; - 配合 8 Q 头共享 1 K/V 头的 GQA 设计,滑动窗口让探针的注意力成本被钉死在 O(n×w),这正是轻量流式护栏能低开销逐 token 打分的关键。
相关文件
| 资源 | 路径 |
|---|---|
| 滑动窗口注意力实现 | modeling_sing_probe.py |
| 分流逻辑与投影定义 | modeling_sing_probe.py |
| 窗口参数声明 | configuration_sing_probe.py |
| 生效超参数(2048 窗口) | config.json |
| 项目背景与部署方式 | README.md |