Qwen3.5-4B-singprobe源码逐行解析(三):SingProbeAttnModel的滑动窗口注意力与GQA实现
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):
context转置并 view 回(B, L, 512);o_proj(context) + query_features:一次残差连接,让"查询特征"直通到分类头;- 经
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),非常适合作为学习轻量探针架构的样例工程。