仓库文件逐个拆:bert-small-pii-detection PII检测模型8大核心文件完全解读
仓库文件逐个拆:bert-small-pii-detection PII检测模型8大核心文件完全解读
bert-small-pii-detection 是一个基于 BERT 微调的英文个人敏感信息(PII)检测模型,能识别邮箱、电话、信用卡、美国社保号等 25 类隐私实体。整个仓库没有任何代码,全部由 8 大核心文件构成,麻雀虽小五脏俱全。本文逐个拆开这 8 个文件,讲清每个文件的作用、体积和选用场景,帮你快速上手这个 PII 隐私检测模型仓库。
🗂 仓库全景:8大核心文件一览表
| 核心文件 | 真实大小 | 一句话作用 |
|---|---|---|
| README.md | 14 KB | 模型说明书:用途、25 类标签、评估指标 |
| config.json | 3 KB | 架构参数 + 51 个标签映射(模型"身份证") |
| model.safetensors | ≈109 MB | PyTorch 推理权重(FP32) |
| model.onnx | ≈109 MB | ONNX 跨框架权重(FP32) |
| model.quant.onnx | ≈27 MB | ONNX INT8 量化权重(约为 1/4 体积) |
| tokenizer.json | 695 KB | 快速分词引擎(完整分词规则) |
| tokenizer_config.json + special_tokens_map.json | 2 KB | 分词参数与 5 个特殊 token(配置对,合并计 1 项) |
| vocab.txt | 227 KB | WordPiece 词表(30,522 个词元) |
💡 3 个大体积模型文件在仓库中通过 Git LFS 存储,直接浏览时只会看到 LFS 指针文件;
git clone时会自动拉取真实内容。
📋 README.md:模型卡片,先读它
README.md 是整个仓库的"说明书",关键信息包括:
- 模型来源:由
prajjwal1/bert-small微调而来,训练数据集为gravitee-io/pii-detection-dataset,任务是 token 分类(token-classification); - 25 类标签:AGE、CREDIT_CARD、DATE_TIME、EMAIL_ADDRESS、IP_ADDRESS、LOCATION、ORGANIZATION、PERSON、PHONE_NUMBER、US_SSN 等,完整清单见 README.md;
- 核心指标:官方评估集上 F1 0.8686、精确率 0.8182、召回率 0.9256,见 README.md;
- 外部基准:在
beki/privy:test-large(12 万条样本)上 FP32 micro F1 高达 0.9833,INT8 量化后仍有 0.9825,见 README.md; - 适用场景:隐私过滤、脱敏流水线(redaction)、数据防泄漏,尤其适合 JSON / HTML / XML / SQL 等结构化文本;
- 已知局限:仅针对英文优化,其他语言效果会下降,且存在领域漂移,建议在自己的数据上复测。
🧬 config.json:架构蓝图 + 标签体系
config.json 决定了模型"长什么样"。作为 bert-small,它的体量确实小巧:
| 参数 | 值 | 含义 |
|---|---|---|
num_hidden_layers |
4 | Transformer 层数("small" 的关键) |
hidden_size |
512 | 隐藏层维度 |
num_attention_heads |
8 | 注意力头数 |
intermediate_size |
2048 | 前馈网络中间维度 |
max_position_embeddings |
512 | 最大输入长度(token 数) |
vocab_size |
30,522 | 词表大小,与 vocab.txt 行数一致 |
architectures |
BertForTokenClassification | 末尾接 token 分类头 |
更值得看的是标签体系:id2label 定义了 51 个标签 = 1 个 O(非实体)+ 25 个实体类型 × 2(B- 开头 / I- 内部),即经典的 BIO 标注方案,映射关系见 config.json。例如 "John Smith" 会被打为 B-PERSON / I-PERSON,模型正是靠逐 token 打分来圈出隐私片段。
⚖️ model.safetensors:PyTorch 官方权重
- 真实大小约 109 MB(114,116,788 字节),float32 精度;
- 供
transformers生态直接加载:AutoModelForTokenClassification.from_pretrained一行搞定,配合pipeline("token-classification")即可跑通,示例见 README.md; - 相比传统
.bin,safetensors 格式支持内存映射加载,更快且不存在反序列化安全隐患,是当前的权重存储主流。
🚀 model.onnx:跨框架推理权重
- 同为 FP32,约 109 MB,由 PyTorch 模型转换而来;
- 用 onnxruntime 加载后无需安装 PyTorch,部署更轻量;输入
input_ids与attention_mask,输出每个 token 的 logits,再按config.json中的id2label映射成标签即可,完整流程见 README.md; - 适合已有 ONNX 推理栈(如网关、插件化服务)的团队。
📦 model.quant.onnx:INT8 量化版,体积砍到 1/4
- 通过 INT8 动态量化,从约 109 MB 压缩到 27 MB(28,732,710 字节);
- 精度损失极小:
beki/privy:test-large上 micro F1 仅从 0.9833 降到 0.9825,各实体分类指标几乎持平; - 内存受限、高并发、边缘设备场景,首选这个文件。
🔤 tokenizer.json:快速分词引擎
tokenzier.json 共 3 万多行,是 tokenizers 库定义的完整分词流水线:
- normalizer:清洗文本并统一转小写(
lowercase: true); - pre_tokenizer:
BertPreTokenizer按空格切分、处理中文字符; - WordPiece 解码:把单词拆成子词,例如 "john" →
john,罕见词 → 多个子词组合。
它是 vocab.txt 的"可执行版本",AutoTokenizer.from_pretrained 会优先用它,速度比纯 Python 实现快一个量级。
⚙️ tokenizer_config.json 与 special_tokens_map.json:分词配置对
- tokenizer_config.json:声明分词器类型为
BertTokenizer,do_lower_case: true、默认max_length: 256、右截断(truncation_side: right),关键参数见 tokenizer_config.json; - special_tokens_map.json:登记 5 个特殊 token 及其词表编号,见 special_tokens_map.json:
| Token | 编号 | 作用 |
|---|---|---|
[PAD] |
0 | 批处理填充 |
[UNK] |
100 | 未知词兜底 |
[CLS] |
101 | 序列起始标记 |
[SEP] |
102 | 序列分隔/结束 |
[MASK] |
103 | 掩码(本模型推理用不到) |
📖 vocab.txt:30,522 个词元的字典
vocab.txt 每行一个 WordPiece 词元,首行为 [PAD],紧随其后是 20 个 [unused0]~[unused19] 占位符,总行数 30,522,与 config.json 的 vocab_size 严格一致。它既是模型的"查词字典",也是 BertTokenizer(非快速版)独立工作的唯一依赖。
🧪 如何下载并验证仓库
git clone https://gitcode.com/hf_mirrors/gravitee-io/bert-small-pii-detection
克隆完成后可用一条命令快速核对文件完整性——三个权重文件应分别约为 109 MB / 109 MB / 27 MB:
du -h bert-small-pii-detection/model.*
若 model.* 只有几百字节,说明 LFS 大文件未拉取,执行 git lfs pull 即可补齐。
🧭 小结:按场景选择你的权重文件
| 使用场景 | 推荐文件 |
|---|---|
| PyTorch / transformers 开发调试 | model.safetensors |
| 跨框架部署、无 PyTorch 依赖 | model.onnx |
| 内存受限、高并发生产环境 | model.quant.onnx |
一句话总结:README 看能力,config 看架构,三个 model 文件按环境三选一,tokenizer 三件套 + vocab 负责把文本喂给模型。理清这 8 个核心文件的分工,你使用这个 PII 检测模型仓库就不会再迷路了。