滑动窗口注意力的实现原理:逐行解读 Qwen3.8-Flash-Next-singprobe 的 _sliding_window_attention

原创2026-10-29 12:20:371,839 阅读
文章标签:人工智能大模型模型安全内容安全AI 安全治理

滑动窗口注意力的实现原理:逐行解读 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]

这是掩码构造最精巧的地方——不写死绝对规则,而是用相对偏移一条式表达两条规则:

  1. relative_positions >= 0:key 位置 ≤ query 位置 → 因果性,禁止看到未来;
  2. 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
登录后查看全文
Qwen3.8-Flash-Next-singprobe