16. HuggingFace Export
개요
eulerforge export-hf는 EulerForge로 훈련한 체크포인트를 HuggingFace Transformers 호환 모델 디렉토리로 내보냅니다.
- 적합한 용도: 모델 배포, HF Hub 업로드, 다른 프레임워크 연동
- 핵심 원칙: Expert 구조 보존 — MoE/MixtureLoRA 구조를 침묵하고 파괴하지 않음
- 참조 예제:
examples/export_dense_lora.py,examples/export_moe_lora.py
사전 요구 사항
- EulerForge 설치 완료
- 훈련 완료된 체크포인트 (run_dir 또는 checkpoint_dir)
1. 전략별 Export 포맷
| 전략 | Export 포맷 | 결과 모델 | HF 로드 방법 |
|---|---|---|---|
dense_lora |
merged |
표준 dense HF 모델 | from_pretrained(path) |
mixture_lora |
custom_moe |
base + router + N LoRA experts | from_pretrained(path, trust_remote_code=True) |
moe_expert_lora |
custom_moe |
N expert FFN + router | from_pretrained(path, trust_remote_code=True) |
2. 기본 사용법
2.1 dense_lora Export (merged)
eulerforge export-hf \
--checkpoint outputs/run_20260311_163425 \
--output ./exported_model
로드:
from transformers import AutoModelForCausalLM, AutoTokenizer
model = AutoModelForCausalLM.from_pretrained("./exported_model")
tokenizer = AutoTokenizer.from_pretrained("./exported_model")
2.2 MoE Export (custom_moe)
eulerforge export-hf \
--checkpoint outputs/run_moe \
--output ./exported_moe
로드:
model = AutoModelForCausalLM.from_pretrained(
"./exported_moe",
trust_remote_code=True,
)
3. 옵션
3.1 체크포인트 선택
# best 체크포인트
eulerforge export-hf --checkpoint outputs/run --output ./out --select-checkpoint best
# checkpoint_dir 직접 지정
eulerforge export-hf --checkpoint outputs/run/final --output ./out
3.2 dtype 지정
# bfloat16으로 export
eulerforge export-hf --checkpoint outputs/run --output ./out --dtype bf16
3.3 Dry-run / Validate-only
# 계획만 출력 (실제 export 없음)
eulerforge export-hf --checkpoint outputs/run --output ./out --dry-run
# 검증만 수행
eulerforge export-hf --checkpoint outputs/run --output ./out --validate-only
3.4 Serialization 옵션
# PyTorch .bin 형식 (safetensors 비활성)
eulerforge export-hf --checkpoint outputs/run --output ./out --no-safe-serialization
# tokenizer 미복사
eulerforge export-hf --checkpoint outputs/run --output ./out --no-copy-tokenizer
4. Export 결과 구조
merged (dense_lora)
exported_model/
├── config.json # eulerforge_export 메타데이터 포함
├── model.safetensors # LoRA 병합된 dense 모델
├── tokenizer_config.json
└── tokenizer.json
custom_moe (mixture_lora / moe_expert_lora)
exported_moe/
├── config.json # auto_map + eulerforge_export 메타
├── configuration_eulerforge_moe.py # HF PretrainedConfig (self-contained)
├── modeling_eulerforge_moe.py # HF PreTrainedModel (self-contained)
├── pytorch_model.bin # Expert 구조 보존된 state dict
├── tokenizer_config.json
└── tokenizer.json
5. Anti-Averaging 보호
MoE export 시 expert weights가 모두 동일하면 (averaging이 발생한 경우) 에러를 발생시킵니다:
Export: Expert weights are identical — averaging detected.
Fix: 체크포인트의 expert weights가 분화되었는지 확인하세요.
See: docs/tutorials/16_export_hf.md
6. 예제 스크립트
| 예제 | 설명 | 명령어 |
|---|---|---|
export_dense_lora.py |
dense_lora → merged export + 추론 | python examples/export_dense_lora.py <path> <output> |
export_moe_lora.py |
MoE → custom_moe export + 검증 | python examples/export_moe_lora.py <path> <output> |
참조
- Spec:
docs/fixtures/specs/export_hf_spec.md - CLI:
do../cli.md§export-hf - 테스트:
tests/test_export_hf.py(29 tests)