🏛️ Hanja Swin Transformer V2 (ANSEONGMIN/hanja-swinv2)

ANSEONGMIN/hanja-swinv2는 오랜 세월 풍화와 마모로 훼손된 한국 금석문/고문서 탁본 이미지를 복원하고 자동 판독하기 위해 학습된 Swin Transformer V2 기반 13,974종 한자 비전 분류 모델입니다. 고려대학교 지능정보 SW아카데미 최종 프로젝트 경진대회에서 **대상(정보통신기획평가원장상)**을 수상한 EpiText 프로젝트의 핵심 비전 AI 엔진입니다.

---

🌐 EpiText 프로젝트 생태계 (Ecosystem & Models)

EpiText 시스템은 **비전 모델(Swin V2)**과 **고전 한문 문맥 언어 모델(SikuRoBERTa)**의 멀티모달 앙상블로 구동됩니다.

모델 / 저장소	링크	설명 및 담당 역할
👁️ Vision AI Model	ANSEONGMIN/hanja-swinv2	(현재 모델) 13,974종 고문서 한자 비전 인식 (Swin V2 Small)
📖 NLP Context Model	jhangyejin/epitext-sikuroberta	사고전서(四庫全書) 기반 고전문맥 추론 및 구두점/오인식 보정 (SikuRoBERTa MLM)
🔬 Core Research Repo	rntqkdl/Epitext_Project	데이터 정제, 롱테일 손실 함수 설계, 모델 학습 및 평가 아카이브
⚙️ Production Backend	jincerity/Epitext_Back	FastAPI 비동기 인퍼런스 서버 및 Docker 컨테이너 서빙
💻 Production Frontend	jincerity/Epitext_Front	탁본 이미지 업로드 및 Grad-CAM 히트맵 시각화 UI

---

📊 모델 성능 지표 (Model Performance)

평가지표	수치 (Metrics)	비고
Top-1 Classification Accuracy	96.63%	13,974종 극단적 롱테일 불균형 환경
Top-5 Classification Accuracy	99.38%	상위 5개 후보 내 정답 포함률
Rare Class Detection Rate	92.40%	샘플 수 1~2개 희귀 한자 탐지율
Baseline 대비 향상도	+38.23%p	기존 ResNet50(58.40%) 대비 성능 비약적 상승

---

🛠️ 모델 아키텍처 및 학습 스펙 (Architecture & Training)

• 기반 아키텍처: swinv2_small_window16_256 (timm 기반, Window Size 16)
• 입력 해상도: $256 \times 256 \times 3$ (RGB)
• 총 클래스 수: 13,974 Classes (char_mapping.json)
• 데이터셋 규모:
  • 원천 수집 데이터: 규장각, 국사편찬위원회(고대사료, 고려사료), 금석문 조사보고서(2018~2023), 지식이음 등 총 13,966개 탁본 이미지 / 8,759개 판독문 / 6,345개 번역문
  • 품질 정제: 7가지 품질 지표(조명, 명암비, 블러, 노이즈, 마스크) 기반 IQR 필터링 및 EasyOCR(ch_tra) 필터링을 통해 고품질 데이터셋 확보.
• 학습 파라미터:
  • Effective Batch Size: 576 (Batch 192 $\times$ Gradient Accumulation 3), Mixed Precision(AMP)
  • 2-Tier 차등 학습률: Backbone (3e-5) / Classification Head (3e-4)
  • 스케줄러: Cosine Annealing with Warmup (5 Epochs)
  • 불균형 손실 함수: 빈도수 제곱근 역수 가중치 ($w_c = (1/N_c)^{0.5}$) Cross-Entropy Loss

---

🚀 빠른 시작 (Quick Start / How to Use)

1. 패키지 설치

pip install torch torchvision timm pillow

2. 파이썬 추론 예제 코드 (Inference Pipeline)

import torch
import torch.nn as nn
import timm
from torchvision import transforms
from PIL import Image
import json

# 1. 모델 아키텍처 정의 (13,974 클래스)
model = timm.create_model("swinv2_small_window16_256", pretrained=False, num_classes=13974)

# 2. Hugging Face 가중치 로드 (로컬 체크포인트 또는 HF Hub 다운로드)
checkpoint_path = "swin_checkpoint.pth"  # Hugging Face Repo 파일 경로
checkpoint = torch.load(checkpoint_path, map_location="cpu")
model.load_state_dict(checkpoint["model_state_dict"] if "model_state_dict" in checkpoint else checkpoint)
model.eval()

# 3. 이미지 전처리 파이프라인 (256x256)
transform = transforms.Compose([
    transforms.Resize((256, 256)),
    transforms.ToTensor(),
    transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225])
])

# 4. 탁본 이미지 예측 수행
image_path = "sample_takbon.jpg"
image = Image.open(image_path).convert("RGB")
input_tensor = transform(image).unsqueeze(0)

with torch.no_grad():
    outputs = model(input_tensor)
    probabilities = torch.softmax(outputs, dim=1)
    top5_prob, top5_indices = torch.topk(probabilities, 5)

print("=== Top-5 Hanja Prediction ===")
for i in range(5):
    idx = top5_indices[0][i].item()
    prob = top5_prob[0][i].item()
    print(f"Top-{i+1}: Class Index {idx} (Probability: {prob*100:.2f}%)")

---

🔬 NLP 앙상블 연동 (SikuRoBERTa)

비전 모델이 예측한 Top-5 한자 후보군은 jhangyejin/epitext-sikuroberta 모델과 결합되어, 앞뒤 문맥(MLM)에 가장 자연스러운 한자로 최종 보정(Post-Correction)됩니다.

---

📜 Citation & License

• License: MIT License
• Academic Inquiries: 고려대학교 지능정보 SW아카데미 7기 EpiText Team (안성민: tjdals2299@gmail.com)