modeling_sing_probe.py逐行精读:gemma-4-26B-A4B-it-singprobe的GQA注意力、滑窗与逐Token分类原理
modeling_sing_probe.py逐行精读:gemma-4-26B-A4B-it-singprobe的GQA注意力、滑窗与逐Token分类原理
gemma-4-26B-A4B-it-singprobe(SingProbe)是构建在 gemma-4-26B-A4B-it 基座模型上的轻量级流式安全探针:它不依赖独立的安全模型,而是在生成过程中复用基座的隐藏状态,对每一个 token 逐一打分,评估查询意图、响应不安全性与幻觉风险,解码开销不到 0.5%。本文将核心文件 modeling_sing_probe.py 逐段精读,拆解 GQA 注意力、2048 滑窗机制与逐 Token 十类分类的实现原理。
📦 SingProbe 是什么:5.67M 参数的流式安全探针
传统做法是在大模型旁边再跑一个 8B 级别的安全审查模型,而 SingProbe 的思路是"寄生式"探针——把一个小网络挂在基座模型内部,边生成边打分:
| 项目 | 取值 |
|---|---|
| 基座模型 | google/gemma-4-26B-A4B-it |
| 探针参数量 | 5.67M(约为基座的 1/4600) |
| 取样层(Tap 层) | 第 [8, 18, 28] 层隐藏状态 |
| 输出 | 8 种查询意图 + unsafe + 幻觉风险,共 10 类 |
评测结果(数据来自 README.md,均为各基准的平均值):
| 任务 | 指标 | SingProbe | 8B 级参考基线 |
|---|---|---|---|
| 查询意图分类 | F1 | 0.8439 | 0.8714 |
| 响应安全分类 | F1 | 0.8647 | 0.8604 |
| 流式安全 | R-AUC / T-AUC | 0.9740 / 0.9175 | 0.9640 / 0.8893 |
| 幻觉检测 | AUC | 0.7952 | 0.8000 |
值得注意的是:在流式安全这一最考验"边生成边拦截"能力的任务上,5.67M 的探针反超了 8B 级基线;良性响应的平均误报率仅 0.04%,解码开销 < 0.5%。这正是逐 Token 分类设计的价值所在。
🗂 仓库文件总览
| 文件 | 作用 |
|---|---|
| modeling_sing_probe.py | 核心模型代码:MLP 探针 + 注意力探针两条路线 |
| configuration_sing_probe.py | 两种配置类(MLP 版 / 注意力版),定义输入维度等超参 |
| config.json | 本检查点的实际配置,并通过 auto_map 注册到 transformers |
| model.safetensors | 探针权重(bfloat16,约 5.67M 参数) |
| README.md | 完整评测结果与 SGLang / vLLM 快速接入方式 |
config.json 中几个关键数字决定了后文所有计算:hidden_size: 2816(基座隐藏维度)、base_model_layer_ids: [8, 18, 28](3 个取样点)、num_attention_heads: 8、head_dim: 64、sliding_window: 2048、num_labels: 10。
本地检出源码以便阅读:
git clone https://gitcode.com/hf_mirrors/inclusionAI/gemma-4-26B-A4B-it-singprobe
🔍 逐段精读 modeling_sing_probe.py
1️⃣ 导入区:输入不是 Token,而是隐藏状态(L1–L10)
文件只依赖 torch 与 transformers 基础件(PreTrainedModel、ACT2FN、TokenClassifierOutput),末尾从本地导入两个配置类(modeling_sing_probe.py#L1-L10)。
2️⃣ 公共基类:输入校验与权重初始化(L13–L31)
SingProbePreTrainedModel 做了两件小事,但信息量很大:
main_input_name = "hidden_states":探针的输入不是词元 ID,而是基座模型前向时吐出的隐藏状态张量,形状为(batch, seq_len, 8448)——其中 8448 = 2816 × 3,即第 8/18/28 层隐藏态沿特征维直接拼接。_validate_input在每次前向开头强制校验最后一维必须等于hidden_size × 取样层数,配置不匹配会立刻抛出清晰的ValueError,避免训练/推理时静默出错。_init_weights:nn.Linear权重用 N(0, 0.02) 正态初始化、偏置清零,RMSNorm初始化为全 1——保证探针刚加载时输出接近中性,不会干扰基座生成。
3️⃣ MLP 版:逐 Token 独立分类(L34–L57)
SingProbeMlpModel 是最简版本,两条线性层加一个激活:
self.fc1 = nn.Linear(config.input_size, config.intermediate_size) # 8448 → 1024
self.fc2 = nn.Linear(config.intermediate_size, config.num_labels) # 1024 → 10
forward 依次执行 fc1 → GELU → fc2,输出 (batch, seq_len, 10) 的 logits。它没有任何跨 Token 交互——每个位置独立打分,相当于"只看当前词、不看上下文"的轻量基线,也便于理解注意力版到底强在哪里。
4️⃣ 核心探针:SingProbeAttnModel 的构造(L60–L78)
真正的明星是 SingProbeAttnModel。构造时先做合法性检查(头数、head_dim、滑窗必须为正),然后搭出 6 个模块:
| 模块 | 映射维度 | 参数量 | 角色 |
|---|---|---|---|
proj_q |
8448 → 512(无偏置) | 4,325,376 | Query 投影,8 头 × 64 维 |
proj_k |
8448 → 64(无偏置) | 540,672 | Key 投影,仅 1 个 KV 头 |
proj_v |
8448 → 64(无偏置) | 540,672 | Value 投影,仅 1 个 KV 头 |
o_proj |
512 → 512 | 262,144 | 输出投影(残差支路) |
norm |
RMSNorm(512, eps=1e-6) | 512 | 分类前归一化 |
classifier |
512 → 10 | 5,130 | 十类打分头 |
加总 5,674,506 ≈ 5.67M 参数,与 README 完全吻合。Q 侧 8 头、K/V 侧 1 头——这正是 GQA(Grouped Query Attention)的 8:1 配置,细节见下文原理章节。
5️⃣ 滑窗注意力:2048 窗口如何切长序列(L80–L109)
_sliding_window_attention 仅在序列长度超过 2048 时触发,逻辑分三步:
- 按窗口分块:
for start in range(0, seq_len, window),每块最多 2048 个查询位置; - 构造因果滑窗掩码,核心只有两行:
relative_positions = query_positions[:, None] - key_positions
attention_mask = (relative_positions >= 0) & (relative_positions < window)
含义:一个 token 只能看自己及前面 2047 个 token(相对位移在 [0, 2048) 区间内),既保持因果性(不看未来),又限制视野(不看 2048 之外的历史);
3. 每块调用一次 F.scaled_dot_product_attention,并传入 enable_gqa 让内核自动把单个 KV 头广播给 8 个 Query 头,最后把各块输出在序列维 torch.cat 拼回完整结果。
以 4096 个 token 为例:第一块查询位置 0–2047,键范围 0–end;第二块查询位置 2048–4095,key_start = max(0, 2048-2048+1) = 1,即每个查询回看自身及前 2047 个位置。计算复杂度从全因果注意力的 O(s²) 降为 O(s × 2048),长序列下收益显著。
6️⃣ forward 主流程:从 8448 维向量到 10 个分数(L111–L142)
forward 的执行链非常清晰:
- 对齐精度:把输入 cast 到
classifier权重的 dtype(bfloat16); - GQA 重塑:Query 重塑为
(batch, 8, seq, 64),K/V 为(batch, 1, seq, 64),即 8 个查询头共享 1 组键值; - 双路选择:序列 ≤ 2048 走标准因果 SDPA(
is_causal=True);超过 2048 走上面的滑窗路径; - 残差连接 + 归一化:
o_proj(context) + query_features——查询向量自身作为残差加回,避免注意力丢失当前词信息; - 十类分类:
RMSNorm后经classifier输出(batch, seq_len, 10)的 logits,封装为TokenClassifierOutput返回。
🧠 GQA 注意力原理:为什么 8 个 Query 头共享 1 个 K/V 头
普通多头注意力中,8 个头各自拥有一套 Key/Value,投影维度是 8 × 64 = 512;而这里 proj_k/proj_v 的输出只有 64 维——K/V 侧参数与显存占用直接砍掉 8 倍。
这背后的分工很讲究:
- Query 侧(8 头):负责"多角度提问",不同头可以分别关注意图、措辞风险、事实一致性等不同语义;
- K/V 侧(1 头):负责"提供通用答案",学到一组所有查询头都能复用的表示。
enable_gqa=True 参数告诉底层 SDPA 内核:键值只有 1 个头,请在计算时自动广播给 8 个查询头。对流式推理场景尤其友好——KV 缓存只需保存 64 维而非 512 维,配合 2048 滑窗,每个新 token 到来时的额外计算被压缩到极小,这就是解码开销 < 0.5% 的来源。
🏷 逐 Token 分类:10 个分数如何支撑"流式安全"
生成过程中模型每吐出一个新 token,探针就同步产出一组 10 维分数(label_0–label_9):前 8 个对应 8 种查询意图,另 2 个分别是响应不安全分与幻觉风险分。
与传统"生成完再审查"不同,这里的分类是因果滑窗注意力支撑的:每个 token 的分数都感知了它前面最多 2048 个 token 的上下文,因此能基于语境而非孤立词面做判断。服务端(SGLang / vLLM 集成分支)在每个 token 处返回这个分数字典,业务侧即可实时拦截或改写,这也是流式安全指标(R-AUC 0.9740)反超 8B 级基线的原因——审查与生成同频,而非事后补救。
⚡ 参数账本:5.67M 从哪来、开销为何 < 0.5%
| 模块 | 参数量 |
|---|---|
proj_q(8448×512) |
4,325,376 |
proj_k(8448×64) |
540,672 |
proj_v(8448×64) |
540,672 |
o_proj(512×512) |
262,144 |
classifier(512×10 + 偏置) |
5,130 |
RMSNorm(512) |
512 |
| 合计 | 5,674,506 |
对比 26B 基座,探针仅占约 0.02% 的参数量。流式解码每步新增的计算只是这几次小矩阵乘法(外加窗口内的注意力),且 2048 滑窗硬性限制了上下文扫描长度——参数量小 × 上下文有界,双重保证了 < 0.5% 的解码开销与 0.04% 的良性误报率。
🚀 快速接入:SGLang / vLLM 启动探针
探针通过 SGLang 或 vLLM 的集成分支加载,启动时挂载基座模型与探针检查点(命令来自 README.md):
python -m sglang.launch_server \
--model-path google/gemma-4-26B-A4B-it \
--probe-ckpt inclusionAI/gemma-4-26B-A4B-it-singprobe \
--port 30000
注意两点:基座模型必须与本探针成对使用(google/gemma-4-26B-A4B-it + 本检查点);接口会对每个生成的 token 返回一个 label_0–label_9 的分数字典,供下游策略消费。
✅ 小结:三大设计要点速记
- 输入:第 8/18/28 层隐藏态拼接成 8448 维向量,校验器保证维度严格匹配;
- GQA 8:1:8 个 Query 头共享 1 组 64 维 K/V,KV 侧开销降低 8 倍,
enable_gqa由 SDPA 内核自动广播; - 2048 滑窗:相对位移掩码
[0, 2048)保证因果 + 限窗,复杂度从 O(s²) 降到 O(s×2048); - 逐 Token 十类输出:8 意图 + unsafe + 幻觉,与生成同频,实现真正的流式安全拦截。
整个文件不到 150 行,却完整体现了"用小探针换大模型安全能力"的工程哲学——如果你只读一个文件理解 SingProbe,读它就够了。