koredact-bert-base

한국어 메시지·문서에서 개인정보 13 유형의 문자 스팬을 찾는 토큰 분류(NER) 모델. BERT-base(파라미터 110M), BIO 태깅 27 라벨. PyTorch(safetensors). ONNX 내보내기는 별도 리포 koredact-bert-base-onnx.

만든 이유

• 국내 공개 PII 마스킹 도구·모델이 실데이터에서 제대로 동작하지 않아 직접 학습. 기존 공개 모델은 사업자등록번호· 운전면허번호·여권번호·문맥 코드 유형이 없거나, 유형 구분 없이 한 라벨로 묶거나, 상용 사용이 막힌 라이선스였음.
• 정규식 후처리 없이 모델 단독으로 운영 가능한 정밀도가 목표. 구분자 제거·자릿수 손상·조사 결합 같은 표기 변형을 학습 데이터에 포함해 하이픈 위치가 아니라 문맥과 자릿수로 유형을 판별하게 함.
• 디코더(조사 절단 · 주민/외국인등록번호 7번째 자리 재판별 · 경계 조각 제거)까지 포함한 추론 라이브러리 koredact 의 기본 모델.

유형(13)

NAME 성명 · PHONE 전화번호 · EMAIL 이메일 · RRN 주민등록번호 · FRN 외국인등록번호 · BRN 사업자등록번호 · CARD 카드번호 · ACCOUNT 계좌번호 · ADDRESS 주소 · DRIVER_LICENSE 운전면허번호 · PASSPORT 여권번호 · URL URL · CODE 인증·주문 등 문맥 코드

계보·학습

• 베이스 계보: klue/bert-base (rev 77c8b3d, CC-BY-SA-4.0). 토큰 분류 헤드 재초기화 후 korean-pii-ner 로 학습.
• 입력 창: 400자 세그먼트, 겹침 100자. 같은 유형의 겹친 스팬은 병합. 학습 인코딩 512 토큰.

평가(held-out 테스트 분할 1,589 문서 · 1회 개봉)

NER 단독 측정(정규식 후처리 없음). raw = 모델 원출력, 디코더 = koredact 디코더 규칙 적용(v3_particle_strip_rrn_frn_7th_fragment_drop). Fβ2 = 재현율 가중 F(β=2). 학습 체크포인트 선택·후보 채택에 쓴 기준이고 F1 은 비교용. 합성 중심 평가셋이라 실데이터 재현율의 상한·하한 어느 쪽도 보증하지 않음.

유형	의미	R(raw)	P(raw)	F1(raw)	Fβ2(raw)	R(디코더)	P(디코더)	F1(디코더)	Fβ2(디코더)
NAME	성명	0.963	0.959	0.961	0.962	0.963	0.962	0.962	0.963
PHONE	전화번호	0.998	0.981	0.989	0.994	0.998	0.982	0.990	0.994
EMAIL	이메일	1.000	0.995	0.998	0.999	1.000	1.000	1.000	1.000
RRN	주민등록번호	0.991	0.947	0.968	0.982	0.991	0.964	0.977	0.985
FRN	외국인등록번호	0.981	0.969	0.975	0.978	0.992	0.970	0.981	0.988
BRN	사업자등록번호	1.000	0.991	0.995	0.998	1.000	0.991	0.995	0.998
CARD	카드번호	1.000	0.981	0.990	0.996	1.000	0.981	0.990	0.996
ACCOUNT	계좌번호	0.974	0.978	0.976	0.975	0.974	0.978	0.976	0.975
ADDRESS	주소	0.990	0.977	0.984	0.988	0.990	0.977	0.984	0.988
DRIVER_LICENSE	운전면허번호	0.962	1.000	0.981	0.969	0.962	1.000	0.981	0.969
PASSPORT	여권번호	1.000	1.000	1.000	1.000	1.000	1.000	1.000	1.000
URL	URL	0.989	0.989	0.989	0.989	0.989	0.989	0.989	0.989
CODE	인증·주문 등 문맥 코드	0.988	0.988	0.988	0.988	0.988	0.988	0.988	0.988
macro F1				0.984				0.986
macro Fβ2	채택 기준				0.986				0.987

ONNX

• 별도 리포 koredact-bert-base-onnx: opset 20, fp32 단일 파일 440 MB. 이 리포의 가중치에서 내보낸 것이며 dev 1,590 문서 · 1,870 세그먼트 · 196,653 토큰에서 PyTorch 대비 토큰 argmax 불일치 0 · max|Δlogit| 8.5e-05.

사용법

• 추론 라이브러리 koredact(Rust 런타임 + Python 바인딩, PyPI) 는 ONNX 리포 koredact-bert-base-onnx 를 기본으로 로드. 설치 uv add koredact.

from koredact import Masker
m = Masker.from_pretrained()                                  # infobank-corp/koredact-bert-base-onnx
m.mask("문의 010-1234-5678 홍길동")                           # '문의 [PHONE] [NAME]'
m.mask(text, types=["PHONE"])                                 # 선택한 유형만 마스킹
Masker.from_pretrained(mask_tokens={"PHONE": "***"})        # 유형별 치환 문자열(기본 [TYPE])

• 이 리포의 PyTorch 가중치를 직접 쓸 때: uv add transformers torch 후 token-classification 파이프라인(aggregation_strategy="simple"). 디코더 규칙(조사 절단 등)은 koredact 에만 있음.

한계

• 평가셋은 합성 데이터 중심. 실데이터 재현율은 별도 감사 없이는 알 수 없음.
• 한글 경로·국제화 도메인 URL, 400자 창 경계에 걸친 긴 스팬은 약점.
• 라이선스 CC-BY-SA-4.0(베이스 계보 상속). 출력은 마스킹 전처리 용도이며 법적 판단 근거로 쓰지 않음.