korean-pii-ner-v3

Korean PII NER v3 (klue/roberta-large fine-tuned)

한국어 PII (Personally Identifiable Information) 가드레일용 NER 모델. NAME / ADDRESS / ORG 3 엔티티 7-label BIO 분류.

Quick Start

from transformers import AutoTokenizer, AutoModelForTokenClassification, pipeline

tokenizer = AutoTokenizer.from_pretrained("vmaca123/korean-pii-ner-v3")
model = AutoModelForTokenClassification.from_pretrained("vmaca123/korean-pii-ner-v3")

ner = pipeline("ner", model=model, tokenizer=tokenizer, aggregation_strategy="simple")
print(ner("저는 홍길동이고 서울시 강남구 테헤란로 152에 거주합니다. 삼성전자 소속입니다."))
# [{'entity_group': 'NAME', 'start': 6, 'end': 9, 'word': '홍길동', ...},
#  {'entity_group': 'ADDRESS', 'start': 13, 'end': 29, 'word': '서울시 강남구 테헤란로 152', ...},
#  {'entity_group': 'ORG', 'start': 35, 'end': 39, 'word': '삼성전자', ...}]

Labels (BIO, 7 classes)

PHONE / EMAIL / RRN / CREDIT_CARD 등 정형 PII는 본 모델 scope 밖 (regex/dict 책임).

Training data

데이터 split: 8:1:1 (train 27,206 / val 3,401 / test 3,401). KLUE-NER validation 5,000은 학습 미포함 외부 평가용.

Training details

• Base: klue/roberta-large (335M params)
• Phase 1: encoder freeze, classifier head 1 epoch, LR 5e-4
• Phase 2: full unfreeze, 5 epochs, LR 2e-5, warmup ratio 0.1, weight decay 0.01
• Batch: 16, max_length 128, fp16
• Hardware: RTX 3090 24GB (Vast.ai)
• Wall clock: ~30 minutes

Evaluation results

Iteration comparison (6 training runs)

v2 실패 lesson: Naver NER 90k + WikiAnn 20k 통합이 KLUE val -10%p. 어절 라벨의 char-level 변환 노이즈 + multi-source distribution shift가 원인. v3는 v1 setup 그대로 + composite/hard-negative augment만 추가하는 conservative 접근.

Sample outputs

Limitations & known issues

• Conjunctive 패턴: {name}이고 {address} 같은 케이스 v3에서 학습 데이터로 보강했으나 일부 변형 (지명+호칭 인접 등) 에서 boundary 오류 가능
• ADDRESS_UNIT 미지원: "101동 1203호" 같은 unit은 dict 후처리에서 분기 (NER은 ADDRESS_FULL만 emit)
• SCHOOL/HOSPITAL 미세분: ORG 단일 라벨로 emit, dict로 SCHOOL/HOSPITAL reclassification
• 외부 도메인 transfer 약함: KLUE val 0.766 vs internal 0.878. 도메인 특화 fine-tuning 권장 (의료/금융/법률 등)
• PHONE/EMAIL/RRN 미지원: 정형 PII는 regex 책임

Intended use

• 한국어 텍스트에서 PII 후보 (PERSON_NAME / ADDRESS_FULL / ORGANIZATION) 탐지
• v0.2 가드레일 파이프라인의 NER detector 모듈 (Korean PII Guardrail v0.2)
• Production 환경: regex / dictionary / context scorer / boundary corrector와 함께 사용 권장 (단일 NER만으로는 99% target 미달)

Out of scope

• 정형 PII (전화번호, 이메일, 주민등록번호 등) — regex/validator 사용
• 멀티 턴 / RAG 환경에서의 컨텍스트 추적 — v0.2 single-turn 범위 밖
• 의료 차트, 법률 문서 등 도메인 특화 텍스트 (성능 저하 예상)

License

CC-BY-SA-4.0 (KLUE base 모델 라이선스 상속).

Citation

@misc{kimminwoo2026koreanpiinerv3,
  title={Korean PII NER v3: klue/roberta-large fine-tuned for PII guardrails},
  author={Kim, Minwoo},
  year={2026},
  url={https://huggingface.co/vmaca123/korean-pii-ner-v3}
}

Companion project

이 모델은 Korean PII Guardrail v0.2 프로젝트의 NER detector 모듈입니다.

• Wrapper code: PII/ner/ner_wrapper.py (v0.2 BaseNERDetector Protocol 준수)
• Design doc: korean_pii_guardrail_v0_2/docs/14_NER_DESIGN_v1.md
• Training results: PII/ner/TRAINING_RESULTS_v3.md