EulerForge

Herramienta de fine-tuning de LLM que entrena modelos densos al estilo MoE

Conversión Dense → MoE + pipeline LoRA. Un framework de fine-tuning orientado a investigación que inyecta LoRA en modelos HuggingFace y permite transformar un modelo denso en una estructura Mixture-of-LoRAs o MoE Expert LoRA para entrenarla.

Experimentos MoE reproducibles incluso con presupuestos de GPU modestos. Con programación por fases que descongela progresivamente router → LoRA → base FFN, abordamos la especialización de expertos, el enrutamiento y la estabilidad MoE en una sola GPU de consumo.

Pipeline completo desde un solo preset YAML, sin tocar el código. SFT → DPO/ORPO → RM → PPO en una sola secuencia — los experimentos se gestionan mediante configuración YAML, no cambiando el código.

Tutoriales KO/EN

Estrategias de inyección LoRA

Tipos de entrenamiento

CLI en 5 idiomas

MoE es una dirección, no un presupuesto

¿Por qué los grandes modelos Mixture-of-Experts rinden tanto? Porque solo activan parámetros en las regiones de experto necesarias. EulerForge entrena el modelo que ya tienes en esa dirección.

Problemas en los que nos enfocamos

Tratar la conversión Dense → MoE como ciudadano de primera clase
Experimentos reproducibles sobre enrutamiento y especialización de expertos
Fine-tuning estable de modelos grandes vía programación por fases
Observación consistente de la estabilidad del router MoE y de la aux loss

Decisiones de diseño

Los experimentos viven en configuración YAML, no en el código del modelo
Preflight + validación de estabilidad MoE se ejecutan antes del entrenamiento
Pipeline multi-fase con paso automático de checkpoints (SFT → DPO/ORPO → RM → PPO), en vez de scripts separados
Entrenamiento cuantizado 4-bit / 8-bit para que los experimentos quepan en presupuestos de GPU modestos

Capacidades principales

Los cuatro pilares que hacen de EulerForge una buena opción para la investigación MoE

01 Conversión Dense → MoE

Mediante las inyecciones mixture_lora y moe_expert_lora — convierte cualquier Qwen / Llama / Gemma dense en un modelo entrenable estilo MoE. Sin reescribir código del modelo.

02 LoRA Handoff + Phase Scheduling

Descongelado por etapas (router → LoRA → base FFN) que hace que el fine-tuning de modelos grandes sea estable y reproducible.

03 Un preset, pipeline completo

SFT → DPO / ORPO → RM → PPO como una sola secuencia de comandos, con detección automática del modelo base y la configuración LoRA entre etapas.

04 Preflight + validación de estabilidad MoE

Detecta errores de configuración y riesgo de colapso del router antes de consumir un solo ciclo de GPU.

▶ Estrategias de inyección detalle (4 tipos)

Cuatro estrategias de inyección

Parte del mismo backbone dense y decide qué tipo de experimento MoE ejecutar en una sola línea YAML.

`dense_lora`

Adaptadores LoRA clásicos — el camino más rápido a la adaptación de dominio. Ideal como control base frente a variantes MoE.

`mixture_lora`

Router + múltiples expertos LoRA. Convierte un modelo dense en una estructura con enrutamiento multitarea a nivel de token.

`moe_expert_lora`

Reemplaza el FFN por un bloque MoE e inyecta LoRA en cada experto (estilo DeepSeek). Convierte un backbone dense en un objetivo de entrenamiento MoE completo.

`native_moe_expert_lora`

Inyecta LoRA en cada experto de un modelo ya MoE como Mixtral o Gemma 4 MoE para un fine-tuning eficiente.

▶ Tipos de entrenamiento detalle (SFT / DPO / ORPO / RM / PPO)

Cinco caminos de entrenamiento — en un solo pipeline

SFT → DPO / ORPO → RM → PPO. Los checkpoints de cada etapa fluyen automáticamente a la siguiente.

Tipo de entrenamiento	Descripción
SFT	Supervised Fine-Tuning — etapa base de alineación
DPO	Direct Preference Optimization — sin modelo de referencia, eficiente en memoria
ORPO	Odds Ratio Preference Optimization — alineación con un solo forward pass
RM	Reward Model (Bradley-Terry)
PPO	Proximal Policy Optimization — etapa final de RLHF

Pipeline de conversión Dense → MoE

EulerForge automatiza cada paso necesario para convertir un modelo dense de HuggingFace en un objetivo de entrenamiento MoE.

# Un preset YAML convierte un Qwen dense en un objetivo MoE Expert LoRA
eulerforge train --preset configs/presets/qwen3.5_0.8b_moe_expert_lora_sft.yml

# Internamente:
# 1. Carga HuggingFace AutoModel (bnb 4/8-bit opcional)
# 2. El adaptador de backbone localiza FFN / módulos de attention
# 3. Reemplaza FFN por un bloque MoE; inyecta LoRA por experto
# 4. Planificador de fases: router warmup -> LoRA -> base FFN
# 5. Preflight + validación de estabilidad MoE antes de entrenar

Preset YAML

→

Config + preflight

→

Carga del modelo base

→

Inyección MoE

→

Entreno por fases

→

Export HF

Phase Scheduling & LoRA Handoff

Gestiona quién es entrenable a lo largo del tiempo — el fine-tuning de modelos grandes se vuelve estable y reproducible.

Router warmup

Al inicio del entrenamiento, solo el router es entrenable para que la distribución token-a-experto se estabilice. Sin esta fase, el colapso del router o de expertos es común.

Fase solo-LoRA

Una vez estable el router, solo se entrenan los LoRA de los expertos. El FFN base permanece congelado.

LoRA Handoff (fade / ramp)

Atenuar gradualmente los pesos LoRA mientras el conocimiento se traspasa al FFN base; en inferencia se conserva la estructura MoE reduciendo la dependencia de LoRA.

Backbones soportados

El mismo código de inyección / entrenamiento funciona en todas las familias de backbone.

Backbone	Modelos
Qwen	Qwen2 / Qwen3 / Qwen3.5 (dense)
Llama	Llama 2 / Llama 3 / Llama 3.2, TinyLlama, Mistral
Gemma 3	Gemma 3 1B / 4B (dense)
Gemma 4	Gemma 4 dense (e2b / e4b) + native MoE (26b a4b)
Mixtral	Mixtral 8x7B / 8x22B (native MoE)
Entrenamiento cuantizado	nf4 / int4 / int8 vía bitsandbytes

Presets destacados

Los presets YAML listos para ejecutar viven en configs/presets/.

Preset	Estrategia	Entrenamiento
`qwen3.5_0.8b_dense_lora_sft.yml`	Dense LoRA	SFT
`qwen3.5_0.8b_mixture_lora_sft.yml`	Mixture-of-LoRAs	SFT
`qwen3.5_0.8b_moe_expert_lora_sft.yml`	MoE Expert LoRA	SFT
`qwen3.5_0.8b_moe_expert_lora_dpo.yml`	MoE Expert LoRA	DPO
`llama3_1b_moe_expert_lora_sft_handoff.yml`	MoE Expert LoRA + Handoff	SFT
`gemma3_4b_moe_expert_lora_orpo_handoff.yml`	MoE Expert LoRA + Handoff	ORPO
`gemma4_26b_a4b_native_expert_lora_sft.yml`	Native MoE Expert LoRA	SFT
`mixtral_native_expert_lora_sft.yml`	Native MoE Expert LoRA	SFT

Instalación e inicio rápido

v0.1.0 — Requisitos: Python ≥ 3.9, PyTorch ≥ 2.1, Transformers ≥ 5.5.

# Instalar desde fuente (v0.1.0)
git clone https://github.com/eulerwa/eulerforge && cd eulerforge && pip install -e .

# Opcional: HPO / TensorBoard
pip install -e .[hpo]
pip install -e .[tb]

# 1. Entrenar — Dense LoRA SFT sobre Qwen3.5-0.8B
eulerforge train \
  --preset configs/presets/qwen3.5_0.8b_dense_lora_sft.yml \
  --set data.path=data/sft_10k_raw.jsonl --set data.max_length=512

# 2. Evaluar (target / baseline / judge)
eulerforge bench --preset configs/bench/sft_with_judge.yml \
  --target-output-dir outputs/run_YYYYMMDD_HHMMSS

# 3. Exportar como directorio HF estándar
eulerforge export-hf \
  --checkpoint outputs/run_YYYYMMDD_HHMMSS --output ./exported

# 4. Cargar en Python
# from eulerforge import load_model
# result = load_model("outputs/run_YYYYMMDD_HHMMSS")

Tutoriales y referencia CLI

Guías paso a paso y la superficie completa de comandos

Nota: los tutoriales y la referencia CLI actualmente solo están disponibles en coreano e inglés. Los enlaces siguientes llevan a la versión en inglés.

Serie de tutoriales (EN) →

23 guías numeradas desde Getting Started hasta un pipeline MoE completo. Disponibles en inglés y coreano.

Referencia CLI (EN) →

train, convert, preprocess, bench, export-hf, grid — todos los flags y opciones.

GitHub →

Código fuente, issues, releases. Apache License 2.0.

CLI internacionalizada

Salida de logs en cinco idiomas — un equipo puede usar la misma herramienta en su propia lengua.

eulerforge --lang ko train --preset PRESET.yml
eulerforge --lang en train --preset PRESET.yml
eulerforge --lang zh train --preset PRESET.yml
eulerforge --lang ja train --preset PRESET.yml
eulerforge --lang es train --preset PRESET.yml