HERIUN/inkspire_korean

InkSpire Korean — 한글 손글씨 스타일 생성 LoRA

InkSpire (Wang et al., ICLR 2026) 를 한글로 재현한 LoRA. FLUX.3-Image-Klein-Base + LoRA r32 (71.2M), 13k step. 스타일 손글씨 한 줄(+ 그 전사)을 보고 같은 필체로 새 문장을 쓴다.

• 학습 코드·실험 기록: https://github.com/HERIUN/Inkspire_korean_finetuning
• 데모(Eruku 와 모델 선택): https://huggingface.co/spaces/HERIUN/eruku_korean_demo
• 같은 데이터로 학습한 자기회귀 모델 비교 대상: HERIUN/eruku_korean

입력 규약

캔버스 X(위 = ref 손글씨, 아래 = 빈 칸) · 콘텐츠 이미지 Xc(NanumGothic 으로 ref 전사와 목표 문구를 글자 상자에 그린 것) · 마스크. Xc 의 ref 줄(전사를 표준폰트로 그린 글자 대응표)로 ref 필체를 베끼므로 필체를 따라 하려면 ref 전사(style text)가 필요하다. 전사 없이도 생성은 되고 글자는 오히려 정확하지만(실손글씨 CER 0.168 → 0.033, cfg 2.0) 필체가 거의 사라진다(HWD 1.46 → 2.05). 목표 줄 폭은 ref 의 "손글씨 폭 / 표준폰트 폭" 비율로 맞춘다(ref_width, 기본).

성능 (ref 전사를 줄 때, PP-OCRv6 판독 CER)

InkSpire 는 내용 CFG(cfg=2.0, uncond="gen", 권장) 와 끔(cfg=1.0, 기본) 두 줄로 적는다. Eruku 는 권장 cfg 1.5.

평가	InkSpire cfg 2.0	InkSpire cfg 1.0	Eruku Korean
한글 폰트 held-out 16종 n=300 — CER↓ / HWD↓	0.0045 / 1.02	0.023 / 0.93	0.010 / 1.12
실손글씨 문장 교차 생성 n=20 — CER↓ / HWD↓	0.071 / 1.60	0.246 / 1.41	0.014 / 1.51
실손글씨 서식 칸 n=286 — CER↓ / HWD↓	0.180 / 1.37	0.417 / 1.20	0.711 (백지 7) / 1.83
IAM lines 2,925 — HWD↓ / FID↓	—	1.68 / 18.58	1.62 / 20.00

• 폰트 조건에선 cfg 2.0 이 정확도·필체 모두 Eruku 를 앞선다. 실제 사람 손글씨 문장은 정확도가 Eruku 에 뒤진다 — 폰트로만 학습해 분포 밖 글자 모양을 그대로 베낀다.
• CFG 는 정확도 ↔ 필체(HWD) 절충이다. 지저분한 ref(서식 칸·표 선 잔재)에선 InkSpire 가 백지·폭주가 거의 없다.
• 한계 전체와 사용 팁: GitHub README 「먼저 읽을 것」. 측정 근거: docs/EXPERIMENTS.md §9·§10.

사용법

추론 코드는 GitHub repo 에 있다(베이스 가중치는 black-forest-labs/flux-3-image-klein-base 약관 수락 후 자동 다운로드).

import numpy as np, torch
from huggingface_hub import snapshot_download
from PIL import Image
from infer.inkspire import InkSpireGen          # GitHub repo 루트에서

lora = snapshot_download("HERIUN/inkspire_korean")        # pytorch_lora_weights.safetensors + klein_empty_prompt.pt
# klein_empty_prompt.pt 는 model_zoo/ 에 둔다(빈 프롬프트 텍스트 임베딩 캐시 — 텍스트 인코더를 안 올린다)
# 표준폰트: 나눔고딕(SIL OFL 1.1, https://hangeul.naver.com/font) NanumGothic-Regular.ttf 를
#   assets/fonts/label/ 에 둔다 — std_font 기본 경로이고, 학습 때 Xc 를 그린 폰트와 같은 파일이어야 한다
g = InkSpireGen(lora, device="cuda", cfg=2.0, uncond="gen",   # 권장. cfg=1.0 = CFG 끔(필체 최대, 오타↑)
                std_font="assets/fonts/label/NanumGothic-Regular.ttf")
ref = np.asarray(Image.open("style_line.png").convert("L"))   # 손글씨 한 줄(스캔 테두리·여백은 미리 잘라 둔다)
out = g.gen_lines(ref, "스타일 이미지의 전사", ["생성할 문장"], seed=0)[0]   # u8 줄 이미지

• 전사는 글자 그대로 정확히 — Xc 대응표의 원천이다. 비우면("") 글자는 정확하지만 필체가 사라진다.
• 틀린 글자가 보이면 seed 만 바꿔 다시 — 오류가 시드마다 다른 글자에서 난다.
• 흐린 연필 ref 는 출력도 흐리다(잉크 농도를 베낀다). 진하게 원하면 ref 대비를 올려 넣는다.

라이선스

FLUX Kommunity License (베이스 모델과 동일, 비상업 용도) — NOTICE 참고. 학습 데이터는 공개 한글 폰트 렌더이며, 비교 평가에 쓴 실손글씨 데이터는 포함하지 않았다.