yachagye/korean-historical-placename-ner

한국 역사 지명 개체명 인식 모델 (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 사료는 재배포하지 않으며, 원본은 국사편찬위원회·공공데이터포털의 이용 조건을 따릅니다.