moe-training

Train Mixture of Experts models with DeepSpeed using sparse routing and expert parallelism.

2|Updated Aug 15, 2026
One-click install
npx skills add https://github.com/Jensen-Yao/agents-skills --skill moe-training-jensen-yao
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: moe-training
Source: https://github.com/Jensen-Yao/agents-skills/tree/main/skills/moe-training
Command: npx skills add https://github.com/Jensen-Yao/agents-skills --skill moe-training-jensen-yao

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires deepspeed, transformers, torch, accelerate, and includes references (resource) components.

What problem does it solve? Training large language models with dense architectures demands compute budgets that scale linearly with parameter count, making billion-parameter models prohibitively expensive. This Skill provides the architectures, configurations, and tuning practices needed to train sparse Mixture of Experts models that activate only a fraction of parameters per token, cutting training cost by roughly 5× compared to dense equivalents. ## Core Features & Use Cases - MoE Architecture Implementation: Build sparse MoE layers with top-k routing, gating networks, load balancing losses, and router z-loss in PyTorch, matching designs from Mixtral 8x7B, DeepSeek-V3, and Switch Transformers. - DeepSpeed Training Configuration: Configure expert parallelism, capacity factors, token dropping, and ZeRO optimization for distributed MoE training across multiple GPUs. - Inference Optimization: Apply FP8/INT8 quantization, fused MoE kernels, speculative decoding, and expert pruning with vLLM for production serving. - Use Case: A team wants to train a Mixtral-style model with 8 experts and top-2 routing on 8 GPUs. This Skill supplies the DeepSpeed config, training script, learning rate guidelines, and load balancing coefficients to launch the run and avoid common instability pitfalls. ## Quick Start Ask the agent to set up a DeepSpeed MoE training run with 8 experts, top-2 routing, and expert parallelism across your available GPUs.

Frequently Asked Questions about moe-training

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I train a Mixture of Experts model with DeepSpeed?▼

Install deepspeed 0.6.0 or higher, enable the moe block in your DeepSpeed config with num_experts and expert_parallel_size, then launch training with deepspeed pretrain_gpt_moe.py. Set moe_loss_coeff to 0.01 and train_capacity_factor to 1.25 as starting values.

What learning rate should I use for MoE training?▼

MoE models need learning rates 3-6× lower than dense models, typically around 1e-4 instead of 6e-4. Also extend the LR decay schedule to roughly 1.5-2× longer, such as 500000 iterations instead of 300000.

How many experts should a Mixture of Experts model have?▼

Small models of 1B-7B parameters typically use 8-16 experts, medium models of 7B-30B use 8-64, and large models above 30B use 64-256. Match expert count to dataset diversity, since too many experts on small datasets risks overfitting.

Why is my MoE training showing load imbalance across experts?▼

Load imbalance happens when the router sends most tokens to a few experts. Increase moe_loss_coeff from 0.01 to 0.1, reduce train_capacity_factor to force redistribution, or add jitter noise to router logits during training.

Does vLLM support expert parallelism for MoE inference?▼

Yes, vLLM supports expert parallelism via enable_expert_parallel=True combined with tensor_parallel_size. Adding FP8 quantization gives 20-30% throughput improvement, and fused MoE kernels add another 12-18%.

What is the difference between top-1 and top-2 routing in MoE models?▼

Top-1 routing, used by Switch Transformers, sends each token to a single expert for maximum throughput. Top-2 routing, used by Mixtral, combines two experts per token for better quality at roughly 50-80% lower inference throughput.