Qwen3.8-27B-singprobe源码解析:SingProbeAttnModel滑动窗口注意力与GQA实现细节
Qwen3.8-27B-singprobe源码解析:SingProbeAttnModel滑动窗口注意力与GQA实现细节
Qwen3.8-27B-singprobe 是基于 Qwen/Qwen3.8-27B 构建的流式安全护栏探针(Streaming Guardrail Probe),无需额外部署安全模型,即可在生成每个 token 时实时评估查询意图、回复不安全性与幻觉风险,解码开销不到 0.5%。本文带你完整拆解其核心模型 SingProbeAttnModel 的源码:GQA(分组查询注意力)如何做到 8 个 Query 头共享 1 组 Key/Value,以及 2048 滑动窗口注意力的因果掩码是怎么用广播运算高效实现的。🔍
项目速览:一个只有 10.1M 参数的安全探针
SingProbe 的设计思路很"轻":不跑独立的安全分类模型,而是复用基础模型生成过程中的隐状态(hidden states),用一个极小的探针网络逐 token 打分。
| 关键指标 | 数值 |
|---|---|
| 基础模型 | Qwen/Qwen3.8-27B |
| 探针参数量 | 10.1M(仅约基础模型的 0.04%) |
| 抽取隐状态的层 | [20, 41, 62](中层、中上层、顶层) |
| 输出标签 | 10 个(8 类意图 + 不安全 + 幻觉) |
| 解码时延开销 | < 0.5% |
评测数据上,它在流式安全检测(R-AUC 0.9881 / T-AUC 0.9305)和幻觉检测(AUC 0.8035)上均超过 8B 级别的专用护栏模型,完整结果见 README.md。
仓库结构:核心代码只有两个 Python 文件
整个仓库结构非常精简,源码解析只需关注两个文件:
| 文件 | 作用 |
|---|---|
| config.json | 模型配置:架构类型、层 ID、注意力头数、滑窗大小等 |
| configuration_sing_probe.py | 配置类:SingProbeAttnConfig 与 SingProbeMlpConfig |
| modeling_sing_probe.py | 模型实现:SingProbeAttnModel(注意力版)与 SingProbeMlpModel(MLP 版) |
| model.safetensors | 探针权重文件 |
配置解析:读懂 config.json 的 7 个关键参数
打开 config.json,每个字段都直接对应模型结构:
{
"architectures": ["SingProbeAttnModel"],
"hidden_size": 5120,
"base_model_layer_ids": [20, 41, 62],
"num_attention_heads": 8,
"head_dim": 64,
"sliding_window": 2048,
"num_labels": 10
}
📌 两个容易忽略的推导量:
- 输入维度
input_size = hidden_size × len(base_model_layer_ids) = 5120 × 3 = 15360,定义在 configuration_sing_probe.py。探针的输入是基础模型 3 个抽取层隐状态的拼接向量; - 投影维度
projection_size = num_attention_heads × head_dim = 8 × 64 = 512,是 Q 侧与输出侧的工作维度。
配置类 SingProbeAttnConfig 在 configuration_sing_probe.py 中定义,通过 auto_map 机制接入 Transformers 的 AutoConfig / AutoModel 加载流程。
GQA 实现细节:8 个 Query 头为什么只投影 1 组 Key/Value
这是整个模型最值得细看的设计。看 SingProbeAttnModel 的初始化代码 modeling_sing_probe.py:
self.proj_q = nn.Linear(config.input_size, self.projection_size, bias=False) # 15360 → 512
self.proj_k = nn.Linear(config.input_size, self.head_dim, bias=False) # 15360 → 64
self.proj_v = nn.Linear(config.input_size, self.head_dim, bias=False) # 15360 → 64
普通多头注意力里,Q/K/V 各自投影出 8 组头;而这里 Q 投影出 8 个头(512 维),K 和 V 各只投影 1 个头(64 维)。这就是典型的 GQA(Grouped Query Attention):8 个 Query 头共享同一组 Key/Value,比例 8:1。
前向过程中形状变换印证了这一点 modeling_sing_probe.py:
query_shape = (batch_size, seq_len, self.num_attention_heads, self.head_dim) # 8 个头
kv_shape = (batch_size, seq_len, 1, self.head_dim) # 仅 1 个头
随后调用 PyTorch 原生 SDPA 时传入 enable_gqa=self.num_attention_heads > 1,底层内核会自动把单组 KV 广播到 8 个 Q 头上,无需手工复制张量。
⚡ GQA 在这里的收益是实打实的:
- KV 计算量降至 1/8:K/V 只投影 64 维而非 512 维;
- 无偏置投影(
bias=False)进一步压缩参数,10.1M 的总参数量正是省出来的; - 与基础模型中常见的大比例 GQA 相比,探针选择 8:1 是在"表达力"和"开销"之间的折中。
滑动窗口注意力:2048 窗口的因果掩码是怎么算的
护栏打分只需要局部上下文——判断当前 token 是否越界,看前 2048 个 token 足够。模型在 modeling_sing_probe.py 中先做一个分支判断:
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(..., is_causal=True) # 全量因果路径
短序列直接走原生因果注意力;长序列才进入滑窗逻辑 modeling_sing_probe.py,其核心是三段"窗口切片":
- 按窗分块:以
window=2048为步长遍历 Query,每块取[start, end); - Key 向前多取一个窗:
key_start = max(0, start - window + 1),保证窗口最前端的 Query 也能看到 2048 个历史 token; - 相对位置广播掩码:这是最精巧的一步——
relative_positions = query_positions[:, None] - key_positions
attention_mask = (relative_positions >= 0) & (relative_positions < window)
它不构建 seq_len × seq_len 的巨型掩码矩阵,而是用两个一维位置向量做广播差:>= 0 实现因果约束(不能看未来),< window 实现窗口截断(最多看 2048 个历史 token)。掩码规模只有 块大小 × (2×窗口-1),显存与构造开销都远低于全量矩阵。
最后各块结果沿序列维 torch.cat 拼回完整输出,数学上与"逐 token 窗口注意力"完全等价。
前向全流程:从 15360 维隐状态到 10 类分数
把上面所有部件串起来,forward 的完整数据流 modeling_sing_probe.py 是:
- 校验输入:断言最后一维等于
input_size(15360),不匹配立即报错,见 _validate_input; - 三向投影:hidden states → Q(8 头 × 64 维)、K(1 头)、V(1 头);
- GQA 滑动窗口注意力:输出每位置 512 维上下文向量;
- 残差连接:
o_proj(context) + query_features——残差支路用的是注意力前的 Query 特征,而非输入隐状态; - RMSNorm + 分类头:
Linear(512 → 10)输出 logits,封装为TokenClassifierOutput返回。
10 个输出即推理接口返回的 label_0–label_9:前 8 个是意图分类,第 9 个是不安全,最后一个是幻觉风险——每个生成 token 都会得到一份这样的分数字典。
💡 仓库同时提供
SingProbeMlpModel(modeling_sing_probe.py):两层全连接(15360 → 1024 → 10)+ GELU 的极简版探针,适合需要更短延迟、可放弃 token 间建模能力的场景。
快速上手:SGLang / vLLM 一条命令挂载探针
部署时只需在推理引擎启动命令里加一个 --probe-ckpt 参数,指向本探针仓库(注意必须与基础模型成对使用):
python -m sglang.launch_server \
--model-path Qwen/Qwen3.8-27B \
--probe-ckpt inclusionAI/Qwen3.8-27B-singprobe \
--port 30000
服务运行后,每生成一个 token 就附带一份 10 维分数,可直接用于流式拦截策略。完整的启动方式与引用信息见 README.md。
关键要点总结
| 设计点 | 实现方式 | 源码位置 |
|---|---|---|
| 输入融合 | 层 20/41/62 隐状态拼接为 15360 维 | config.json |
| GQA | Q 8 头 vs KV 1 头,enable_gqa=True 广播 |
modeling_sing_probe.py |
| 滑动窗口 | 2048 窗 + 相对位置广播掩码,免全量矩阵 | modeling_sing_probe.py |
| 残差结构 | o_proj(attn) + query → RMSNorm → 分类头 |
modeling_sing_probe.py |
| 输出 | 每 token 10 类分数(意图/不安全/幻觉) | config.json |
用 10.1M 参数换来了接近 8B 专用护栏模型的检测效果,SingProbeAttnModel 的这套"GQA 压 KV + 滑窗限上下文 + 残差归一分类"组合,是轻量化逐 token 安全探针的一个很好的参考实现。✅