zh-tw-pii-ner-spacy-trf
繁體中文（台灣）PII 命名實體辨識模型，基於 spaCy zh_core_web_trf（XLM-RoBERTa transformer）fine-tune。
主要強化兩類實體在繁中 PII 場景的辨識能力：
| 標籤 |
對應 PII 類型 |
範例 |
PERSON |
人名（NAME） |
王小明、歐陽娜娜、Mike Chen、Dr. 王 |
GPE |
地址 / 地理實體（ADDRESS） |
台北市信義區市府路 1 號、新北市板橋區文化路一段 200 號 |
其他 spaCy zh pipeline 元件（tagger / parser / attribute_ruler / transformer）凍結沿用 base model，未調整。
🚀 快速使用
安裝
pip install spacy huggingface_hub
uv pip install spacy huggingface_hub
從 Hugging Face 載入
from huggingface_hub import snapshot_download
import spacy
model_path = snapshot_download(repo_id="anx2026/zh-tw-pii-ner-spacy-trf")
nlp = spacy.load(model_path)
doc = nlp("我叫王小明，住台北市信義區市府路 1 號。")
for ent in doc.ents:
print(ent.text, ent.label_)
📊 評估結果
內部 dev set（528 句，spaCy 自動評估）
| Type |
Precision |
Recall |
F1 |
| Overall |
0.914 |
0.914 |
0.914 |
| PERSON |
0.943 |
0.928 |
0.936 |
| GPE |
0.853 |
0.883 |
0.868 |
外部繁中 PII fixture（495 句，lenient overlap matching）
| Model |
TP |
FP |
FN |
Precision |
Recall |
F1 |
base zh_core_web_trf |
191 |
57 |
51 |
0.770 |
0.789 |
0.780 |
| fine-tuned（本模型） |
242 |
51 |
0 |
0.826 |
1.000 |
0.905 |
Δ vs base：F1 +0.125、Recall +0.211、NAME F1 +0.143、ADDRESS F1 +0.081
Per-Type（外部 fixture）
| Type |
Model |
P |
R |
F1 |
| NAME |
base |
0.827 |
0.717 |
0.768 |
| NAME |
fine-tuned |
0.837 |
1.000 |
0.911 |
| ADDRESS |
base |
0.674 |
1.000 |
0.805 |
| ADDRESS |
fine-tuned |
0.795 |
1.000 |
0.886 |
🧪 訓練資料
總計 5280 筆，分割 train / dev / test = 4224 / 528 / 528。
標籤分佈（train set）
| 標籤 |
數量 |
| PERSON |
3297 |
| GPE |
1515 |
資料來源
| 來源 |
數量 |
說明 |
| Templates（自製） |
3033 |
繁中模板 × 變體（複姓、外籍、暱稱、台灣常用地址格式） |
| WikiANN zh（簡轉繁） |
1191 |
wikiann 中文切片，OpenCC 簡轉繁處理 |
Hard cases 涵蓋
- 複姓人名（歐陽、司馬、諸葛、上官 等 8+ 種）
- 中英混合人名（Mike Chen、Mr. Lin、Dr. 王）
- 暱稱／職稱開頭（小明、明哥、華姊）
- 台灣地址完整格式（縣市 + 行政區 + 路名 + 段巷弄號樓）
- 多 PII 高密度句子
- Negative samples（避免易誤判詞，163 筆）
⚙️ 訓練配置
| 項目 |
值 |
| Base model |
zh_core_web_trf（spaCy 3.8） |
| Transformer |
XLM-RoBERTa-base |
| Frozen components |
tagger, parser, attribute_ruler |
| Trainable components |
transformer, ner |
| Optimizer |
Adam（β1=0.9, β2=0.999, L2=0.01） |
| LR schedule |
warmup_linear, warmup=250, total=4000 |
| Initial LR |
5e-5 |
| Dropout |
0.1 |
| Max epochs |
8 |
| Batch size |
8（pad batcher size=2000） |
| Gradient accumulation |
3 |
| Patience |
1500 |
| Seed |
20260505 |
| GPU allocator |
pytorch |
⚠️ 限制與注意事項
- 僅針對 PERSON / GPE 兩類強化，其他實體類型（ORG、DATE 等）行為等同 base model。
- 訓練資料以台灣繁中為主，香港 / 澳門地址格式可能效果不佳。
- 模板資料佔比較高，極端口語、社群媒體用語覆蓋有限。
- WikiANN 簡轉繁可能保留部分簡體用詞痕跡。
- Inference 速度約為 base model 的 1.9 倍時間（11.2s vs 5.9s on 495 句樣本）。
📁 模型結構
.
├── config.cfg # spaCy pipeline 設定
├── meta.json # 模型 metadata + scores
├── tokenizer # ChineseTokenizer (segmenter=char)
├── transformer/ # XLM-RoBERTa weights
├── ner/ # Fine-tuned NER head
├── tagger/ # 凍結，沿用 base
├── parser/ # 凍結，沿用 base
├── attribute_ruler/ # 凍結，沿用 base
└── vocab/ # spaCy vocab
📜 授權
本模型基於 spaCy zh_core_web_trf（MIT）fine-tune，訓練資料含 WikiANN（CC-BY-SA 4.0）切片。下游使用請依各來源條款。
🏷️ 引用
@misc{zh_tw_pii_ner_spacy_trf_2026,
title = {zh-tw-pii-ner-spacy-trf: spaCy zh_core_web_trf fine-tuned for Traditional Chinese PII NER},
author = {AI NEXT MINE},
year = {2026},
url = {https://huggingface.co/anx2026/zh-tw-pii-ner-spacy-trf}
}
