Repository navigation
perf(moe): wire phimoe to the fused decode-MoE kernel - #312
Merged
Merged
Conversation
Migrate PhiMoE's local SwitchLinear and SwitchGLU to the shared implementations in switch_layers.rs and add the single-token fused dispatch.
The local SwitchLinear enum (Quantized/Regular variants with gather_qmm/gather_mm dispatch) and the local SwitchGLU struct (with gather_sort/scatter_unsort helpers) are removed from phimoe.rs. SparseMoeBlock.experts now carries crate::models::switch_layers::SwitchGLU, loaded via SwitchGLU::from_weights(weights, prefix+".switch_mlp", group_size, bits) -- the same prefix the old local call used.
sanitize_weights is left entirely intact: it still handles the unstacked experts.{i}.w1/w2/w3 layout from community checkpoints and stacks them into block_sparse_moe.switch_mlp.{gate,up,down}_proj.*. Pre-stacked checkpoints (already in the target shape, as verified on mlx-community/Phi-3.5-MoE-instruct-4bit) pass through unchanged.
SparseMoeBlock::forward gains the same fused dispatch pattern used by qwen3_moe, gemma4, and lfm2: when the token count is 1 and MLXCEL_FUSED_MOE is not disabled, forward_fused_kernel is called and the [hidden_dim] result is reshaped to [1, hidden_dim] before the block reassembly; the gather_qmm+moe_weighted_sum path is the fallback.
Docs: phimoe moved from the not-yet-wired list to Models covered in fused-moe-decode-kernel-design.md; count updated from seven to eight.
Tests: phimoe_tests.rs added with four config-parsing tests covering the 4-bit checkpoint layout, head_dim derivation, num_kv_heads accessor, and unquantized defaults. Registered in models/mod.rs.
Member
Author
|
Rebased onto main to pick up the Dff guard (#311). phi-3.5-moe's expert intermediate is 6400, above the default |
inureyes
force-pushed
the
perf/issue-303-phimoe-fused-kernel
branch
from
June 16, 2026 13:51
e498e4a to
cf068df
Compare
This was referenced Jun 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
SwitchLinear/SwitchGLU(plusgather_sort/scatter_unsorthelpers) and retypesSparseMoeBlock.expertsto the sharedcrate::models::switch_layers::SwitchGLU.SparseMoeBlock::forward, matching the pattern used by qwen3_moe, gemma4, and lfm2.sanitize_weightsintact so unstackedexperts.{i}.w1/w2/w3community checkpoints still stack correctly.What changed
src/models/phimoe.rs: removed ~190 lines of localSwitchLinear/SwitchGLU; retypesexpertsfield; updatesSparseMoeBlock::from_weightsto call sharedSwitchGLU::from_weights(weights, prefix+".switch_mlp", args.group_size(), args.bits()); adds fused dispatch block inSparseMoeBlock::forward.src/models/phimoe_tests.rs: new file with four config-parsing tests (4-bit checkpoint, head_dim, num_kv_heads, unquantized defaults).src/models/mod.rs: registersphimoe_tests.docs/benchmark_results/fused-moe-decode-kernel-design.md: moves phimoe to the wired models list; count seven -> eight.Weight-loading parity note
Pre-stacked checkpoints (
mlx-community/Phi-3.5-MoE-instruct-4bit) have weights underblock_sparse_moe.switch_mlp.{gate,up,down}_proj.{weight,scales,biases}. The sharedSwitchGLU::from_weightsreads exactly those keys when called with prefix{layer}.block_sparse_moe.switch_mlp, so loading is identical to the old local implementation. Thesanitize_weightsstacking path for unstacked community checkpoints is untouched.Test plan
cargo check --lib --tests --features metal,acceleratepassescargo clippy --lib --tests --features metal,accelerate -- -D warningspasses (zero warnings)mlx-community/Phi-3.5-MoE-instruct-4bitpending orchestrator (part of epic epic(moe): wire the remaining unwired MoE families to the fused decode-MoE kernel #307)Closes #303