privyscope-zh-hans

从简体中文文本中**检测并遮蔽个人信息（PII）**的引擎。它是 privyscope 系列的简体中文版本，能自动识别并遮蔽 姓名、电话号码、各类证件号、电子邮箱、地址、金融信息、非公开日期以及 认证凭据（密钥）。

⚠️ privyscope 只是辅助遮蔽的工具，并不保证去标识化或合规性。 详见局限性。

📖 English README

安装

pip install privyscope-zh-hans      # 会自动安装 `privyscope` 内核

一分钟上手

在 Python 中使用

from privyscope_zh_hans import Privyscope

engine = Privyscope.from_pretrained()                 # 首次运行时下载 ONNX 权重
result = engine.redact("我叫王伟，电话是13812345678，邮箱是 wang@example.com")

result.masked_text        # "我叫<PER>，电话是<PHONE>，邮箱是 <EMAIL>"
result.detected_spans     # [DetectedSpan(label="PER", start=2, end=4, ...), ...]
result.summary            # {"span_count": 3, "by_label": {"PER": 1, "PHONE": 1, "EMAIL": 1}, ...}

在终端中使用

privyscope redact "我叫王伟，电话是13812345678，邮箱是 wang@example.com"
cat notes.txt | privyscope redact --operating-point high_recall

文档

更详细的指南按用途整理在 docs/ 目录中：

能识别哪些项目

基础项目（正则 + NER）共 8 类： PER · PHONE · ID_NUM · EMAIL · LOC · BANK · DATE · SECRET。

还有仅用正则识别的扩展项目： PASSPORT · SOCIAL_CREDIT · PLATE · CRYPTO · IP · DEVICE · URL — 参见 privyscope_zh_hans/entity_config.yaml。

Stage-1 的正则规则来自 pii-pattern-engine 规则集。多数规则 都带有校验函数（校验和 / 字典检查），只是形状相似的数字不会被遮蔽。例如身份证号 会做校验位验证，电话号码则覆盖了纯数字、带分隔符、带 +86、座机等多种写法，避免只学到 单一格式。

privyscope_zh_hans/regex_rules.yaml 由 scripts/gen_regex_rules.py 自动生成， 每次构建都会被覆盖 —— 要改规则请修改该脚本，而不是 YAML。详见 CONTRIBUTING。

代码使用 BCP-47 脚本子标签 zh-Hans（简体）；与繁体 （privyscope-zh-hant，zh-Hant）的区别本质上是字形，而非地区。

工作原理

两阶段混合流水线，两路结果取并集合并（SRS §3.4）：

1. 正则过滤 —— 抓取电话、邮箱、证件号、银行卡、密钥等形状固定的 PII。
2. ONNX NER —— 抓取姓名、地址、非公开日期等需要结合上下文判断的 PII，采用 BIOES 词元分类器加约束 Viterbi 解码器。

推理阶段只依赖 ONNX Runtime，无需 PyTorch。默认以不漏检（召回优先）为主， 无需重新训练，只调整运行点即可改变行为。只有 微调时才需要 PyTorch。中文是逐字（char-level）切分，因此 不存在跨词元边界的问题。

模型与性能

• 结构 —— hfl/chinese-roberta-wwm-ext（Apache-2.0）编码器 → BIOES 词元分类头 → 约束 Viterbi 解码器。

• 发布产物 —— INT8 量化的 ONNX 模型，约 98 MB（在 ≤150 MB 预算内），最大序列 长度 256。权重首次使用时从 Hugging Face Hub 下载，并附带 SHA-256 checksum.txt 供完整性校验。

• 精度 —— 在与训练不重叠的验证集（1,000 句，typed/strict 评分，regex + NER 完整流水线）上的实体级 strict F1：

  PER	LOC	DATE	ID_NUM	BANK	PHONE	SECRET
  1.00	1.00	1.00	0.06	1.00	0.88	0.94

  micro-F1 为 0.906（1,000 句）。姓名、地址、日期、银行卡等项目已达到满分。 但 ID_NUM（居民身份证号）目前召回极低（约 0.03——1,000 句中的 18 位身份证号 绝大多数未被识别，命中的都正确故精确率为 1.0），这是当前已知短板，也是拉低 总分的主要原因，我们会在后续迭代中修复。该验证集混入了口语、错字、无空格等写法， 并以 strict（偏移完全一致）评分，因此是保守下限，干净文本会更高。EMAIL 由正则确定性识别，本次样本中未出现。可用 privyscope eval --lang zh_hans your_val.jsonl 复现。

实战示例：网购咨询

下面是一位顾客发给购物平台的真实咨询（约 210 字，含姓名、日期、邮箱、电话、 地址、银行卡号），经过 engine.redact() 处理后的结果。

输入

您好，我叫王伟。我在2024年3月14日购买的一双跑步鞋到现在还没有收到，因此想咨询一下。我在注册会员时使用的邮箱是 wang.wei92@gmail.com，白天可以联系到我的手机号码是 13812345678。收货地址是上海市浦东新区世纪大道100号，付款使用的是银行卡 4539-1488-0343-6467，并且已经支付成功。如果商品确实已经丢失，能否将货款退还到我的银行卡？请帮忙查询一下目前的物流状态，并尽快给我回复。非常感谢您的帮助。

遮蔽结果（result.masked_text）

您好，我叫<PER>。我在<DATE>购买的一双跑步鞋到现在还没有收到，因此想咨询一下。我在注册会员时使用的邮箱是 <EMAIL>，白天可以联系到我的手机号码是 <PHONE>。收货地址是<LOC>，付款使用的是银行卡 <BANK>，并且已经支付成功。如果商品确实已经丢失，能否将货款退还到我的银行卡？请帮忙查询一下目前的物流状态，并尽快给我回复。非常感谢您的帮助。

识别出的 6 项

局限性

• 不保证去标识化或合规。请将它作为隐私设计中的多重防线之一来使用。
• 也有识别不好的情况：少见或地域性强的姓名可能漏检；上下文含糊时可能过度遮蔽 公众人物；在格式高度混杂的文本中跨度可能被切碎；对全新格式的 SECRET 可能漏检。
• 在医疗、法律、金融、政务等敏感场景中，建议再由人工复核一遍。

许可证

以 Apache-2.0 发布。模型权重同样是 Apache-2.0，连同用于完整性校验的 checksum.txt（SHA-256）一起发布在 Hugging Face Hub 上。欢迎贡献 —— 详见 CONTRIBUTING.md。