Model Card for privacy-filter-tw

privacy-filter-tw 是專為中華民國台灣場景打造的 PII（個人識別資訊）偵測模型。本模型建構於 openai/privacy-filter 之上，新增 11 個台灣特有 PII 類別（身分證、健保卡、統一編號、車牌、護照、駕照、LINE ID、PTT 帳號、戶號、醫事字號、軍人證號），並針對繁體中文場景做大規模強化訓練，使其能精準辨識台灣場景中的個資格式（含民國紀年、中文姓名邊界、台灣地址、09xx 手機等）。

⚠️ 規格重點： 本模型為單次 forward pass 的 token-classification 模型，不是 chat / generative LM；使用模型自帶的 constrained Viterbi decoder（OPF 格式），不能透過 HuggingFace transformers.pipeline 載入。

Model Details

承續 openai/privacy-filter 開源的 PII 偵測架構（1.5B total / 50M active params, GPT-oss-style MoE backbone, banded bidirectional attention），原模型只支援 8 個 PII 類別且訓練語料以英文為主，在台灣場景有兩個明顯短板：

1. In-schema label 在 zh-TW 表現不均：中文姓名邊界、民國紀年、台灣地址 / 帳號格式都需要補強
2. 大量台灣常見 PII 類別不在 schema 內：身分證、健保卡、車牌、LINE ID 等都無法直接偵測

privacy-filter-tw 透過 lianghsun/tw-PII-chat（61,300 筆合成訓練資料，11 個台灣 OOD label 採頻率加權分佈）做完整 fine-tune，把這兩個 gap 補起來。

-tw 後綴明示這是針對 Taiwan locale 的特化版本，與通用版 openai/privacy-filter 並列使用而非取代。

核心特點 (Key Features)

1. 新增 11 個台灣特有 PII labels：

   • tw_national_id（身分證字號）、tw_nhi_card（健保卡）、tw_company_id（統一編號）
   • tw_passport（護照）、tw_driver_license（駕照）、tw_license_plate（車牌）
   • tw_line_id（LINE ID）、tw_ptt_id（PTT 帳號）
   • tw_household_no（戶號 / 房屋稅籍）、tw_medical_license（醫事人員字號）、tw_military_id（軍人證號）

2. In-schema 8 labels 全面強化：

   • In-schema 整體 strict micro F1 從 57.6% 提升到 86.0%（+28.4pp）
   • 民國紀年 32.7% → 82.4%（+49.7pp）；中文姓名 40.9% → 82.1%（+41.1pp）；地址 54.5% → 85.4%（+30.8pp）

3. 保留 OPF 原生推論架構：

   • 完全相容於 openai/privacy-filter 的 inference 流程（custom Viterbi decoder + banded attention）
   • 同樣的 original/* checkpoint 格式，可用 opf CLI 直接載入
   • Context window 128k，與 base 一致

Model Description

• Developed by: Liang Hsun Huang
• Base model: openai/privacy-filter (1.5B total / 50M active params, MoE-128 top-4)
• Model type: Token Classification (BIOES, 77 classes = 1 background + 19 labels × 4 boundary tags)
• Language(s) (NLP): Traditional Chinese (Taiwan) & English
• License: Apache 2.0
• Format: OPF-native checkpoint（非 HuggingFace AutoModelForTokenClassification 相容格式）

Model Sources

• Repository: lianghsun/privacy-filter-tw
• Training dataset: lianghsun/tw-PII-chat（gated, manual review）
• Evaluation benchmark: lianghsun/tw-PII-bench
• Live dashboard: openai-pii-bench.lianghsun.dev

Evaluation

Head-to-head vs openai/privacy-filter — across all 3 splits

評測於 lianghsun/tw-PII-bench 全 3 個 split（910 題：short 310 + mid 300 + long 300）。兩個模型皆採用模型原生 Viterbi decoder（非 HF pipeline）。

Per-split in-schema strict micro F1

Split	文字長度	Items	openai/privacy-filter	🌟 privacy-filter-tw	Δ
short	15-120 字	310	57.6%	86.0%	▲ +28.4pp
mid	200-1000 字	300	59.9%	71.5%	▲ +11.7pp
long	1500-5000 字	300	51.7%	50.0%	▼ -1.7pp
all	—	910	54.1%	56.1%	▲ +2.0pp

⚠️ 重要觀察：本模型訓練語料（tw-PII-chat）皆為短句（ctx=512），因此 short / mid 領先幅度大，long 與 base 模型幾乎打平。要在長文本上維持優勢，下一輪 fine-tune 需加入長文本訓練樣本。詳見 Known limitations。

Overall metrics (all 3 splits combined)

Metric	openai/privacy-filter	🌟 privacy-filter-tw	Δ
In-schema strict micro F1	54.1%	56.1%	▲ +2.0pp
In-schema micro precision	49.9%	44.2%	▼ -5.7pp
In-schema micro recall	59.1%	76.6%	▲ +17.5pp
In-schema relaxed micro F1 (IOU>0.5)	57.9%	62.5%	▲ +4.6pp
OOD detection rate (any overlap)	68.2%	96.5%	▲ +28.3pp
OOD generalization rate (correct label)	48.2%	88.9%	▲ +40.8pp
Hard-negative FP / item (short only)	0.40	0.78	▼ +0.38（trade-off）

Per-label F1 — In-schema 8 labels (overall, strict span+label)

Label	openai/privacy-filter	🌟 privacy-filter-tw	Δ
private_person	36.3%	55.8%	▲ +19.5pp
private_phone	86.7%	69.7%	▼ -17.0pp
private_email	67.8%	59.5%	▼ -8.3pp
private_address	69.9%	73.4%	▲ +3.5pp
private_date	19.1%	44.6%	▲ +25.5pp
private_url	21.3%	42.5%	▲ +21.2pp
account_number	72.7%	75.0%	▲ +2.2pp
secret	65.1%	42.4%	▼ -22.7pp

部分 in-schema label（phone / email / secret）在 mid+long 拖累下 overall 微跌，但在 short split 上 fine-tune 模型仍全面領先（短句場景 phone 90.7%、email 88.9%、secret 76.6%）。

Per-label F1 — Taiwan OOD 11 labels (overall, strict)

Label	openai/privacy-filter	🌟 privacy-filter-tw	Δ
tw_national_id 身分證字號	0.0%	82.9%	▲ +82.9pp
tw_nhi_card 健保卡	0.0%	84.8%	▲ +84.8pp
tw_company_id 統一編號	0.0%	90.3%	▲ +90.3pp
tw_passport 護照	0.0%	87.9%	▲ +87.9pp
tw_driver_license 駕照	0.0%	88.9%	▲ +88.9pp
tw_license_plate 車牌	0.0%	78.2%	▲ +78.2pp
tw_line_id LINE ID	0.0%	85.2%	▲ +85.2pp
tw_ptt_id PTT 帳號	0.0%	62.7%	▲ +62.7pp
tw_household_no 戶號	0.0%	86.9%	▲ +86.9pp
tw_medical_license 醫事字號	0.0%	80.9%	▲ +80.9pp
tw_military_id 軍人證號	0.0%	59.8%	▲ +59.8pp

11 個 Taiwan OOD label 全部從 0% 提升到 60-90% 區間。tw_military_id 與 tw_ptt_id 是相對弱項（訓練樣本最少分別 300 / 500 筆）。

Known limitations

1. Long-context regression（最重要）：long split (1500-5000 字) F1 50.0%，與 base 模型 51.7% 打平甚至略低。原因是 tw-PII-chat 訓練資料皆為單句 / 段落級別、訓練 ctx=512。長文本 fine-tune 是 v2 必要強化方向（混入 context-extended 訓練樣本 / curriculum 拉長 ctx）。
2. Hard-negative FP 偏高（0.78/題）：fine-tune 後 recall 大漲（76.6% vs 59.1%），但 precision 退步（44.2% vs 49.9%）— 對「看起來像 PII 的非 PII」（商家名、地標、客服電話）變得更敏感。下版需加入 hard negative 訓練資料矯正。
3. 部分 in-schema label overall 退步：private_phone、private_email、secret 在 mid+long context 中 F1 下降（雖然 short 上仍進步）。可能與 long-context regression 同源。
4. tw_military_id 與 tw_ptt_id 偏弱：訓練資料量最少（300 / 500 筆），且 Gemini 對軍人證號實際格式掌握有誤；下版需補強。
5. 未涵蓋少數族群名 / 罕見字：原住民傳統名、客語姓名邊界判定仍有 edge case。

How to Run Inference

1️⃣ 安裝 OPF CLI

pip install -e git+https://github.com/openai/privacy-filter#egg=opf

2️⃣ 下載模型

huggingface-cli download lianghsun/privacy-filter-tw --local-dir ./privacy-filter-tw

3️⃣ 跑單句推論

opf --checkpoint ./privacy-filter-tw "你好，我是王小明，身分證字號 A123456789，手機 0912-345-678。"

4️⃣ Python 直接呼叫（vendored Decoder 範例）

完整可執行範例見 tw-PII-bench companion repo 的 scripts/lib/privacy_filter_lib.py：

from pathlib import Path
import privacy_filter_lib as pf

runtime = pf.get_runtime(model_dir=Path("./privacy-filter-tw"))
decoder = pf.Decoder(label_info=runtime.label_info, model_dir=Path("./privacy-filter-tw"))

text = "您好，我是陸軍少校王志強，身分證字號 F128334452，駕照 ABC1234567，車牌 ABC-1234。"
result_text, spans = pf.predict_text(runtime, text, decoder)

for s in spans:
    print(f"  [{s['start']:3d}:{s['end']:3d}] {s['entity']:20s} → {text[s['start']:s['end']]!r}")

Output 格式

與 openai/privacy-filter 原生輸出完全相容：

[
  {"entity": "private_person", "start": 6, "end": 11},
  {"entity": "tw_national_id", "start": 19, "end": 29},
  {"entity": "tw_driver_license", "start": 33, "end": 43},
  {"entity": "tw_license_plate", "start": 47, "end": 55}
]

⚠️ 不要用 transformers.AutoModelForTokenClassification.from_pretrained() 載入，會缺少 Viterbi decoding，導致中文 span fragmentation（嚴重時 strict F1 從 86% 掉到 < 5%）。

Training Details

項目	值
Base checkpoint	openai/privacy-filter (original/* weights)
Training data	lianghsun/tw-PII-chat（61,300 筆，11 OOD frequency-weighted）
Train / Val split	55,170 / 3,065
Optimizer	AdamW (lr=2e-4, weight_decay=0.0, max_grad_norm=1.0)
Schedule	3 epochs, batch_size=32, ctx=512, bf16
Output head	33 → 77 classes（前 33 列從 base 拷貝，後 44 列重新初始化）
Hardware	1× NVIDIA B200
Training time	~4 minutes（238 秒 wall-clock）
Final validation	loss 0.0254, token accuracy 99.28%

Label space (tw_pii_v1)

20 個 span class（含 O background）= 8 個 in-schema + 11 個 Taiwan OOD：

O, account_number, private_address, private_date, private_email, private_person,
private_phone, private_url, secret,
tw_national_id, tw_nhi_card, tw_company_id, tw_passport, tw_line_id,
tw_license_plate, tw_driver_license, tw_household_no, tw_ptt_id,
tw_medical_license, tw_military_id

完整 BIOES 展開為 1 + 19 × 4 = 77 classes。Label space 定義見 tw_label_space.json。

Citation

@misc{privacy_filter_tw,
  title        = {privacy-filter-tw: A Taiwan-localized PII detector built on openai/privacy-filter},
  author       = {Huang, Liang Hsun},
  year         = {2026},
  howpublished = {\url{https://huggingface.co/lianghsun/privacy-filter-tw}},
  note         = {Fine-tuned on lianghsun/tw-PII-chat with 11 Taiwan-specific OOD labels added.}
}

Acknowledgements

• OpenAI 開源 openai/privacy-filter 與其 OPF inference framework，提供堅實的 backbone。
• Gemini 3.1 Pro / Flash Lite Preview 用於 tw-PII-chat 訓練資料合成。

Model Card Authors

Liang Hsun Huang

Model Card Contact

Liang Hsun Huang