infer_banking.py 逐行源码解读:银行意图识别模型 deepopen-banking77-sam13-v1 的 FP32 推理与 SDPA 注意力实现
infer_banking.py 逐行源码解读:银行意图识别模型 deepopen-banking77-sam13-v1 的 FP32 推理与 SDPA 注意力实现
deepopen-banking77-sam13-v1 是一个基于 ModernBERT 的 BANKING77 银行客服意图识别(77 类文本分类)模型,其核心推理入口 infer_banking.py 只有 11 行代码,却完整实现了 FP32 精度 + SDPA 注意力 的可复现推理流程。本文将逐行拆解这份源码,帮助新手理解生产级推理脚本中"锁定执行路径、保证数值可复现"的工程思路。
🧭 项目速览:一个 77 类银行意图识别模型
| 项目 | 说明 |
|---|---|
| 任务 | BANKING77 银行客服文本分类(77 个意图,单标签) |
| 基座模型 | ModernBERT 序列分类(28 层、hidden 1024、16 头注意力,见 config.json) |
| 训练策略 | 从历史 checkpoint 用 SAM(Sharpness-Aware Minimization)续训,seed 13,BF16 训练 |
| 冻结测试成绩 | 94.1234%(2899/3080),记录于 RELEASE.json |
| 推理协议 | eager 执行、FP32 精度、SDPA 注意力、batch 32、max length 128 |
📌 注意:该 checkpoint 是在观察三组回测结果后选取的最优 seed(SAM 13/42/87 分别 2899/2896/2894),配对置信区间包含零,README 中明确未声明其为 SOTA。这种"诚实披露"本身值得学习。
🚀 如何跑通:安装与一键推理
环境要求 Python 3.12,版本已完整锁定在 requirements-py312-lock.txt(torch 2.9.1 / transformers 4.57.6)。有 NVIDIA GPU 可走 CUDA,无 GPU 自动回退 CPU:
python -m pip install -r requirements.txt
python infer_banking.py --checkpoint . --text "what is my bank balance"
💡 仓库需完整下载——README.md 明确说明:自定义 tokenizer、config 与 Python 文件缺一不可,通用的 pipeline 方式不适用于此自定义 CLINC 发布包。--text 参数可重复传入以批量处理多条文本。
📖 infer_banking.py 逐行解读
整份脚本仅 11 行(infer_banking.py),但每一行都有明确目的。下面按功能分块拆解。
1)第 1–4 行:锁定后端与依赖引入
import os
os.environ['USE_TF']='0'
import argparse,json,torch
from transformers import AutoTokenizer,AutoModelForSequenceClassification
USE_TF='0'必须在 import transformers 之前设置,强制选择 PyTorch 后端,避免环境中装有 TensorFlow 时发生后端冲突;- 只引入
AutoTokenizer与AutoModelForSequenceClassification两个入口,模型架构ModernBertForSequenceClassification会从 config.json 自动解析。
2)第 5 行:禁用 torch.compile,锁定 eager 执行
torch._dynamo.config.disable=True
这是整个脚本可复现性的关键一行。它全局禁用 PyTorch 2.x 的 dynamo/compile 路径,确保前向永远走 eager(逐算子)执行。项目评估协议固定为 "eager FP32 SDPA"(见 evaluation/banking_continuation_protocol.json),而 evaluation/banking_execution_audit.json 的审计结果显示:执行路径与精度的选择会影响最终正确数(历史 94.0909% vs 当前 eager FP32 93.9935%)。因此宁可放弃编译加速,也要保证"任何人、任何机器跑出相同结果"。
3)第 6 行:命令行参数
p=argparse.ArgumentParser();p.add_argument('--checkpoint',required=True);p.add_argument('--text',action='append',required=True);a=p.parse_args()
--checkpoint:模型目录(含 model.safetensors、config.json、tokenizer 文件),通常传.;--text使用action='append',可传多次,天然支持批量推理。
4)第 7 行:加载模型——核心行
tok=AutoTokenizer.from_pretrained(a.checkpoint,local_files_only=True)
m=AutoModelForSequenceClassification.from_pretrained(a.checkpoint,local_files_only=True,attn_implementation='sdpa').eval()
device='cuda' if torch.cuda.is_available() else 'cpu';m.to(device)
这一行包含三个要点:
| 要点 | 含义 |
|---|---|
local_files_only=True |
纯离线加载,绝不访问网络,保证"下载一次、到处运行" |
attn_implementation='sdpa' |
启用 PyTorch 内置的 Scaled Dot-Product Attention:GPU/CPU 上均走优化内核,无需额外安装 FlashAttention 等第三方库,跨平台一致 |
.eval() + 设备选择 |
关闭 dropout 等训练态行为(config 中 classifier_dropout=0.1 会被真正关闭);有 CUDA 用 CUDA,否则回退 CPU |
模型权重存于 model.safetensors,config 中 dtype: float32 表明以 FP32 存储。
5)第 8 行:批量 tokenize
b=tok(a.text,padding=True,truncation=True,max_length=128,return_tensors='pt').to(device)
max_length=128 与评估协议中的 maximum length 128 严格一致——推理参数与评测参数对齐是结果可比的前提。padding=True 支持一次传入多句话,return_tensors='pt' 直接产出 PyTorch 张量并送上设备。
6)第 9 行:inference_mode 下的 FP32 前向
with torch.inference_mode():pr=m(**b).logits.float().softmax(-1)
torch.inference_mode()比no_grad更轻量,明确声明"此块不参与自动微分",省去图构建开销;.logits.float()显式把 logits 转回 FP32 再做 softmax,确保 77 维概率分布在双精度浮点语义下计算,避免低精度累积误差;softmax(-1)输出每个意图类别的归一化概率。
7)第 10 行:数值健壮性断言
assert torch.isfinite(pr).all()
一行 assert 拦截 NaN/Inf——如果权重损坏或输入异常导致非有限值,程序会立即失败而不是把脏概率打印出去。这是"失败要响亮(fail fast)"原则的体现。
8)第 11 行:自描述 JSON 输出
print(json.dumps([{'text':t,'intent':m.config.id2label[int(v.argmax())],'probability':float(v.max()),'precision':'FP32','compile':False} for t,v in zip(a.text,pr)],indent=2))
输出中除 text、intent、probability 外,还刻意带上 "precision":"FP32" 与 "compile":False 两个元数据字段——把"用什么条件跑出来的"写进结果本身,方便下游审计与归档。77 个类别名来自 config.json 中的 id2label 映射(如 card_arrival、pin_blocked 等)。
🔍 为什么坚持 FP32 + SDPA 组合?
结合 evaluation/banking_execution_audit.json 的审计结论,可以读出三条设计动机:
- 精确性可复现:审计证明了"执行路径敏感性"——编译、精度、批处理等路径差异会改变预测计数。固定 eager + FP32 + SDPA 后,推理结果与冻结预测 evaluation/predictions.csv 可以做到零差异比对;
- SDPA 是"最大公约数"注意力:相比 FlashAttention(需特定硬件/内核)或纯 Python eager 注意力(慢),
attn_implementation='sdpa'由 PyTorch 官方实现,CPU/CUDA 行为一致且性能足够; - 概率不等于校准置信度:README 特别提醒"预测概率不提供校准的 OOS 拒绝"——不要把
probability当作异常流量拦截阈值直接使用。
🗂 仓库里还有哪些值得看的文件
| 文件 | 作用 |
|---|---|
| verify_release.py | 冻结预测复现校验器:对全部 3080 条 gold 标签逐行比对,要求零差异 |
| evaluation/predictions.csv | 每条测试样本的冻结预测(不含原文) |
| evaluation/classes.csv | 每类准确率/precision/F1 统计 |
| evaluation/banking_continuation_summary.json | 7 组权重(3 对照 + 3 SAM + 历史)的完整对比 |
| SHA256SUMS.json | 绑定全部发布文件的 SHA256 指纹 |
| training_source/ | 归档的原始研究脚本(SAM 续训、评估、边界分析),非一键复训环境,说明见 training_source/README.txt |
想验证"我拿到的模型就是发布的模型",可单独获取官方测试集后运行:
python verify_release.py --package banking_sam13 --checkpoint . --data /path/to/test.jsonl --output reproduction.json
⚠️ 校验失败时应当报告,而不是反过来调整模型——这是一次回顾性复现审计,不构成独立基准结果。
❓ 新手常见疑问
问:没有 GPU 能用吗? 能。第 7 行会自动检测 torch.cuda.is_available(),无 CUDA 时回退 CPU,只是速度更慢。
问:能换 FlashAttention 提速吗? 技术上可以,但会偏离发布的 "eager FP32 SDPA" 评估协议,结果不再与冻结预测严格可比——这正是脚本禁用 compile、固定 SDPA 的取舍。
问:为什么不用 pipeline("text-classification", ...)? 该发布包含自定义 tokenizer 配置与现代架构参数(局部/全局注意力、稀疏预测开关等),通用 pipeline 不支持这些自定义 CLINC 发布包(见 README.md)。
问:输出概率能直接当置信度用吗? 不建议。概率未经校准,不能直接作为 out-of-scope 拒绝阈值,需要自行做校准实验。
✅ 小结
infer_banking.py 用 11 行代码示范了可复现推理脚本的完整清单:锁定后端(USE_TF=0)→ 禁用编译(dynamo off)→ 离线加载(local_files_only)→ 固定注意力实现(SDPA)→ 对齐评测超参(max length 128)→ FP32 softmax → 有限值断言 → 自描述输出。对于任何需要在生产环境中保证"结果可审计、可复现"的 NLP 模型,这套写法都值得直接借鉴。