privyscope-zh-hant

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

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

📖 English README

安裝

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

一分鐘上手

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

在終端機中使用

privyscope redact "我叫陳志明，電話是0912-345-678，信箱是 chen@example.com"
cat notes.txt | privyscope redact --operating-point high_recall

文件

更詳細的指南依用途整理在 docs/ 目錄中：

能辨識哪些項目

基礎項目（正規表示式 + 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。

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

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

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

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

運作原理

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

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

推論階段只依賴 ONNX Runtime，不需要 PyTorch。預設以不漏抓（召回優先）為主， 無需重新訓練，只調整運行點即可改變行為。只有 微調時才需要 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() 處理後的結果。

輸入

您好，我叫陳志明。我於2024年3月14日購買的一雙慢跑鞋到現在還沒有收到，因此想詢問一下。我在註冊會員時使用的電子郵件是 chen.ming92@gmail.com，白天可以聯絡到我的手機號碼是 0912-345-678。收件地址：台北市信義區信義路五段7號，付款使用的是信用卡 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。