How lfan-ke/es-moe works
ES-MoE Toolkit is a Python library that adds expert-sparse mixture-of-experts blocks to Ultralytics YOLO, plus scripts for training and evaluating research runs. The main workflow is to register the block, graft it into a model configuration, build the YOLO model, and route auxiliary router loss into training; the equip entry point combines these steps. Separate capabilities support custom experts and balancing losses, DDP training, YOLO-Master recipe comparisons, and routing and metric analysis. The source excerpts show core runtime behavior; script relationships beyond indexed imports are omitted where not evidenced.
Main entry points: __init__.py Public API and CLI · inject.py Register and equip · report.py Metric reporting · trainer.py DDP trainer
Components 19
Model integration
- Public API and CLI
esmoe/__init__.py - Register and equip
esmoe/inject.py - Config grafting
esmoe/graft.py - Block registry
esmoe/registry.py
MoE runtime
- ESMoE block
esmoe/module.py - Aux loss collection
esmoe/aux_loss.py
Training
- DDP trainer
esmoe/trainer.py - Upstream recipe
esmoe/upstream.py
Research runs
- Protocol training
scripts/train.py - Recipe parity
scripts/recipe_parity.py - Same-config runs
scripts/same_config.py - Run verification
scripts/verify.py
Result analysis
- Routing analysis
scripts/routing.py - Metric reporting
scripts/report.py - Charts
scripts/charts.py - Result backfill
scripts/backfill.py - Demo export
scripts/demo_export.py
Other components
- Engineer
- Ultralytics YOLO
Connections 26
- Engineer → Public API and CLI: calls
README.md - Public API and CLI → Register and equip: exposes
esmoe/__init__.py - Public API and CLI → Config grafting: exposes
esmoe/__init__.py - Register and equip → Config grafting: grafts config
esmoe/inject.py - Register and equip → Ultralytics YOLO: builds model
esmoe/inject.py - Register and equip → DDP trainer: routes trainer
esmoe/inject.py - Config grafting → Ultralytics YOLO: loads config
esmoe/graft.py - Ultralytics YOLO → ESMoE block: builds block
README.md - ESMoE block → Block registry: publishes loss
esmoe/module.py - Aux loss collection → Block registry: reads losses
esmoe/aux_loss.py - Aux loss collection → ESMoE block: walks blocks
esmoe/aux_loss.py - Register and equip → Aux loss collection: adds router loss
README.md - DDP trainer → Register and equip: arms workers
esmoe/trainer.py - DDP trainer → Upstream recipe: adjusts optimizer
esmoe/trainer.py - Engineer → Protocol training: runs protocol
README.md - Protocol training → Public API and CLI: uses package
scripts/train.py - Recipe parity → Public API and CLI: uses package
scripts/recipe_parity.py - Same-config runs → Metric reporting: reads metrics
scripts/same_config.py - Run verification → Public API and CLI: uses package
scripts/verify.py - Routing analysis → Public API and CLI: loads model
scripts/routing.py - Routing analysis → Metric reporting: compares runs
scripts/routing.py - Charts → Metric reporting: reads aggregates
scripts/charts.py - Charts → Same-config runs: reads comparisons
scripts/charts.py - Result backfill → Metric reporting: uses reporting
scripts/backfill.py - Demo export → Recipe parity: uses parity data
scripts/demo_export.py - Demo export → Public API and CLI: uses package
scripts/demo_export.py