Metadata-Version: 2.4
Name: privyscope-zh-hans
Version: 0.1.5
Summary: privyscope-zh-hans — Simplified Chinese language pack for the privyscope PII engine
Author: privyscope Core Team
License: Apache-2.0
Project-URL: Homepage, https://github.com/zafrem/privyscope-zh-hans
Project-URL: Documentation, https://github.com/zafrem/privyscope-zh-hans/blob/main/README.md
Keywords: pii,ner,redaction,privacy,chinese,simplified,onnx
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: privyscope>=0.1.5
Provides-Extra: train
Requires-Dist: privyscope[train]>=0.1.0; extra == "train"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# privyscope-zh-hans

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

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

📖 **[English README](README.en.md)**

## 安装

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

## 一分钟上手

**在 Python 中使用**

```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}, ...}
```

**在终端中使用**

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

## 文档

更详细的指南按用途整理在 [`docs/`](docs/) 目录中：

| 我想…… | 指南 |
|---|---|
| 在终端里运行 | [CLI 参考](docs/CLI.md) |
| 从 Python 调用 | [Python API 参考](docs/API.md) |
| 理解 JSON 输出 | [输出结构](docs/OUTPUT_SCHEMAS.md) |
| 用自己的标注数据评分 | [评估与输出模式](docs/EVAL_AND_OUTPUT_MODES.md) |
| 权衡精确率与召回率 | [运行点](docs/OPERATING_POINTS.md) |
| 离线 / 内网使用 | [离线使用](docs/OFFLINE.md) |
| 用自己的数据微调 | [微调](docs/FINETUNING.md) |

## 能识别哪些项目

基础项目（正则 + 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`](privyscope_zh_hans/entity_config.yaml)。

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

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

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

## 工作原理

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

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

推理阶段**只依赖 ONNX Runtime，无需 PyTorch**。默认以不漏检（召回优先）为主，
无需重新训练，只调整[运行点](docs/OPERATING_POINTS.md)即可改变行为。只有
[微调](docs/FINETUNING.md)时才需要 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()` 处理后的结果。

**输入**

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

**遮蔽结果（`result.masked_text`）**

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

**识别出的 6 项**

| 标签 | 识别到的文本 |
|---|---|
| `PER` | 王伟 |
| `DATE` | 2024年3月14日 |
| `EMAIL` | wang.wei92@gmail.com |
| `PHONE` | 13812345678 |
| `LOC` | 上海市浦东新区世纪大道100号 |
| `BANK` | 4539-1488-0343-6467 |

## 局限性

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

## 许可证

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