从隐藏状态到安全分数:gpt-oss-120b-singprobe探针代码实现全解析
从隐藏状态到安全分数:gpt-oss-120b-singprobe探针代码实现全解析
gpt-oss-120b-singprobe 是一个流式安全护栏探针:它不额外运行独立的安全模型,而是复用 openai/gpt-oss-120b 生成过程中的隐藏状态(hidden states),为每一个 token 实时输出查询意图、响应不安全性和幻觉风险三类安全分数,解码开销不到 0.5%。本文将带你用通俗的方式读懂这套探针的完整代码实现。
🎯 什么是 SingProbe:给大模型装一枚"实时安全探针"
传统做法是在生成结束后再跑一个独立的安全分类模型来判断内容是否安全,这既增加延迟,又无法在流式输出过程中实时拦截风险。SingProbe 的思路完全不同:
在模型逐 token 生成的同时,直接从模型内部"摘取"信号,即时打分。
它可以理解为在大模型内部嵌入了一枚微型探针:
| 特性 | 说明 |
|---|---|
| 基座模型 | openai/gpt-oss-120b |
| 探针参数量 | 仅 5.8M(相对 120B 基座可忽略不计) |
| 采样层 | 第 [10, 22, 34] 层隐藏状态 |
| 输出 | 8 种查询意图 + 不安全响应 + 幻觉风险,共 10 个分数 |
| 解码开销 | < 0.5% |
官方评测显示,探针在流式安全检测上的 R-AUC / T-AUC 达到 0.9881 / 0.9454,良性响应误报率平均仅 0.06%,详见 README.md。
📁 项目结构一览:四个文件读懂整个探针
这个仓库刻意保持极简——探针的全部"智慧"都在配置与模型定义里:
| 文件 | 作用 |
|---|---|
| config.json | 探针模型的运行配置(架构、层数、标签数等) |
| configuration_sing_probe.py | 探针的配置类(Config),供 transformers 自动加载 |
| modeling_sing_probe.py | 探针的模型本体(Model),核心网络结构都在这里 |
| model.safetensors | 探针训练好的权重文件 |
这种 config.json + configuration_*.py + modeling_*.py 的三件套,是 Hugging Face 生态中自定义模型的标准布局,理解了它就读懂了项目骨架。
⚙️ 配置文件解析:5.8M 探针是如何定义的
config.json 是整个探针的"身份证",关键字段如下:
architectures: 指定模型类为SingProbeAttnModel,即注意力版探针(下文详述);hidden_size: 2880: 基座模型每层的隐藏维度;base_model_layer_ids: [10, 22, 34]: 探针从基座的第 10、22、34 层摘取隐藏状态;num_labels: 10: 每个 token 输出 10 个分数(label_0~label_9);sliding_window: 2048: 注意力探针只回看最近 2048 个 token,兼顾精度与速度。
其中 auto_map 字段告诉 transformers 框架:加载这个仓库时,自动使用 configuration_sing_probe.py 里的 SingProbeAttnConfig 和 modeling_sing_probe.py 里的 SingProbeAttnModel——这就是"一行命令加载探针"能跑通的底层原因。
配置类还藏着一个关键计算:
@property
def input_size(self) -> int:
return self.hidden_size * len(self.base_model_layer_ids)
即探针的输入维度 = 2880 × 3 = 8640。每从基座"摘"一层,就拼接一段 2880 维的向量,三层拼起来就是探针的完整输入。
🧠 两类探针模型:MLP 极简版 vs 注意力主力版
打开 modeling_sing_probe.py,会发现仓库里其实定义了两种探针结构,都继承自公共基类 SingProbePreTrainedModel(负责权重初始化与输入校验):
MLP 版:最简单的两层前馈网络
SingProbeMlpModel(modeling_sing_probe.py)结构直白到一行就能说清:
拼接后的隐藏状态 → fc1 线性层 → GELU 激活 → fc2 线性层 → 10 个分数
它把三层隐藏状态拼成 8640 维向量后,用两个全连接层直接映射到 10 个标签。适合作为轻量对照基线,但对"上下文语义"的捕捉能力有限。
注意力版:本仓库真正部署的主力
SingProbeAttnModel(modeling_sing_probe.py)是目前发布的探针,config.json 中指定的就是它。它的前向流程可以拆成 5 步:
- 输入校验:检查输入维度是否为
hidden_size × 3 = 8640,不匹配立即报错; - Q / K / V 投影:用 3 个无偏置线性层把每个 token 的向量投影成 Query、Key、Value。注意 Q 投影到
8 头 × 64 维 = 512维,而 K、V 只有 1 个头——这是典型的 GQA(分组查询注意力) 设计,查询头多、键值头少,省显存又保效果; - 注意力聚合:序列长度不超过
sliding_window(2048)时,直接走因果注意力;超过则启用_sliding_window_attention(modeling_sing_probe.py),按 2048 窗口分块计算,每个查询只能看到窗口内的历史 token,把长文本下的计算量锁在常数级; - 残差连接:注意力输出经
o_proj后与 Query 特征相加,保留原始语义信息; - 归一化 + 分类头:RMSNorm 归一化后,线性层输出 10 个 logits,封装为
TokenClassifierOutput返回。
一句话总结:MLP 版是"拍扁直连",注意力版是"回看上下文再判断"——后者能利用前后文语义,这正是它成为主力的原因。
📊 分数怎么用:每个 token 都有 10 个标签
探针每生成一个 token,就会返回 label_0 ~ label_9 共 10 个分数,分别对应:
| 分数 | 含义 |
|---|---|
label_0 ~ label_7 |
8 种查询意图分类 |
label_8 |
响应不安全程度 |
label_9 |
幻觉风险程度 |
工程上最常见的用法:流式输出过程中持续监测 label_8,一旦分数越阈值就即时中断生成——风险还没扩散到用户眼前就被拦下,这就是"streaming guardrail"的价值所在。
🚀 如何一行命令部署 SingProbe 探针
探针通过 SGLang 或 vLLM 的集成分支加载,启动服务器时用 --probe-ckpt 指定探针即可:
python -m sglang.launch_server \
--model-path openai/gpt-oss-120b \
--probe-ckpt inclusionAI/gpt-oss-120b-singprobe \
--port 30000
⚠️ 注意:基座模型与探针必须成对使用(openai/gpt-oss-120b 配本探针),因为探针是"贴"在这套基座的隐藏状态上训练的,混用其他模型会导致分数失效。
如需获取仓库源码:
git clone https://gitcode.com/hf_mirrors/inclusionAI/gpt-oss-120b-singprobe
✅ 总结:为什么说它是"轻到极致"的安全方案
- 零额外模型:探针只有 5.8M 参数,寄生在基座的隐藏状态上工作;
- 真流式:每个 token 生成时同步出分,而非事后审查;
- 开销极小:解码加速比损失 < 0.5%,良性内容误报率仅 0.06%;
- 代码极简:一个配置类 + 一个模型类,不到 150 行就能读懂全部网络结构。
如果你想在自己的安全护栏方案中借鉴这种"复用基座内部信号"的思路,modeling_sing_probe.py 中的滑窗注意力与 GQA 投影实现,是非常值得精读的范例。