Skip to content

vllm.model_executor.models.qwen3_moe

Inference-only Qwen3MoE model compatible with HuggingFace weights.

_build_expert_mapping 

_build_expert_mapping(
    model: Module,
    num_experts: int,
    num_redundant_experts: int,
) -> list[tuple[str, str, int, str]]

Return the expert weight mapping consumed by FusedMoE.load_weights.

Combines the per-expert mapping (experts..{gate_proj,up_proj,down_proj}) with three aliases for HF's fused-MoE checkpoint layout (transformers

= v5, and any v4 checkpoint re-saved with save_original_format=False): experts.gate_up_proj of shape (E, 2*I, H) and experts.down_proj of shape (E, H, I). For the fused aliases expert_id is repurposed as shard_idx (0=gate, 1=up) by FusedMoE.load_weights' dim()==3 branch. See vllm/model_executor/models/transformers/moe.py for the same pattern.

Source code in vllm/model_executor/models/qwen3_moe.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
def _build_expert_mapping(
    model: nn.Module,
    num_experts: int,
    num_redundant_experts: int,
) -> list[tuple[str, str, int, str]]:
    """Return the expert weight mapping consumed by FusedMoE.load_weights.

    Combines the per-expert mapping (experts.<i>.{gate_proj,up_proj,down_proj})
    with three aliases for HF's fused-MoE checkpoint layout (transformers
    >= v5, and any v4 checkpoint re-saved with save_original_format=False):
    experts.gate_up_proj of shape (E, 2*I, H) and experts.down_proj of
    shape (E, H, I). For the fused aliases expert_id is repurposed as
    shard_idx (0=gate, 1=up) by FusedMoE.load_weights' dim()==3 branch.
    See vllm/model_executor/models/transformers/moe.py for the same
    pattern.
    """
    per_expert_mapping = fused_moe_make_expert_params_mapping(
        model,
        ckpt_gate_proj_name="gate_proj",
        ckpt_down_proj_name="down_proj",
        ckpt_up_proj_name="up_proj",
        num_experts=num_experts,
        num_redundant_experts=num_redundant_experts,
    )
    fused_mapping = [
        ("experts.w13_weight", "experts.gate_up_proj", 0, "w1"),
        ("experts.w13_weight", "experts.gate_up_proj", 1, "w3"),
        ("experts.w2_weight", "experts.down_proj", 0, "w2"),
    ]
    return per_expert_mapping + fused_mapping