[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6QF7HN6PJ31ERZWRAB1VASC":3,"skill-same:01M6QF7HN6PJ31ERZWRAB1VASC":91},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":39,"linkOnly":40,"markdownContent":41,"markdownBody":42,"frontMatter":43,"refName":50,"commitSha":51,"skillDirectory":52,"forksCount":14,"repositoryHtmlUrl":53,"repositoryHomepageUrl":54,"ownerHtmlUrl":55,"ownerBlogUrl":56,"ownerDescription":57,"updatedAt":58,"install":59,"resources":72},"01M6QF7HN6PJ31ERZWRAB1VASC","moe-training",null,"Train Mixture of Experts (MoE) models using DeepSpeed or HuggingFace. Use when training large-scale models with limited compute (5× cost reduction vs dense models), implementing sparse architectures like Mixtral 8x7B or DeepSeek-V3, or scaling model capacity without proportional compute increase. Covers MoE architectures, routing mechanisms, load balancing, expert parallelism, and inference optimization.","Tashima-Tarsh\u002FDisha6.6","Tashima-Tarsh","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F269906498?v=4","01M6PBH98X03XERH0HFT4PFB1P","NITISH KUMAR","01M6PBH9DA0M6KM3Z12P848F0K",0,"MIT","https:\u002F\u002Fgithub.com\u002FTashima-Tarsh\u002FDisha6.6\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fkal-moe-training\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38],"moe training","moe","training","Accelerate","implementing","experts","Efficient Training","Mixtral","Expert Parallelism","Sparse Models","Mixture Of Experts","Emerging Techniques","architectures","scaling","expert","model","Transformers","Optimization","DeepSpeed","multimodal","2026-11-10 10:12:30",false,"---\nname: moe-training\ndescription: Train Mixture of Experts (MoE) models using DeepSpeed or HuggingFace. Use when training large-scale models with limited compute (5× cost reduction vs dense models), implementing sparse architectures like Mixtral 8x7B or DeepSeek-V3, or scaling model capacity without proportional compute increase. Covers MoE architectures, routing mechanisms, load balancing, expert parallelism, and inference optimization.\nlicense: MIT\nmetadata:\n  version: 1.0.0\n  category: multimodal-and-emerging\n  maintainer: Kalaris Labs\n  tags: Emerging Techniques, MoE, Mixture Of Experts, Sparse Models, DeepSpeed, Expert Parallelism, Mixtral, DeepSeek, Routing, Load Balancing, Efficient Training\n  dependencies: deepspeed, transformers, torch, accelerate\n---\n\n# MoE Training: Mixture of Experts\n\n## When to Use This Skill\n\nUse MoE Training when you need to:\n- **Train larger models** with limited compute (5× cost reduction vs dense models)\n- **Scale model capacity** without proportional compute increase\n- **Achieve better performance** per compute budget than dense models\n- **Specialize experts** for different domains\u002Ftasks\u002Flanguages\n- **Reduce inference latency** with sparse activation (only 13B\u002F47B params active in Mixtral)\n- **Implement SOTA models** like Mixtral 8x7B, DeepSeek-V3, Switch Transformers\n\n**Notable MoE Models**: Mixtral 8x7B (Mistral AI), DeepSeek-V3, Switch Transformers (Google), GLaM (Google), NLLB-MoE (Meta)\n\n## Installation\n\n```bash\n# DeepSpeed with MoE support\npip install deepspeed>=0.6.0\n\n# Megatron-DeepSpeed for large-scale training\ngit clone https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FMegatron-DeepSpeed\ncd Megatron-DeepSpeed\npip install -r requirements.txt\n\n# Alternative: HuggingFace Transformers\npip install transformers accelerate\n```\n\n## Quick Start\n\n### Basic MoE Architecture\n\n```python\nimport torch\nimport torch.nn as nn\n\nclass MoELayer(nn.Module):\n    \"\"\"Sparse Mixture of Experts layer.\"\"\"\n\n    def __init__(self, hidden_size, num_experts=8, top_k=2):\n        super().__init__()\n        self.num_experts = num_experts\n        self.top_k = top_k\n\n        # Expert networks (FFN)\n        self.experts = nn.ModuleList([\n            nn.Sequential(\n                nn.Linear(hidden_size, 4 * hidden_size),\n                nn.GELU(),\n                nn.Linear(4 * hidden_size, hidden_size)\n            )\n            for _ in range(num_experts)\n        ])\n\n        # Gating network (router)\n        self.gate = nn.Linear(hidden_size, num_experts)\n\n    def forward(self, x):\n        # x shape: (batch_size, seq_len, hidden_size)\n        batch_size, seq_len, hidden_size = x.shape\n\n        # Flatten for routing\n        x_flat = x.view(-1, hidden_size)  # (batch_size * seq_len, hidden_size)\n\n        # Compute gate scores\n        gate_logits = self.gate(x_flat)  # (batch_size * seq_len, num_experts)\n\n        # Top-k routing\n        gate_scores = torch.softmax(gate_logits, dim=-1)\n        topk_scores, topk_indices = torch.topk(gate_scores, self.top_k, dim=-1)\n\n        # Normalize top-k scores\n        topk_scores = topk_scores \u002F topk_scores.sum(dim=-1, keepdim=True)\n\n        # Dispatch and combine expert outputs\n        output = torch.zeros_like(x_flat)\n\n        for i in range(self.top_k):\n            expert_idx = topk_indices[:, i]\n            expert_scores = topk_scores[:, i].unsqueeze(-1)\n\n            # Route tokens to experts\n            for expert_id in range(self.num_experts):\n                mask = (expert_idx == expert_id)\n                if mask.any():\n                    expert_input = x_flat[mask]\n                    expert_output = self.experts[expert_id](expert_input)\n                    output[mask] += expert_scores[mask] * expert_output\n\n        # Reshape back\n        return output.view(batch_size, seq_len, hidden_size)\n```\n\n### DeepSpeed MoE Training\n\n```bash\n# Training script with MoE\ndeepspeed pretrain_gpt_moe.py \\\n  --num-layers 24 \\\n  --hidden-size 1024 \\\n  --num-attention-heads 16 \\\n  --seq-length 2048 \\\n  --max-position-embeddings 2048 \\\n  --micro-batch-size 4 \\\n  --global-batch-size 256 \\\n  --train-iters 500000 \\\n  --lr 0.0001 \\\n  --min-lr 0.00001 \\\n  --lr-decay-style cosine \\\n  --num-experts 128 \\\n  --moe-expert-parallel-size 4 \\\n  --moe-loss-coeff 0.01 \\\n  --moe-train-capacity-factor 1.25 \\\n  --moe-eval-capacity-factor 2.0 \\\n  --fp16 \\\n  --deepspeed_config ds_config.json\n```\n\n## Core Concepts\n\n### 1. MoE Architecture\n\n**Key Components:**\n- **Experts**: Multiple specialized FFN networks (typically 8-128)\n- **Router\u002FGate**: Learned network that selects which experts to use\n- **Top-k Routing**: Activate only k experts per token (k=1 or k=2)\n- **Load Balancing**: Ensure even expert utilization\n\n```\nInput Token\n    ↓\nRouter (Gate Network)\n    ↓\nTop-k Expert Selection (e.g., 2 out of 8)\n    ↓\nExpert 1 (weight: 0.6) + Expert 5 (weight: 0.4)\n    ↓\nWeighted Combination\n    ↓\nOutput\n```\n\n### 2. Routing Mechanisms\n\n**Top-1 Routing (Switch Transformer):**\n```python\n# Simplest routing: one expert per token\ngate_logits = router(x)  # (batch, seq_len, num_experts)\nexpert_idx = torch.argmax(gate_logits, dim=-1)  # Hard routing\n```\n\n**Top-2 Routing (Mixtral):**\n```python\n# Top-2: two experts per token\ngate_scores = torch.softmax(router(x), dim=-1)\ntop2_scores, top2_indices = torch.topk(gate_scores, k=2, dim=-1)\n\n# Normalize scores\ntop2_scores = top2_scores \u002F top2_scores.sum(dim=-1, keepdim=True)\n\n# Combine expert outputs\noutput = (top2_scores[:, :, 0:1] * expert_outputs[top2_indices[:, :, 0]] +\n          top2_scores[:, :, 1:2] * expert_outputs[top2_indices[:, :, 1]])\n```\n\n**Expert Choice Routing:**\n```python\n# Experts choose top-k tokens (instead of tokens choosing experts)\n# Guarantees perfect load balancing\nexpert_scores = router(x).transpose(-1, -2)  # (batch, num_experts, seq_len)\ntopk_tokens = torch.topk(expert_scores, k=capacity_per_expert, dim=-1)\n```\n\n### 3. Load Balancing\n\n**Auxiliary Loss:**\n```python\ndef load_balancing_loss(gate_logits, expert_indices, num_experts):\n    \"\"\"Encourage uniform expert usage.\"\"\"\n    # Fraction of tokens routed to each expert\n    expert_counts = torch.bincount(expert_indices.flatten(), minlength=num_experts)\n    expert_fraction = expert_counts.float() \u002F expert_indices.numel()\n\n    # Gate probability for each expert (average across tokens)\n    gate_probs = torch.softmax(gate_logits, dim=-1).mean(dim=0)\n\n    # Auxiliary loss: encourage alignment\n    aux_loss = num_experts * (expert_fraction * gate_probs).sum()\n\n    return aux_loss\n\n# Add to main loss\ntotal_loss = language_model_loss + 0.01 * load_balancing_loss(...)\n```\n\n**Router Z-Loss (Stability):**\n```python\ndef router_z_loss(logits):\n    \"\"\"Encourage router to have lower entropy (more decisive).\"\"\"\n    z_loss = torch.logsumexp(logits, dim=-1).pow(2).mean()\n    return z_loss\n\ntotal_loss = lm_loss + 0.01 * aux_loss + 0.001 * router_z_loss(gate_logits)\n```\n\n### 4. Expert Parallelism\n\n```python\n# DeepSpeed configuration\n{\n  \"train_batch_size\": 256,\n  \"fp16\": {\"enabled\": true},\n  \"moe\": {\n    \"enabled\": true,\n    \"num_experts\": 128,\n    \"expert_parallel_size\": 8,  # Distribute 128 experts across 8 GPUs\n    \"capacity_factor\": 1.25,    # Expert capacity = tokens_per_batch * capacity_factor \u002F num_experts\n    \"drop_tokens\": true,        # Drop tokens exceeding capacity\n    \"use_residual\": false\n  }\n}\n```\n\n## Training Configuration\n\n### DeepSpeed MoE Config\n\n```json\n{\n  \"train_batch_size\": 256,\n  \"gradient_accumulation_steps\": 1,\n  \"optimizer\": {\n    \"type\": \"Adam\",\n    \"params\": {\n      \"lr\": 0.0001,\n      \"betas\": [0.9, 0.999],\n      \"eps\": 1e-8\n    }\n  },\n  \"fp16\": {\n    \"enabled\": true,\n    \"loss_scale\": 0,\n    \"initial_scale_power\": 16\n  },\n  \"moe\": {\n    \"enabled\": true,\n    \"num_experts\": 128,\n    \"expert_parallel_size\": 8,\n    \"moe_loss_coeff\": 0.01,\n    \"train_capacity_factor\": 1.25,\n    \"eval_capacity_factor\": 2.0,\n    \"min_capacity\": 4,\n    \"drop_tokens\": true,\n    \"use_residual\": false,\n    \"use_tutel\": false\n  },\n  \"zero_optimization\": {\n    \"stage\": 1\n  }\n}\n```\n\n### Training Script\n\n```bash\n#!\u002Fbin\u002Fbash\n\n# Mixtral-style MoE training\ndeepspeed --num_gpus 8 pretrain_moe.py \\\n  --model-parallel-size 1 \\\n  --num-layers 32 \\\n  --hidden-size 4096 \\\n  --num-attention-heads 32 \\\n  --seq-length 2048 \\\n  --max-position-embeddings 4096 \\\n  --micro-batch-size 2 \\\n  --global-batch-size 256 \\\n  --train-iters 500000 \\\n  --save-interval 5000 \\\n  --eval-interval 1000 \\\n  --eval-iters 100 \\\n  --lr 0.0001 \\\n  --min-lr 0.00001 \\\n  --lr-decay-style cosine \\\n  --lr-warmup-iters 2000 \\\n  --clip-grad 1.0 \\\n  --weight-decay 0.1 \\\n  --num-experts 8 \\\n  --moe-expert-parallel-size 4 \\\n  --moe-loss-coeff 0.01 \\\n  --moe-train-capacity-factor 1.25 \\\n  --moe-eval-capacity-factor 2.0 \\\n  --disable-moe-token-dropping \\\n  --fp16 \\\n  --deepspeed \\\n  --deepspeed_config ds_config_moe.json \\\n  --data-path \u002Fpath\u002Fto\u002Fdata \\\n  --vocab-file \u002Fpath\u002Fto\u002Fvocab.json \\\n  --merge-file \u002Fpath\u002Fto\u002Fmerges.txt\n```\n\n## Advanced Patterns\n\nDetails, code examples and parameter tables: [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md). Read it when this step applies.\n\n## Best Practices\n\n### 1. Expert Count Selection\n\n```python\n# Rule of thumb: More experts = more capacity, but diminishing returns\n# Typical configurations:\n# - Small models (1B-7B): 8-16 experts\n# - Medium models (7B-30B): 8-64 experts\n# - Large models (30B+): 64-256 experts\n\n# Example: Mixtral 8x7B\n# Total params: 47B (8 experts × 7B each)\n# Active params: 13B (2 experts × 7B, top-2 routing)\n# Efficiency: 47B capacity with 13B compute\n```\n\n### 2. Capacity Factor Tuning\n\n```python\n# Capacity = (tokens_per_batch \u002F num_experts) * capacity_factor\n\n# Training: Lower capacity (faster, drops some tokens)\ntrain_capacity_factor = 1.25  # 25% buffer\n\n# Evaluation: Higher capacity (no dropping)\neval_capacity_factor = 2.0    # 100% buffer\n\n# Formula:\nexpert_capacity = int((seq_len * batch_size \u002F num_experts) * capacity_factor)\n```\n\n### 3. Learning Rate Guidelines\n\n```python\n# MoE models need lower LR than dense models\n# - Dense model: lr = 6e-4\n# - MoE model: lr = 1e-4 (3-6× lower)\n\n# Also extend decay schedule\ndense_lr_decay_iters = 300000\nmoe_lr_decay_iters = 500000  # 1.5-2× longer\n```\n\n### 4. Loss Coefficient Tuning\n\n```python\n# Start with standard values\nmoe_loss_coeff = 0.01    # Auxiliary loss (load balancing)\nrouter_z_loss_coeff = 0.001  # Router entropy (stability)\n\n# If load imbalance persists, increase aux loss\nif max_expert_usage \u002F min_expert_usage > 2.0:\n    moe_loss_coeff = 0.1  # Stronger load balancing\n\n# If training unstable, increase z-loss\nif grad_norm > 10.0:\n    router_z_loss_coeff = 0.01\n```\n\n### 5. Avoid Common Pitfalls\n\n```python\n# ❌ Bad: Using same LR as dense model\noptimizer = Adam(model.parameters(), lr=6e-4)\n\n# ✅ Good: Lower LR for MoE\noptimizer = Adam([\n    {'params': model.non_moe_params, 'lr': 6e-4},\n    {'params': model.moe_params, 'lr': 1e-4}\n])\n\n# ❌ Bad: No load balancing\nloss = lm_loss\n\n# ✅ Good: Add auxiliary loss\nloss = lm_loss + 0.01 * aux_loss + 0.001 * z_loss\n\n# ❌ Bad: Too many experts for small dataset\nnum_experts = 128  # Overfitting risk\n\n# ✅ Good: Match experts to data diversity\nnum_experts = 8  # Better for small datasets\n```\n\n## Inference Optimization\n\n### Sparse Inference\n\n```python\n# Only activate top-k experts (huge memory savings)\n@torch.no_grad()\ndef moe_inference(x, model, top_k=2):\n    \"\"\"Sparse MoE inference: only load k experts.\"\"\"\n    # Router\n    gate_logits = model.gate(x)\n    topk_scores, topk_indices = torch.topk(\n        torch.softmax(gate_logits, dim=-1),\n        k=top_k,\n        dim=-1\n    )\n\n    # Load and run only top-k experts\n    output = torch.zeros_like(x)\n    for i in range(top_k):\n        expert_idx = topk_indices[:, i]\n        # Load expert from disk\u002Foffload if needed\n        expert = model.load_expert(expert_idx)\n        output += topk_scores[:, i:i+1] * expert(x)\n\n    return output\n```\n\n## Resources\n\n- **DeepSpeed MoE Tutorial**: https:\u002F\u002Fwww.deepspeed.ai\u002Ftutorials\u002Fmixture-of-experts-nlg\u002F\n- **Mixtral Paper**: https:\u002F\u002Farxiv.org\u002Fabs\u002F2401.04088\n- **Switch Transformers**: https:\u002F\u002Farxiv.org\u002Fabs\u002F2101.03961\n- **HuggingFace MoE Guide**: https:\u002F\u002Fhuggingface.co\u002Fblog\u002Fmoe\n- **NVIDIA MoE Blog**: https:\u002F\u002Fdeveloper.nvidia.com\u002Fblog\u002Fapplying-mixture-of-experts-in-llm-architectures\u002F\n\n## See Also\n\n- `references\u002Farchitectures.md` - MoE model architectures (Mixtral, Switch, DeepSeek-V3)\n- `references\u002Ftraining.md` - Advanced training techniques and optimization\n- `references\u002Finference.md` - Production deployment and serving patterns\n\n## Agent operating procedure\n\n1. **Check the environment.** Confirm GPU memory, model checkpoint and licence, framework versions and input formats.\n2. **Pin down the inputs.** Confirm formats, identifiers and parameters from the data or the user. Ask rather than guess any value that changes the result.\n3. **Run a small version first.** Run inference on a single sample at low resolution or short length first.\n4. **Execute the full task** using the instructions and references above.\n5. **Validate the result.** Inspect outputs qualitatively and with task metrics; check licence restrictions for generated content.\n6. **Report.** State what was run (versions, commands, parameters), what was checked, and what is still uncertain.\n\n| If this happens | Do this |\n|---|---|\n| Out-of-memory on large inputs | Reduce resolution or sequence length, use half precision, or tile the input. |\n| A function, flag or endpoint in these instructions is missing in the installed version | Check the installed version's own documentation (`help()`, `--help`, official docs), adapt, and tell the user. Never invent an API. |\n| A required input, identifier or parameter is ambiguous | Ask the user, or state the assumption explicitly before running. |\n\n**Integrity rules**\n\n- Never fabricate results, parameters, identifiers, citations or statistics. If something cannot be run or verified, say so plainly.\n- Check model and dataset licences before commercial or published use.\n- Treat version-specific details here as possibly outdated: confirm them against the official documentation for the installed version.\n- Ask before actions that cost money, consume shared GPUs or cloud quota, touch personal or patient data, or cannot be undone.\n","# MoE Training: Mixture of Experts\n\n## When to Use This Skill\n\nUse MoE Training when you need to:\n- **Train larger models** with limited compute (5× cost reduction vs dense models)\n- **Scale model capacity** without proportional compute increase\n- **Achieve better performance** per compute budget than dense models\n- **Specialize experts** for different domains\u002Ftasks\u002Flanguages\n- **Reduce inference latency** with sparse activation (only 13B\u002F47B params active in Mixtral)\n- **Implement SOTA models** like Mixtral 8x7B, DeepSeek-V3, Switch Transformers\n\n**Notable MoE Models**: Mixtral 8x7B (Mistral AI), DeepSeek-V3, Switch Transformers (Google), GLaM (Google), NLLB-MoE (Meta)\n\n## Installation\n\n```bash\n# DeepSpeed with MoE support\npip install deepspeed>=0.6.0\n\n# Megatron-DeepSpeed for large-scale training\ngit clone https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FMegatron-DeepSpeed\ncd Megatron-DeepSpeed\npip install -r requirements.txt\n\n# Alternative: HuggingFace Transformers\npip install transformers accelerate\n```\n\n## Quick Start\n\n### Basic MoE Architecture\n\n```python\nimport torch\nimport torch.nn as nn\n\nclass MoELayer(nn.Module):\n    \"\"\"Sparse Mixture of Experts layer.\"\"\"\n\n    def __init__(self, hidden_size, num_experts=8, top_k=2):\n        super().__init__()\n        self.num_experts = num_experts\n        self.top_k = top_k\n\n        # Expert networks (FFN)\n        self.experts = nn.ModuleList([\n            nn.Sequential(\n                nn.Linear(hidden_size, 4 * hidden_size),\n                nn.GELU(),\n                nn.Linear(4 * hidden_size, hidden_size)\n            )\n            for _ in range(num_experts)\n        ])\n\n        # Gating network (router)\n        self.gate = nn.Linear(hidden_size, num_experts)\n\n    def forward(self, x):\n        # x shape: (batch_size, seq_len, hidden_size)\n        batch_size, seq_len, hidden_size = x.shape\n\n        # Flatten for routing\n        x_flat = x.view(-1, hidden_size)  # (batch_size * seq_len, hidden_size)\n\n        # Compute gate scores\n        gate_logits = self.gate(x_flat)  # (batch_size * seq_len, num_experts)\n\n        # Top-k routing\n        gate_scores = torch.softmax(gate_logits, dim=-1)\n        topk_scores, topk_indices = torch.topk(gate_scores, self.top_k, dim=-1)\n\n        # Normalize top-k scores\n        topk_scores = topk_scores \u002F topk_scores.sum(dim=-1, keepdim=True)\n\n        # Dispatch and combine expert outputs\n        output = torch.zeros_like(x_flat)\n\n        for i in range(self.top_k):\n            expert_idx = topk_indices[:, i]\n            expert_scores = topk_scores[:, i].unsqueeze(-1)\n\n            # Route tokens to experts\n            for expert_id in range(self.num_experts):\n                mask = (expert_idx == expert_id)\n                if mask.any():\n                    expert_input = x_flat[mask]\n                    expert_output = self.experts[expert_id](expert_input)\n                    output[mask] += expert_scores[mask] * expert_output\n\n        # Reshape back\n        return output.view(batch_size, seq_len, hidden_size)\n```\n\n### DeepSpeed MoE Training\n\n```bash\n# Training script with MoE\ndeepspeed pretrain_gpt_moe.py \\\n  --num-layers 24 \\\n  --hidden-size 1024 \\\n  --num-attention-heads 16 \\\n  --seq-length 2048 \\\n  --max-position-embeddings 2048 \\\n  --micro-batch-size 4 \\\n  --global-batch-size 256 \\\n  --train-iters 500000 \\\n  --lr 0.0001 \\\n  --min-lr 0.00001 \\\n  --lr-decay-style cosine \\\n  --num-experts 128 \\\n  --moe-expert-parallel-size 4 \\\n  --moe-loss-coeff 0.01 \\\n  --moe-train-capacity-factor 1.25 \\\n  --moe-eval-capacity-factor 2.0 \\\n  --fp16 \\\n  --deepspeed_config ds_config.json\n```\n\n## Core Concepts\n\n### 1. MoE Architecture\n\n**Key Components:**\n- **Experts**: Multiple specialized FFN networks (typically 8-128)\n- **Router\u002FGate**: Learned network that selects which experts to use\n- **Top-k Routing**: Activate only k experts per token (k=1 or k=2)\n- **Load Balancing**: Ensure even expert utilization\n\n```\nInput Token\n    ↓\nRouter (Gate Network)\n    ↓\nTop-k Expert Selection (e.g., 2 out of 8)\n    ↓\nExpert 1 (weight: 0.6) + Expert 5 (weight: 0.4)\n    ↓\nWeighted Combination\n    ↓\nOutput\n```\n\n### 2. Routing Mechanisms\n\n**Top-1 Routing (Switch Transformer):**\n```python\n# Simplest routing: one expert per token\ngate_logits = router(x)  # (batch, seq_len, num_experts)\nexpert_idx = torch.argmax(gate_logits, dim=-1)  # Hard routing\n```\n\n**Top-2 Routing (Mixtral):**\n```python\n# Top-2: two experts per token\ngate_scores = torch.softmax(router(x), dim=-1)\ntop2_scores, top2_indices = torch.topk(gate_scores, k=2, dim=-1)\n\n# Normalize scores\ntop2_scores = top2_scores \u002F top2_scores.sum(dim=-1, keepdim=True)\n\n# Combine expert outputs\noutput = (top2_scores[:, :, 0:1] * expert_outputs[top2_indices[:, :, 0]] +\n          top2_scores[:, :, 1:2] * expert_outputs[top2_indices[:, :, 1]])\n```\n\n**Expert Choice Routing:**\n```python\n# Experts choose top-k tokens (instead of tokens choosing experts)\n# Guarantees perfect load balancing\nexpert_scores = router(x).transpose(-1, -2)  # (batch, num_experts, seq_len)\ntopk_tokens = torch.topk(expert_scores, k=capacity_per_expert, dim=-1)\n```\n\n### 3. Load Balancing\n\n**Auxiliary Loss:**\n```python\ndef load_balancing_loss(gate_logits, expert_indices, num_experts):\n    \"\"\"Encourage uniform expert usage.\"\"\"\n    # Fraction of tokens routed to each expert\n    expert_counts = torch.bincount(expert_indices.flatten(), minlength=num_experts)\n    expert_fraction = expert_counts.float() \u002F expert_indices.numel()\n\n    # Gate probability for each expert (average across tokens)\n    gate_probs = torch.softmax(gate_logits, dim=-1).mean(dim=0)\n\n    # Auxiliary loss: encourage alignment\n    aux_loss = num_experts * (expert_fraction * gate_probs).sum()\n\n    return aux_loss\n\n# Add to main loss\ntotal_loss = language_model_loss + 0.01 * load_balancing_loss(...)\n```\n\n**Router Z-Loss (Stability):**\n```python\ndef router_z_loss(logits):\n    \"\"\"Encourage router to have lower entropy (more decisive).\"\"\"\n    z_loss = torch.logsumexp(logits, dim=-1).pow(2).mean()\n    return z_loss\n\ntotal_loss = lm_loss + 0.01 * aux_loss + 0.001 * router_z_loss(gate_logits)\n```\n\n### 4. Expert Parallelism\n\n```python\n# DeepSpeed configuration\n{\n  \"train_batch_size\": 256,\n  \"fp16\": {\"enabled\": true},\n  \"moe\": {\n    \"enabled\": true,\n    \"num_experts\": 128,\n    \"expert_parallel_size\": 8,  # Distribute 128 experts across 8 GPUs\n    \"capacity_factor\": 1.25,    # Expert capacity = tokens_per_batch * capacity_factor \u002F num_experts\n    \"drop_tokens\": true,        # Drop tokens exceeding capacity\n    \"use_residual\": false\n  }\n}\n```\n\n## Training Configuration\n\n### DeepSpeed MoE Config\n\n```json\n{\n  \"train_batch_size\": 256,\n  \"gradient_accumulation_steps\": 1,\n  \"optimizer\": {\n    \"type\": \"Adam\",\n    \"params\": {\n      \"lr\": 0.0001,\n      \"betas\": [0.9, 0.999],\n      \"eps\": 1e-8\n    }\n  },\n  \"fp16\": {\n    \"enabled\": true,\n    \"loss_scale\": 0,\n    \"initial_scale_power\": 16\n  },\n  \"moe\": {\n    \"enabled\": true,\n    \"num_experts\": 128,\n    \"expert_parallel_size\": 8,\n    \"moe_loss_coeff\": 0.01,\n    \"train_capacity_factor\": 1.25,\n    \"eval_capacity_factor\": 2.0,\n    \"min_capacity\": 4,\n    \"drop_tokens\": true,\n    \"use_residual\": false,\n    \"use_tutel\": false\n  },\n  \"zero_optimization\": {\n    \"stage\": 1\n  }\n}\n```\n\n### Training Script\n\n```bash\n#!\u002Fbin\u002Fbash\n\n# Mixtral-style MoE training\ndeepspeed --num_gpus 8 pretrain_moe.py \\\n  --model-parallel-size 1 \\\n  --num-layers 32 \\\n  --hidden-size 4096 \\\n  --num-attention-heads 32 \\\n  --seq-length 2048 \\\n  --max-position-embeddings 4096 \\\n  --micro-batch-size 2 \\\n  --global-batch-size 256 \\\n  --train-iters 500000 \\\n  --save-interval 5000 \\\n  --eval-interval 1000 \\\n  --eval-iters 100 \\\n  --lr 0.0001 \\\n  --min-lr 0.00001 \\\n  --lr-decay-style cosine \\\n  --lr-warmup-iters 2000 \\\n  --clip-grad 1.0 \\\n  --weight-decay 0.1 \\\n  --num-experts 8 \\\n  --moe-expert-parallel-size 4 \\\n  --moe-loss-coeff 0.01 \\\n  --moe-train-capacity-factor 1.25 \\\n  --moe-eval-capacity-factor 2.0 \\\n  --disable-moe-token-dropping \\\n  --fp16 \\\n  --deepspeed \\\n  --deepspeed_config ds_config_moe.json \\\n  --data-path \u002Fpath\u002Fto\u002Fdata \\\n  --vocab-file \u002Fpath\u002Fto\u002Fvocab.json \\\n  --merge-file \u002Fpath\u002Fto\u002Fmerges.txt\n```\n\n## Advanced Patterns\n\nDetails, code examples and parameter tables: [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md). Read it when this step applies.\n\n## Best Practices\n\n### 1. Expert Count Selection\n\n```python\n# Rule of thumb: More experts = more capacity, but diminishing returns\n# Typical configurations:\n# - Small models (1B-7B): 8-16 experts\n# - Medium models (7B-30B): 8-64 experts\n# - Large models (30B+): 64-256 experts\n\n# Example: Mixtral 8x7B\n# Total params: 47B (8 experts × 7B each)\n# Active params: 13B (2 experts × 7B, top-2 routing)\n# Efficiency: 47B capacity with 13B compute\n```\n\n### 2. Capacity Factor Tuning\n\n```python\n# Capacity = (tokens_per_batch \u002F num_experts) * capacity_factor\n\n# Training: Lower capacity (faster, drops some tokens)\ntrain_capacity_factor = 1.25  # 25% buffer\n\n# Evaluation: Higher capacity (no dropping)\neval_capacity_factor = 2.0    # 100% buffer\n\n# Formula:\nexpert_capacity = int((seq_len * batch_size \u002F num_experts) * capacity_factor)\n```\n\n### 3. Learning Rate Guidelines\n\n```python\n# MoE models need lower LR than dense models\n# - Dense model: lr = 6e-4\n# - MoE model: lr = 1e-4 (3-6× lower)\n\n# Also extend decay schedule\ndense_lr_decay_iters = 300000\nmoe_lr_decay_iters = 500000  # 1.5-2× longer\n```\n\n### 4. Loss Coefficient Tuning\n\n```python\n# Start with standard values\nmoe_loss_coeff = 0.01    # Auxiliary loss (load balancing)\nrouter_z_loss_coeff = 0.001  # Router entropy (stability)\n\n# If load imbalance persists, increase aux loss\nif max_expert_usage \u002F min_expert_usage > 2.0:\n    moe_loss_coeff = 0.1  # Stronger load balancing\n\n# If training unstable, increase z-loss\nif grad_norm > 10.0:\n    router_z_loss_coeff = 0.01\n```\n\n### 5. Avoid Common Pitfalls\n\n```python\n# ❌ Bad: Using same LR as dense model\noptimizer = Adam(model.parameters(), lr=6e-4)\n\n# ✅ Good: Lower LR for MoE\noptimizer = Adam([\n    {'params': model.non_moe_params, 'lr': 6e-4},\n    {'params': model.moe_params, 'lr': 1e-4}\n])\n\n# ❌ Bad: No load balancing\nloss = lm_loss\n\n# ✅ Good: Add auxiliary loss\nloss = lm_loss + 0.01 * aux_loss + 0.001 * z_loss\n\n# ❌ Bad: Too many experts for small dataset\nnum_experts = 128  # Overfitting risk\n\n# ✅ Good: Match experts to data diversity\nnum_experts = 8  # Better for small datasets\n```\n\n## Inference Optimization\n\n### Sparse Inference\n\n```python\n# Only activate top-k experts (huge memory savings)\n@torch.no_grad()\ndef moe_inference(x, model, top_k=2):\n    \"\"\"Sparse MoE inference: only load k experts.\"\"\"\n    # Router\n    gate_logits = model.gate(x)\n    topk_scores, topk_indices = torch.topk(\n        torch.softmax(gate_logits, dim=-1),\n        k=top_k,\n        dim=-1\n    )\n\n    # Load and run only top-k experts\n    output = torch.zeros_like(x)\n    for i in range(top_k):\n        expert_idx = topk_indices[:, i]\n        # Load expert from disk\u002Foffload if needed\n        expert = model.load_expert(expert_idx)\n        output += topk_scores[:, i:i+1] * expert(x)\n\n    return output\n```\n\n## Resources\n\n- **DeepSpeed MoE Tutorial**: https:\u002F\u002Fwww.deepspeed.ai\u002Ftutorials\u002Fmixture-of-experts-nlg\u002F\n- **Mixtral Paper**: https:\u002F\u002Farxiv.org\u002Fabs\u002F2401.04088\n- **Switch Transformers**: https:\u002F\u002Farxiv.org\u002Fabs\u002F2101.03961\n- **HuggingFace MoE Guide**: https:\u002F\u002Fhuggingface.co\u002Fblog\u002Fmoe\n- **NVIDIA MoE Blog**: https:\u002F\u002Fdeveloper.nvidia.com\u002Fblog\u002Fapplying-mixture-of-experts-in-llm-architectures\u002F\n\n## See Also\n\n- `references\u002Farchitectures.md` - MoE model architectures (Mixtral, Switch, DeepSeek-V3)\n- `references\u002Ftraining.md` - Advanced training techniques and optimization\n- `references\u002Finference.md` - Production deployment and serving patterns\n\n## Agent operating procedure\n\n1. **Check the environment.** Confirm GPU memory, model checkpoint and licence, framework versions and input formats.\n2. **Pin down the inputs.** Confirm formats, identifiers and parameters from the data or the user. Ask rather than guess any value that changes the result.\n3. **Run a small version first.** Run inference on a single sample at low resolution or short length first.\n4. **Execute the full task** using the instructions and references above.\n5. **Validate the result.** Inspect outputs qualitatively and with task metrics; check licence restrictions for generated content.\n6. **Report.** State what was run (versions, commands, parameters), what was checked, and what is still uncertain.\n\n| If this happens | Do this |\n|---|---|\n| Out-of-memory on large inputs | Reduce resolution or sequence length, use half precision, or tile the input. |\n| A function, flag or endpoint in these instructions is missing in the installed version | Check the installed version's own documentation (`help()`, `--help`, official docs), adapt, and tell the user. Never invent an API. |\n| A required input, identifier or parameter is ambiguous | Ask the user, or state the assumption explicitly before running. |\n\n**Integrity rules**\n\n- Never fabricate results, parameters, identifiers, citations or statistics. If something cannot be run or verified, say so plainly.\n- Check model and dataset licences before commercial or published use.\n- Treat version-specific details here as possibly outdated: confirm them against the official documentation for the installed version.\n- Ask before actions that cost money, consume shared GPUs or cloud quota, touch personal or patient data, or cannot be undone.\n",{"name":5,"license":15,"metadata":44,"description":7},{"tags":45,"version":46,"category":47,"maintainer":48,"dependencies":49},"Emerging Techniques, MoE, Mixture Of Experts, Sparse Models, DeepSpeed, Expert Parallelism, Mixtral, DeepSeek, Routing, Load Balancing, Efficient Training","1.0.0","multimodal-and-emerging","Kalaris Labs","deepspeed, transformers, torch, accelerate","main","0da4485785ee599388900be50db1635489d53056",".agents\u002Fskills\u002Fkal-moe-training","https:\u002F\u002Fgithub.com\u002FTashima-Tarsh\u002FDisha6.6","https:\u002F\u002Fdisha6.6.thenitishkr.in\u002F","https:\u002F\u002Fgithub.com\u002FTashima-Tarsh","www.thenitishkr","thenitishkr | AI • Cyber-security • Research\r\n","2026-11-08 03:33:25",{"source":8,"skillName":5,"commands":60,"prompt":70,"zipAvailable":71},[61,64,67],{"tool":62,"command":63},"npx","npx skills add Tashima-Tarsh\u002FDisha6.6 --skill moe-training",{"tool":65,"command":66},"bunx","bunx skills add Tashima-Tarsh\u002FDisha6.6 --skill moe-training",{"tool":68,"command":69},"pnpm","pnpm dlx skills add Tashima-Tarsh\u002FDisha6.6 --skill moe-training","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FTashima-Tarsh\u002FDisha6.6\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fkal-moe-training\u002FSKILL.md",true,[73,79,83,87],{"path":74,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":77,"sourceHtmlUrl":78},"references\u002Fadvanced-patterns.md","REFERENCE","参考文档",2630,"https:\u002F\u002Fgithub.com\u002FTashima-Tarsh\u002FDisha6.6\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fkal-moe-training\u002Freferences\u002Fadvanced-patterns.md",{"path":80,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":81,"sourceHtmlUrl":82},"references\u002Farchitectures.md",14044,"https:\u002F\u002Fgithub.com\u002FTashima-Tarsh\u002FDisha6.6\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fkal-moe-training\u002Freferences\u002Farchitectures.md",{"path":84,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":85,"sourceHtmlUrl":86},"references\u002Finference.md",8239,"https:\u002F\u002Fgithub.com\u002FTashima-Tarsh\u002FDisha6.6\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fkal-moe-training\u002Freferences\u002Finference.md",{"path":88,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":89,"sourceHtmlUrl":90},"references\u002Ftraining.md",9707,"https:\u002F\u002Fgithub.com\u002FTashima-Tarsh\u002FDisha6.6\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fkal-moe-training\u002Freferences\u002Ftraining.md",[92,124,149,176,201,225],{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":103,"publishedAt":39},"01M6QRD07D4TGNDK6VJ4EHF8BV","youtube-full","Use when the user needs YouTube transcripts, video search, channel browsing, playlist extraction, or content monitoring. Trigger phrases: 'get the transcript for', 'search YouTube for', 'what are the latest videos on', 'list this playlist', 'monitor this channel', or any request involving a YouTube URL, video ID, or @handle. Do NOT use for downloading video or audio files, YouTube engagement data (likes, comments), or private\u002Fage-restricted videos.","https:\u002F\u002Fgithub.com\u002FTashima-Tarsh\u002FDisha6.6\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fyoutube-full\u002FSKILL.md",[98],{"categoryNo":99,"categoryName":100,"taxonomyType":101,"taxonomyTypeDesc":102},"01JBSEEDCAT000000000000016","图像与多媒体","SCENARIO","使用场景",[104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123],"youtube full","youtube","full","transcript","search","monitoring","data","Video","Audio","list","files","do","get","age","trigger","URL","for","browsing","request","youtube transcripts",{"skillNo":125,"name":126,"nameZh":6,"description":127,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":128,"categories":129,"keywords":130,"publishedAt":39},"01M6QRCJ3112VYPA97YG7KGMC2","x-twitter-growth","X\u002FTwitter growth engine for building audience, crafting viral content, and analyzing engagement. Use when the user wants to grow on X\u002FTwitter, write tweets or threads, analyze their X profile, research competitors on X, plan a posting strategy, or optimize engagement. Complements social-content (generic multi-platform) with X-specific depth: algorithm mechanics, thread engineering, reply strategy, profile optimization, and competitive intelligence via web search.","https:\u002F\u002Fgithub.com\u002FTashima-Tarsh\u002FDisha6.6\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fx-twitter-growth\u002FSKILL.md",[],[131,132,133,134,108,135,136,137,138,139,140,141,142,143,144,145,146,147,148,120],"twitter","x twitter growth","growth","research","content","engineering","plan","web search","competitors","analyze","engine","write","strategy","use","platform","grow","posting","competitive",{"skillNo":150,"name":151,"nameZh":6,"description":152,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":153,"categories":154,"keywords":158,"publishedAt":39},"01M6QRBN3EHQNJY42RERP7A149","write-a-skill","Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, build, or author a new skill.","https:\u002F\u002Fgithub.com\u002FTashima-Tarsh\u002FDisha6.6\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fwrite-a-skill\u002FSKILL.md",[155],{"categoryNo":156,"categoryName":157,"taxonomyType":101,"taxonomyTypeDesc":102},"01JBSEEDCAT000000000000023","Skill与智能体开发",[159,142,160,161,162,163,164,165,144,166,167,50,168,169,170,171,172,173,174,175],"write a skill","github","create","https","productivity","matt pocock","direct","example","build","new skill","structure","new agent","resources","with","tree","progressive disclosure","author",{"skillNo":177,"name":178,"nameZh":6,"description":179,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":180,"categories":181,"keywords":182,"publishedAt":39},"01M6QRB6G8P33PNGAF9Y69EJ9T","wrap-up","Close out a launched Claude Managed Agent — recap every primitive the founder now owns, regenerate the single-file overview page, and suggest the next 1-2 upgrades. Use when the user says \"wrap up\", \"close this out\", \"what do I own now\", \"give me the summary\", \"recap the agent\", or when the orchestrator routes phase=wrap-up. primitives_inventory.py tables everything owned (agent, environment, session, memory, outcome, deployment); overview_page.py regenerates a self-contained .\u002Fmy-agent\u002Fagent-overview.html; upgrade_suggester.py ranks the next moves from recorded deferrals plus standing hardening steps. Companion to run-without-you; the last stop before phase=done.","https:\u002F\u002Fgithub.com\u002FTashima-Tarsh\u002FDisha6.6\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fwrap-up\u002FSKILL.md",[],[183,184,185,186,187,188,189,190,191,144,192,115,193,194,195,196,197,198,199,200],"wrap up","up","wrap","gemini","deployment","run","file","hardening","closeout","stop","upgrade","founder","close","companion","you","tables","directions","phase",{"skillNo":202,"name":203,"nameZh":6,"description":204,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":205,"categories":206,"keywords":208,"publishedAt":39},"01M6QRA5AYC1RBFZ39GTWGS3N8","workflow-builder","Design and write deterministic multi-agent workflow scripts (.js files in .claude\u002Fworkflows\u002F) for Claude Code's Workflow tool. Use when a user wants to build, create, author, scaffold, or run a custom Claude Code workflow, orchestrate sub-agents (fan-out, pipeline, loop, judge-panel), or automate a repeatable multi-step task across fresh-context agents.","https:\u002F\u002Fgithub.com\u002FTashima-Tarsh\u002FDisha6.6\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fworkflow-builder\u002FSKILL.md",[207],{"categoryNo":156,"categoryName":157,"taxonomyType":101,"taxonomyTypeDesc":102},[209,210,211,212,213,161,188,214,215,216,217,218,142,219,114,220,221,222,223,224],"workflow","workflow builder","builder","design","workflows","code","orchestrate","pipeline","loop","multi-agent","context","across","fresh","scripts","judge","claude code workflow",{"skillNo":226,"name":227,"nameZh":6,"description":228,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":229,"categories":230,"keywords":231,"publishedAt":39},"01M6QR7QMCZESKQA0ERW1E657M","weekly-review","Use when someone wants to run a weekly review, close open loops, audit stalled projects and commitments, get their system back to trusted, restart a lapsed review habit, or says \"\u002Fcs:weekly-review\". Walks David Allen's three-phase loop — GET CLEAR, GET CURRENT, GET CREATIVE — with deterministic scripts that inventory open loops, gate the checklist with named gaps, and score commitment health 0-100.","https:\u002F\u002Fgithub.com\u002FTashima-Tarsh\u002FDisha6.6\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fweekly-review\u002FSKILL.md",[],[232,233,234,235,236,237,238,239,240,217,241,242,243,244,245,246,116,247,248,200],"review","weekly review","weekly","deterministic scripts","reflect","feeds","inventory","open","team","projects","project-management","scanner","conversation","back","project","sprint","cadence"]