modeling_sing_probe.py逐行精读:gemma-4-26B-A4B-it-singprobe的GQA注意力、滑窗与逐Token分类原理

原创2026-10-16 13:26:201,435 阅读

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 时触发,逻辑分三步:

  1. 按窗口分块:for start in range(0, seq_len, window),每块最多 2048 个查询位置;
  2. 构造因果滑窗掩码,核心只有两行:
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 的执行链非常清晰:

  1. 对齐精度:把输入 cast 到 classifier 权重的 dtype(bfloat16);
  2. GQA 重塑:Query 重塑为 (batch, 8, seq, 64),K/V 为 (batch, 1, seq, 64),即 8 个查询头共享 1 组键值;
  3. 双路选择:序列 ≤ 2048 走标准因果 SDPA(is_causal=True);超过 2048 走上面的滑窗路径;
  4. 残差连接 + 归一化:o_proj(context) + query_features——查询向量自身作为残差加回,避免注意力丢失当前词信息;
  5. 十类分类: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,读它就够了。

登录后查看全文
gemma-4-26B-A4B-it-singprobe