EulerForge

Un toolkit de fine-tuning de LLM que entrena modelos densos en estilo MoE

Un framework de fine-tuning orientado a investigación que inyecta LoRA en modelos HuggingFace y permite entrenar un modelo denso como una estructura Mixture-of-LoRAs o MoE Expert LoRA. Sobre un flujo habitual de SFT denso, EulerForge añade conversión Dense → MoE y programación por fases, de modo que la especialización de expertos, el enrutamiento y la estabilidad MoE puedan estudiarse de forma reproducible con un presupuesto de GPU modesto, sin reescribir el código del modelo. Un mismo preset YAML lleva el recorrido SFT → DPO/ORPO → RM → PPO.

En qué se enfoca EulerForge

En lugar de apuntar a un framework SFT de propósito general, hemos puesto el peso en expresar un flujo de investigación MoE como una configuración estandarizada.

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

1. 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.

2. LoRA Handoff + Phase Scheduling

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

3. 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.

4. 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.

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.

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