Qwen3.5-4B-singprobe源码逐行解析(三):SingProbeAttnModel的滑动窗口注意力与GQA实现

原创2026-10-16 20:48:141,919 阅读

Qwen3.5-4B-singprobe源码逐行解析(三):SingProbeAttnModel的滑动窗口注意力与GQA实现

Qwen3.5-4B-singprobe 是一个构建在 Qwen3.5-4B 之上的流式安全护栏模型:它在解码过程中直接读取基座模型的隐藏状态,对每个生成的 token 实时打分,覆盖 8 类查询意图、回复安全性与幻觉风险。本文对核心模型类 SingProbeAttnModel 做逐行解析,重点讲透两个实现亮点——滑动窗口注意力(sliding window attention)与分组查询注意力(GQA),理解它们就能看懂这个小探针为什么能保持 <0.5% 的解码开销。

先看全景:SingProbeAttnModel 在架构中的位置

项目 说明
模型架构 SingProbeAttnModel(见 config.json)
输入 基座模型第 [9, 19, 30] 层隐藏状态的拼接,维度 2560 × 3 = 7680
输出 10 个 logits:label_0~label_9(8 意图 + unsafe + hallucination)
参数量 5.18M,bfloat16 存储

整个模型就是一个单层注意力 + 分类头的小网络,但这一层里浓缩了两个工程巧思:用 GQA 把 KV 压到 1/8,用滑动窗口把注意力范围限制在最近 2048 个 token。

输入约定:三层隐藏状态的拼接

探针并不直接吃 token,而是吃基座模型中间层的隐藏状态。config.json 中通过 base_model_layer_ids: <a href="https://link.gitcode.com/i/6811c653021241cddd0f20602b801a3b" target="_blank">9, 19, 30] 指定了"取点"位置([config.json),配置类的 input_size 属性据此算出输入维度(configuration_sing_probe.py):

@property
def input_size(self) -> int:
    return self.hidden_size * len(self.base_model_layer_ids)  # 2560 * 3 = 7680

推理时,集成框架把三层状态在最后一维拼成 <a href="https://link.gitcode.com/i/f7b2d99c348066b77efdef5ac35e8678" target="_blank">batch, seq_len, 7680] 的张量传入。forward 入口处的 _validate_input 会先校验维度是否匹配([modeling_sing_probe.py),不匹配则抛出 ValueError,这是排查集成配置错误的第一个断点。

GQA 实现:8 个 Q 头共享 1 个 KV 头

构造函数里的四个线性投影

模型定义在 modeling_sing_probe.py。关键在四个投影层的维度设计:

self.projection_size = self.num_attention_heads * self.head_dim  # 8 * 64 = 512
self.proj_q = nn.Linear(config.input_size, self.projection_size, bias=False)  # 7680 → 512
self.proj_k = nn.Linear(config.input_size, self.head_dim, bias=False)         # 7680 → 64
self.proj_v = nn.Linear(config.input_size, self.head_dim, bias=False)         # 7680 → 64
self.o_proj = nn.Linear(self.projection_size, self.projection_size, bias=False)  # 512 → 512

注意 proj_k / proj_v 的输出只有 head_dim=64,而不是 Q 侧的 512——这就是 GQA 的精髓:K/V 只保留 1 个头,让 8 个 Q 头分组共享它(分组比例为 8:1)。对比标准多头注意力,KV 投影的参数量和运行时的 KV 缓存都直接缩小了 8 倍,这正是探针能"贴"在解码循环里几乎零开销的原因。所有投影都关闭了 bias,进一步省参数。

forward 中的张量整形

注意力计算前,Q 和 K/V 分别被 reshape 成不同形状(modeling_sing_probe.py):

query = query_features.view(batch_size, seq_len, 8, 64).transpose(1, 2)   # (B, 8, L, 64)
key   = self.proj_k(hidden_states).view(batch_size, seq_len, 1, 64).transpose(1, 2)  # (B, 1, L, 64)

K/V 的第二维是 1,随后调用 F.scaled_dot_product_attention 时传入 enable_gqa=True(modeling_sing_probe.py),由 PyTorch 自动把唯一的 KV 头广播给 8 个 Q 头分组,不需要手写 head 复制逻辑。

滑动窗口注意力逐行解析

为什么分块计算

_sliding_window_attention(modeling_sing_probe.py)没有用预生成的 2048 带宽掩码矩阵硬算长序列,而是按 2048 个 token 一个块循环,每块内只切出相关的 Q/K/V 子段再做局部注意力:

for start in range(0, seq_len, window):
    end = min(start + window, seq_len)
    key_start = max(0, start - window + 1)
  • start 是块起点,end 是块终点;
  • key_start = start - window + 1:块内第一个 query 最多需要回看 2048 个 key,所以 K/V 切段的起点向前多留一个窗口的位置。第一个块 key_start=0,不会越界。

相对位置掩码:一次表达"因果 + 窗口"

块内的注意力掩码用相对位置一步构造(modeling_sing_probe.py):

relative_positions = query_positions[:, None] - key_positions
attention_mask = (relative_positions >= 0) & (relative_positions < window)

这两个条件是理解的核心:

条件 含义
relative_positions >= 0 因果性:key 的位置不能晚于 query,防止看到未来
relative_positions < window 滑动窗口:只允许回看最近 2048 个 token

举个例子:序列长度 5000 时,第二块(start=2048)里,位于位置 3000 的 query 只能看到位置 953~3000 的 key。掩码先 reshape 成 [None, None](即 [1,1])再传入 F.scaled_dot_product_attention 的 attn_mask,利用广播匹配 [B, H, Lq, Lk]。

长序列与短序列的两条路径

forward 里有一个很实用的分支(modeling_sing_probe.py):只有当 sliding_window < seq_len 时才走窗口版;短序列直接退化为标准因果注意力(is_causal=True)。这样探针在任意长度上下文下都行为正确,短上下文时还省掉了分块循环的开销。

残差、归一化与 10 类输出

注意力输出回到 token 维度后(modeling_sing_probe.py):

  1. context 转置并 view 回 (B, L, 512);
  2. o_proj(context) + query_features:一次残差连接,让"查询特征"直通到分类头;
  3. 经 RMSNorm(512, eps=1e-6) 后进入 classifier,产出 10 个 logits。

这 10 个分数与 README 中的输出约定一一对应:label_0~label_7 是 8 类查询意图,label_8 是回复不安全度,label_9 是幻觉风险,每个生成的 token 都会得到一组实时分数,供 SGLang/vLLM 集成做流式拦截。

验证一下 README 里的 5.18M 参数量

模块 形状 参数量
proj_q 7680 → 512 3,928,960
proj_k 7680 → 64 491,520
proj_v 7680 → 64 491,520
o_proj 512 → 512 262,144
classifier 512 → 10 5,130
norm(RMSNorm) 512 512
合计 5,179,786 ≈ 5.18M

可以看到 proj_q 占了约 76% 的参数——Q 侧的 8 个头是探针的"主要算力预算",而 GQA 正是把 K/V 侧成本压到最低的关键设计。

关键超参数速查

超参数 取值 作用
hidden_size 2560 基座模型隐藏维度
base_model_layer_ids [9, 19, 30] 取点的 3 个层,输入维度 ×3
num_attention_heads 8 Q 头数
head_dim 64 每头维度,Q 总维度 512
sliding_window 2048 每个 token 最多回看的 token 数
num_labels 10 分类输出数

小结

SingProbeAttnModel 用一个极小的单层注意力结构完成了"每 token 实时打 10 分"的任务:GQA 让 KV 成本降为 1/8,滑动窗口把注意力范围收敛到最近 2048 个 token,残差 + RMSNorm + 线性头则保证输出稳定可校准。这套设计把安全护栏从"再跑一个大模型"变成了"搭一个小探针",是流式安全检测落地的典型范式。源码总共不到 150 行(modeling_sing_probe.py),非常适合作为学习轻量探针架构的样例工程。

登录后查看全文
Qwen3.5-4B-singprobe