한국 역사 지명 개체명 인식 모델 (Korean Historical Place-Name NER)
한국 고전 한문 사료에서 지명 개체를 추출하는 개체명 인식(NER) 모델입니다. 국사편찬위원회 한국사데이터베이스의 색인 XML 태그를 학습 정답(gold label)으로 사용하며, 기반 모델로 고전 한문에 특화 사전학습된 SikuRoBERTa를 사용합니다.
이 저장소는 학습 출처 구성이 다른 두 모델의 가중치를 함께 배포합니다. 두 모델은 상보적 판정 양상을 지니며, 출력을 개체 수준에서 결합하는 앙상블(합집합 + 겹침 최장) 구조로 재현과 정밀을 함께 확보합니다.
- 소스 코드·파이프라인: GitHub
- 관련 논문: 양정현, 2026, 「색인 XML 사료를 활용한 한국 역사 지명 개체명 인식 모델의 구축」, 『한국사학보』104
모델 구성
| 파일 | 모델 | 학습 출처 | 성격 |
|---|---|---|---|
sjw_sillok.ckpt | 승정원일기·실록 모델 | 조선왕조실록·승정원일기·고순종실록 | 고재현·저정밀 |
jonghap.ckpt | 종합 모델 | 위 + 한국사료총서·고려사·고려사절요·삼국사기·삼국유사 | 저재현·고정밀 |
- 아키텍처: SikuRoBERTa(108M) + Dropout + Linear(hidden→3). 문자 단위 BIO(0=O, 1=B-LOC, 2=I-LOC).
- 손실: CrossEntropyLoss(ignore_index=-100). 학습: bf16-mixed, 3 epochs, lr 2e-5(AdamW), 유효 배치 160.
성능 (자체 검증셋, span exact match)
| 모델 | F1 | Precision | Recall |
|---|---|---|---|
| 승정원일기·실록 모델 | 0.9049 | 0.8982 | 0.9118 |
| 종합 모델 | 0.8915 | 0.8803 | 0.9030 |
평가 단위는 토큰이 아니라 개체 완전 일치입니다. O 라벨이 약 98.3%를 차지하여 토큰 micro F1이 성능을 부풀리기 때문입니다. 두 모델의 검증셋은 구성이 달라(승정원일기·실록 val은 순수 연대기, 종합 val은 7종 전체) F1을 직접 비교하지 마십시오.
학습 자료: 1,334개 파일, 총 한자 293,652,373자, 지명 개체 2,075,132개, 고유 지명 94,846종.
사용법
이 모델은 표준 AutoModelForTokenClassification이 아니라 SikuRoBERTa 인코더 위에 3-클래스 선형 분류기를 얹은 구조로, PyTorch Lightning 체크포인트(.ckpt)로 배포됩니다. 로딩·추론·앙상블 병합은 GitHub 저장소의 NER_model_loader.py와 4_NER_추론_txt.py를 사용하는 것이 표준입니다.
huggingface-cli download yachagye/korean-historical-placename-ner sjw_sillok.ckpt jonghap.ckpt --local-dir ./ckpt
python 4_NER_추론_txt.py # 모드·입력 방식 선택 후 두 ckpt 지정 → 통합본 생성
구조 참고(추론 시 문자 단위 입력, word_ids 정렬, 엄격 BIO 복원, 개체 완전 일치 채점):
import torch
from transformers import AutoTokenizer, AutoModel
tok = AutoTokenizer.from_pretrained("SIKU-BERT/sikuroberta")
enc = AutoModel.from_pretrained("SIKU-BERT/sikuroberta")
classifier = torch.nn.Linear(enc.config.hidden_size, 3) # 0=O, 1=B-LOC, 2=I-LOC
# ckpt의 state_dict에서 인코더·분류기 가중치를 복원 (NER_model_loader.py 참조)
출력은 지명 개체를 대괄호 [ ]로 표시한 한문 텍스트입니다.
[竹山縣]
東至[陰竹縣]界二十二里，南至[忠淸道][鎭川縣]界二十六里，西至[安城郡]界二十三里…
앙상블·검수
- 합집합: 두 모델 span을 모두 후보로 → 누락 복구(재현).
- 겹침 시 최장: 겹치는 span은 가장 넓은 것 하나만 → 경계 정밀.
- 단계적 검수: 자동 병합 → 수동 검수 → 지명DB 최장일치 보조 검수.
한계
- 분할 잔여 단편(
路·內·西등 비지명 1글자)과 선행 허사 흡수(隷류)가 통합본에 남을 수 있습니다. 이는 지명 경계가 본래 확정적이지 않은 자료 특성의 표면화로, 다운스트림 정제에서 거릅니다. - 단음절 지명(
京등)은 문맥 의존 판정이 필요합니다.
학습 데이터·출처
국사편찬위원회 한국사데이터베이스 색인 XML 사료. 원본은 공공데이터포털에서 제공됩니다. 본 저장소는 원본 사료를 재배포하지 않고 파생 가중치만 공개합니다.
인용
@article{yang_placename_ner,
author = {양정현},
title = {색인 XML 사료를 활용한 한국 역사 지명 개체명 인식 모델의 구축},
journal = {한국사학보},
number = {104},
year = {2026},
note = {면수·DOI 확정 시 갱신 예정}
}
라이선스
Apache-2.0. 기반 모델 SikuRoBERTa가 Apache-2.0으로 배포되므로(2026년 7월 확인), 파생 가중치도 동일 라이선스로 공개합니다. Apache-2.0에 따라 기반 모델의 라이선스·저작권 고지를 유지하고 개조 내역을 명시합니다(저장소 NOTICE 참조). 학습에 사용한 색인 XML 사료는 재배포하지 않으며, 원본은 국사편찬위원회·공공데이터포털의 이용 조건을 따릅니다.