HERIUN/eruku_korean

Eruku Korean (한글 손글씨 생성)

Eruku (blowing-up-groundhogs/eruku, arXiv:2510.23240) 를 한글(Korean) 로 파인튜닝한 모델입니다. 스타일 참조 손글씨 이미지 + 생성할 텍스트를 받아, 해당 스타일로 텍스트 이미지를 자기회귀 생성합니다.

• Base model: blowing-up-groundhogs/eruku (영어 pretrained)
• Training code / recipe: https://github.com/HERIUN/Eruku_korean_finetuning
• Checkpoint: en2ko fine-tune, step 11,000 (pytorch_model.bin, weights only)

영어 pretrained 는 한글을 전혀 생성하지 못합니다(완전 붕괴). 이 모델은 영어 능력을 보존한 채 한글을 새로 학습했습니다.

사용법

1) AutoModel (권장, 원본과 동일한 편의 API)

from transformers import AutoModel
from PIL import Image
import torch

device = "cuda" if torch.cuda.is_available() else "cpu"
model = AutoModel.from_pretrained("HERIUN/eruku_korean", trust_remote_code=True).to(device).eval()

style_image = Image.open("style_sample.png")   # 손글씨 스타일 참조 이미지
result = model.generate_handwriting(
    style_image=style_image,
    gen_text="한국어 손글씨 생성",
    style_text="",       # 선택: style 이미지의 전사
    cfg_scale=1.5,       # 한글은 1.5 권장 (원본 기본 1.25)
)
result.save("generated.png")

로드 시 t5_to_ocr.weight 가 UNEXPECTED 로 뜨는 건 정상입니다(학습에만 쓰인 보조 OCR 헤드, 추론 미사용 → 무시). 그 외 파라미터는 모두 정상 로드됩니다.

2) 학습 repo 코드로 로드 (동일 결과)

from huggingface_hub import hf_hub_download
from infer_show import load_model   # https://github.com/HERIUN/Eruku_korean_finetuning
ckpt = hf_hub_download("HERIUN/eruku_korean", "pytorch_model.bin")
model, _ = load_model(ckpt, "cuda")

upstream 대비 차이점

학습 파이프라인에 두 가지 수정이 반영되어 있습니다(가중치에 내재). 추론 전처리는 원본 modeling_eruku.py 와 동일하게 동작하도록 맞춰져 있어 위 AutoModel 경로가 올바른 결과를 냅니다.

1. style-length 단위 버그 수정: 학습 시 get_model_inputs 의 style/gen 길이 clamp 에서 픽셀↔latent 단위가 섞여 style 이 ~1/8 로 잘리던 문제를 픽셀 환산(*8)으로 수정.
2. 이중 정규화 제거: 학습 데이터가 이미 [-1,1] 인데 Normalize(0.5,0.5) 를 한 번 더 적용해 VAE 입력이 [-3,1] 로 밀리던 문제를 제거(학습 시). 추론은 [0,1] 입력을 한 번 정규화하므로 일관.

학습 레시피

항목	값
시작	영어 pretrained (blowing-up-groundhogs/eruku), Phase 1 생략
virtual batch	256 (batch 2 × grad-accum 128)
lr	5e-5 (pretrained 천천히 덮어 영어 보존)
데이터	온라인 합성(한글 손글씨/디스플레이 폰트 + 라틴 폰트 15%), style 18 / gen 132 어절
max-img-len	8192 (긴 문장 truncation 방지)
VAE	동결 (frozen)

평가 (held-out 미학습 폰트, n=40, 긴 문장 포함)

↓ 낮을수록 좋음(FID·CER) / ↑ 높을수록(SSIM). 미학습 폰트 = 학습에 쓰지 않은 held-out 폰트.

	한글 FID↓	한글 CER↓	한글 SSIM↑	영어 FID↓	영어 CER↓
pretrained (영어원조)	176.8	3.539 (붕괴)	—	54.6	0.274
이 모델 (step 11k)	110.0	0.150	0.332	51.4	0.250
step 5k (참고)	87.7	0.214	0.353	50.9	0.256

• 한글: pretrained 는 완전 붕괴(CER 3.5) → 파인튜닝 후 유창(CER 0.15). 내용 정확도 최고.
• 영어: 파인튜닝 후에도 보존(FID·CER 거의 동일).
• step 5k 는 스타일/이미지 충실도(FID) 가 더 좋고, step 11k(이 모델) 는 텍스트 내용 정확도(CER) 가 더 좋은 trade-off 입니다. 가독성/정확도 우선이면 이 모델을 권장합니다.

알려진 한계: VAE 한글 수용성

한글 fidelity 는 step ~11k 부근에서 plateau 합니다. 원인은 학습 부족이 아니라 동결 VAE 의 한글 재구성 한계입니다. 모델은 VAE latent 만 조건·타깃으로 쓰므로, VAE 가 한글을 latent 에 담지 못하는 디테일은 학습으로 넘을 수 없습니다. 같은 폰트 VAE roundtrip 재구성 오차: 한글 MSE 0.0165 / SSIM 0.906 vs 영어 MSE 0.0014 / SSIM 0.984 (한글이 ~12배, 밀집 음절일수록 심함). 자세한 근거는 training repo 참고.

라이선스

Apache-2.0 (base model 승계). 폰트/데이터는 각 라이선스를 따릅니다.

인용

Base model:

@article{eruku2025,
  title={Eruku: Autoregressive Styled Text Image Generation},
  journal={arXiv preprint arXiv:2510.23240},
  year={2025}
}