moe-training

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

1|Updated Mar 5, 2026
One-click install
npx skills add https://github.com/Clay-HHK/claude-skills --skill moe-training-clay-hhk
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: moe-training
Source: https://github.com/Clay-HHK/claude-skills/tree/main/moe-training
Command: npx skills add https://github.com/Clay-HHK/claude-skills --skill moe-training-clay-hhk

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 requires compute that scales linearly with parameter count, making large-capacity models prohibitively expensive. This Skill guides training of Mixture of Experts (MoE) models that activate only a fraction of parameters per token, achieving roughly 5× training cost reduction 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 for training stability. - DeepSpeed & Megatron-DeepSpeed Training: Configure expert parallelism, capacity factors, PR-MoE pyramid structures, and Mixture-of-Students distillation for large-scale pretraining. - Inference Optimization: Deploy MoE models with vLLM using FP8 quantization, fused MoE kernels, speculative decoding, and expert pruning. - Use Case: Reproduce a Mixtral 8x7B-style model with 8 experts and top-2 routing across 8 GPUs, distributing experts with expert parallelism and tuning the auxiliary loss coefficient to prevent load imbalance. ## Quick Start Ask the AI to help you configure and launch a DeepSpeed MoE training run with a specified number of experts, GPUs, and dataset path.

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 is the difference between top-1 and top-2 routing in MoE models?▼

Top-1 routing (Switch Transformers) sends each token to a single expert for maximum throughput, while top-2 routing (Mixtral) combines two experts per token for better quality. Top-1 inference can deliver 50-80% higher throughput than top-2.

How many experts should I use for my MoE model?▼

Use 8-16 experts for small models (1B-7B), 8-64 for medium models (7B-30B), and 64-256 for large models (30B+). 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 favors 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 MoE training require a lower learning rate than dense models?▼

Yes, MoE models typically need a learning rate 3-6× lower than dense equivalents, such as 1e-4 instead of 6e-4. Also extend the LR decay schedule by 1.5-2×, for example 500000 decay iterations instead of 300000.

Can I run Mixtral 8x7B inference on a single GPU?▼

Yes, with vLLM using AWQ or GPTQ quantization, Mixtral 8x7B fits in roughly 24GB VRAM at INT8 versus 48GB at FP16. Set gpu_memory_utilization to 0.95 and use smaller batch sizes for single-GPU deployment.