Home > EulerForge > Tutorials > 16. HuggingFace Export

16. HuggingFace Export

Overview

eulerforge export-hf exports EulerForge-trained checkpoints to a HuggingFace Transformers-compatible model directory.

Prerequisites

1. Export Format by Strategy

Strategy Export Format Resulting Model HF Loading Method
dense_lora merged Standard dense HF model 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. Basic Usage

2.1 dense_lora Export (merged)

eulerforge export-hf \
    --checkpoint outputs/run_20260311_163425 \
    --output ./exported_model

Loading:

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

Loading:

model = AutoModelForCausalLM.from_pretrained(
    "./exported_moe",
    trust_remote_code=True,
)

3. Options

3.1 Checkpoint Selection

# Best checkpoint
eulerforge export-hf --checkpoint outputs/run --output ./out --select-checkpoint best

# Specify checkpoint_dir directly
eulerforge export-hf --checkpoint outputs/run/final --output ./out

3.2 Specifying dtype

# Export as bfloat16
eulerforge export-hf --checkpoint outputs/run --output ./out --dtype bf16

3.3 Dry-run / Validate-only

# Print plan only (no actual export)
eulerforge export-hf --checkpoint outputs/run --output ./out --dry-run

# Validation only
eulerforge export-hf --checkpoint outputs/run --output ./out --validate-only

3.4 Serialization Options

# PyTorch .bin format (disable safetensors)
eulerforge export-hf --checkpoint outputs/run --output ./out --no-safe-serialization

# Skip tokenizer copy
eulerforge export-hf --checkpoint outputs/run --output ./out --no-copy-tokenizer

4. Export Output Structure

merged (dense_lora)

exported_model/
├── config.json              # Includes eulerforge_export metadata
├── model.safetensors        # Dense model with LoRA merged
├── tokenizer_config.json
└── tokenizer.json

custom_moe (mixture_lora / moe_expert_lora)

exported_moe/
├── config.json                          # auto_map + eulerforge_export metadata
├── configuration_eulerforge_moe.py      # HF PretrainedConfig (self-contained)
├── modeling_eulerforge_moe.py           # HF PreTrainedModel (self-contained)
├── pytorch_model.bin                    # State dict with expert structure preserved
├── tokenizer_config.json
└── tokenizer.json

5. Anti-Averaging Protection

During MoE export, if all expert weights are identical (indicating averaging has occurred), an error is raised:

Export: Expert weights are identical — averaging detected.
Fix: Verify that the expert weights in the checkpoint have diverged.
See: docs/tutorials/16_export_hf.md

6. Example Scripts

Example Description Command
export_dense_lora.py dense_lora -> merged export + inference python examples/export_dense_lora.py <path> <output>
export_moe_lora.py MoE -> custom_moe export + verification python examples/export_moe_lora.py <path> <output>

References

← Prev 15. Loading Models17. Scratch Pretraining Next →