Modelpublic

anx2026/zh-tw-pii-ner-spacy-trf

sourceHugging Faceupdated 5mo agoView on Hugging Face

1likes

Model Card

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，未調整。

🚀 快速使用

安裝

bash

pip install spacy huggingface_hub
# 或
uv pip install spacy huggingface_hub

從 Hugging Face 載入

python

from huggingface_hub import snapshot_download
import spacy

# Private repo 需先 login：huggingface-cli login
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_)
# 王小明 PERSON
# 台北市信義區市府路 1 號 GPE

📊 評估結果

內部 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}
}