Metadata-Version: 2.4
Name: privyscope-zh-hant
Version: 0.1.5
Summary: privyscope-zh-hant — Traditional Chinese language pack for the privyscope PII engine (regex ready; NER model pending)
Author: privyscope Core Team
License: Apache-2.0
Project-URL: Homepage, https://github.com/zafrem/privyscope-zh-hant
Project-URL: Documentation, https://github.com/zafrem/privyscope-zh-hant/blob/main/README.md
Keywords: pii,ner,redaction,privacy,chinese,traditional,onnx
Classifier: Development Status :: 3 - Alpha
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-hant

從繁體中文文本中**偵測並遮蔽個人資訊（PII）**的引擎。它是
[privyscope](https://github.com/zafrem) 系列的繁體中文版本，能自動辨識並遮蔽
姓名、電話號碼、各類證件號碼、電子郵件、地址、金融資訊、非公開日期以及
認證憑證（密鑰）。

> ⚠️ privyscope 只是**輔助**遮蔽的工具，並不保證去識別化或法規遵循。
> 詳見[限制](#限制)。

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

## 安裝

```bash
pip install privyscope-zh-hant      # 會自動安裝 `privyscope` 核心
```

## 一分鐘上手

**在 Python 中使用**

```python
from privyscope_zh_hant import Privyscope

engine = Privyscope.from_pretrained()                 # 首次執行時下載 ONNX 權重
result = engine.redact("我叫陳志明，電話是0912-345-678，信箱是 chen@example.com")

result.masked_text        # "我叫<PER>，電話是<PHONE>，信箱是 <EMAIL>"
result.detected_spans     # [DetectedSpan(label="PER", start=2, end=5, ...), ...]
result.summary            # {"span_count": 3, "by_label": {"PER": 1, "PHONE": 1, "EMAIL": 1}, ...}
```

**在終端機中使用**

```bash
privyscope redact "我叫陳志明，電話是0912-345-678，信箱是 chen@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` · `UNIFIED_BUSINESS_NO` · `PLATE` · `CRYPTO` · `IP` · `DEVICE` · `URL`
— 參見 [`privyscope_zh_hant/entity_config.yaml`](privyscope_zh_hant/entity_config.yaml)。

Stage-1 的正規表示式規則來自
[pii-pattern-engine](https://github.com/zafrem/pii-pattern-engine) 規則集。多數規則
都帶有**驗證函式**（檢查碼 / 字典檢查），只是形狀相似的數字不會被遮蔽，例如中華民國
身分證字號（如 `A123456789`）會做檢查碼驗證。

> 分詞器以 `do_lower_case=True` 設定，讓大寫拉丁字母（身分證字號的開頭英文字母、
> 品牌名稱等）不會變成 `[UNK]` —— 訓練與推論必須使用相同設定。

> `privyscope_zh_hant/regex_rules.yaml` 由 `scripts/gen_regex_rules.py` **自動產生**，
> 每次建置都會被覆寫 —— 要改規則請修改該腳本，而非 YAML。詳見
> [CONTRIBUTING](CONTRIBUTING.md)。

代碼使用 BCP-47 腳本子標籤 **`zh-Hant`**（繁體）；與簡體
（`privyscope-zh-hans`，`zh-Hans`）的區別本質上是字形，而非地區。

## 運作原理

**兩階段混合流水線**，兩路結果取聯集合併（SRS §3.4）：

1. **正規表示式過濾** —— 擷取電話、電子郵件、證件號、銀行卡、密鑰等形狀固定的 PII。
2. **ONNX NER** —— 擷取姓名、地址、非公開日期等需結合上下文判斷的 PII，採用
   BIOES 詞元分類器加約束 Viterbi 解碼器。

推論階段**只依賴 ONNX Runtime，不需要 PyTorch**。預設以不漏抓（召回優先）為主，
無需重新訓練，只調整[運行點](docs/OPERATING_POINTS.md)即可改變行為。只有
[微調](docs/FINETUNING.md)時才需要 PyTorch。中文是逐字（char-level）切分，因此
不存在跨詞元邊界的問題。

## 模型與效能

- **結構** —— `google-bert/bert-base-chinese`（Apache-2.0）編碼器 → BIOES 詞元分類頭 →
  約束 Viterbi 解碼器。
- **發布產物** —— INT8 量化的 ONNX 模型，約 **98 MB**（在 ≤150 MB 預算內），最大序列
  長度 256。權重首次使用時從 Hugging Face Hub 下載，並附帶 SHA-256 `checksum.txt`
  供完整性驗證。
- **精度** —— 在與訓練不重疊的驗證集（`typed`/strict 評分，regex + NER 完整流水線）
  上的實體級 strict F1：

  | PER | LOC | DATE | ID_NUM | BANK | PHONE | SECRET |
  |-----|-----|------|--------|------|-------|--------|
  | 1.00 | 0.14 | 0.92 | 0.91 | 0.95 | 0.96 | 0.89 |

  micro-F1 為 **0.918**（1,000 句）。姓名、電話、銀行卡、日期、身分證字號等項目都
  相當穩定，唯獨 `LOC`（地址）目前**邊界容易過度擷取**（常把「收件地址」等前綴一起
  框進去），是**已知短板**，也是把個別分數拉低的主因，我們會在後續迭代修正。此驗證
  集在本機以 `carriers/zh_hant.val.json` 產生（含口語 / 錯字 / 無空格寫法），並以
  strict（偏移完全一致）評分，屬**保守下限**，乾淨文本會更高。`EMAIL` 由正規表示式
  確定性辨識，本次樣本中未出現。可用 `privyscope eval --lang zh_hant your_val.jsonl`
  復現。

## 實戰範例：網購諮詢

以下是一位顧客寄給購物平台的真實諮詢（約 210 字，含姓名、日期、電子郵件、電話、
地址、信用卡號），經過 `engine.redact()` 處理後的結果。

**輸入**

```text
您好，我叫陳志明。我於2024年3月14日購買的一雙慢跑鞋到現在還沒有收到，因此想詢問一下。我在註冊會員時使用的電子郵件是 chen.ming92@gmail.com，白天可以聯絡到我的手機號碼是 0912-345-678。收件地址：台北市信義區信義路五段7號，付款使用的是信用卡 4539-1488-0343-6467，並且已經付款成功。如果商品確實已經遺失，能否將貨款退還到我的信用卡？請協助查詢目前的物流狀態，並盡快給我回覆。非常感謝您的幫助。
```

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

```text
您好，我叫<PER>。我於<DATE>購買的一雙慢跑鞋到現在還沒有收到，因此想詢問一下。我在註冊會員時使用的電子郵件是 <EMAIL>，白天可以聯絡到我的手機號碼是 <PHONE>。收件地址：<LOC>，付款使用的是信用卡 <BANK>，並且已經付款成功。如果商品確實已經遺失，能否將貨款退還到我的信用卡？請協助查詢目前的物流狀態，並盡快給我回覆。非常感謝您的幫助。
```

**辨識出的 6 項**

| 標籤 | 辨識到的文字 |
|---|---|
| `PER` | 陳志明 |
| `DATE` | 2024年3月14日 |
| `EMAIL` | chen.ming92@gmail.com |
| `PHONE` | 0912-345-678 |
| `LOC` | 台北市信義區信義路五段7號 |
| `BANK` | 4539-1488-0343-6467 |

## 限制

- 不保證去識別化或法規遵循。請將它作為隱私設計中的**多重防線之一**來使用。
- 也有辨識不佳的情況：少見或地域性強的姓名可能漏抓；上下文含糊時可能過度遮蔽
  公眾人物；在格式高度混雜的文本中跨度可能被切碎；對全新格式的 `SECRET` 可能漏抓。
- 在醫療、法律、金融、政務等敏感場景中，建議再由人工複核一遍。

## 授權

以 Apache-2.0 發布。模型權重同樣是 Apache-2.0，連同用於完整性驗證的
`checksum.txt`（SHA-256）一起發布在 Hugging Face Hub 上。歡迎貢獻 ——
詳見 [CONTRIBUTING.md](CONTRIBUTING.md)。
