vllm.model_executor.layers.fused_moe.oracle.base
¶
Abstract base class for MoE kernel oracles.
Classes:
-
MoEKernelOracle–Abstract base for MoE kernel-selection oracles.
Functions:
-
make_moe_kernel–Assemble a
FusedMoEKernelfrom a prepare/finalize and an experts part.
MoEKernelOracle
¶
Abstract base for MoE kernel-selection oracles.
Concrete oracles provide name and backend_to_kernel_cls today; the
remaining methods below are the #37753 migration target and are still
implemented per module, so they are declared but not enforced.
Methods:
-
backend_enum_cls–Return the concrete
Enumclass enumerating this oracle's -
backend_to_kernel_cls–Map a backend enum value to its concrete
FusedMoEExperts -
convert_to_kernel_format–Shuffle weights into the layout expected by
backend. -
get_priority_backends–Return platform-appropriate backends in priority order for
-
make_kernel–Construct the
FusedMoEKernel(Prepare/Finalize + Experts -
make_log_backend–Message for the backend a select loop settled on.
-
make_log_unsupported–Message for a backend that does not support the configuration.
-
make_quant_config–Build a
FusedMoEQuantConfigfor this oracle. -
map_backend–Map a user-facing
MoEBackend(from the runner config) to -
return_or_raise–Return
backendwith its first supported kernel class, or raise. -
select_backend–Primary entry point: choose the best supported backend for
-
try_backend–Probe
backend's candidate kernel classes, first supported wins.
Source code in vllm/model_executor/layers/fused_moe/oracle/base.py
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 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 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 | |
backend_enum_cls()
¶
Return the concrete Enum class enumerating this oracle's
backends (e.g. UnquantizedMoeBackend, Fp8MoeBackend).
backend_to_kernel_cls(backend)
¶
Map a backend enum value to its concrete FusedMoEExperts
subclasses, in selection priority order.
Implementations must forward to the module-level function at call time,
not alias it with = staticmethod(fn), which snapshots it at import.
Source code in vllm/model_executor/layers/fused_moe/oracle/base.py
convert_to_kernel_format(backend, moe_config, w13_weight, w2_weight)
¶
Shuffle weights into the layout expected by backend.
Default implementation returns the inputs unchanged. Oracles
whose backends need weight permutation should override this
(e.g. UnquantizedMoEKernelOracle handles AITER and FlashInfer
layouts).
moe_config carries MoE-layer state (e.g. is_act_and_mul)
that the conversion needs without coupling the oracle to a
Module reference. Quantized oracles whose conversion
additionally needs scales / zero-points / block shapes will
override with a wider signature (and ultimately a per-oracle
config object — tracked in the #37753 follow-up PRs).
Source code in vllm/model_executor/layers/fused_moe/oracle/base.py
get_priority_backends(moe_config)
¶
Return platform-appropriate backends in priority order for
this moe_config.
make_kernel(quant_config, moe_config, backend, experts_cls, routing_tables=None)
¶
Construct the FusedMoEKernel (Prepare/Finalize + Experts
combinator) for the chosen backend.
Source code in vllm/model_executor/layers/fused_moe/oracle/base.py
make_log_backend(backend, available_backends=None, is_lora=False)
¶
Message for the backend a select loop settled on.
Source code in vllm/model_executor/layers/fused_moe/oracle/base.py
make_log_unsupported(backend, reason, is_lora=False)
¶
Message for a backend that does not support the configuration.
Source code in vllm/model_executor/layers/fused_moe/oracle/base.py
make_quant_config(*args, **kwargs)
¶
Build a FusedMoEQuantConfig for this oracle.
Quantized oracles (fp8, nvfp4, mxfp4, ...) override this with the appropriate signature for their quantization scheme. Unquantized oracles inherit the default, which raises because there is no quantization-specific config to build.
Source code in vllm/model_executor/layers/fused_moe/oracle/base.py
map_backend(runner_backend)
¶
Map a user-facing MoEBackend (from the runner config) to
this oracle's enum.
return_or_raise(backend, available_backends=None, kernel_classes=None, activation_key=_UNSET, is_lora=False)
¶
Return backend with its first supported kernel class, or raise.
Raises:
-
ValueError–no candidate kernel class supports the deployment configuration; the message carries the last rejection reason.
Source code in vllm/model_executor/layers/fused_moe/oracle/base.py
select_backend(moe_config, weight_key=None, activation_key=None)
¶
Primary entry point: choose the best supported backend for
the given moe_config.
weight_key / activation_key carry the quantization scheme of
the weights and activations and are consumed by quantized oracles
(fp8, nvfp4, int8, ...) to disambiguate backends. The unquantized
oracle ignores them. Subclasses with additional selection inputs
(e.g. int_wna16 needs weight_bits, fp8 needs
allow_vllm_cutlass) widen the signature in their override; a
per-oracle config object is the longer-term target tracked in
the #37753 follow-up PRs.
Source code in vllm/model_executor/layers/fused_moe/oracle/base.py
try_backend(backend, kernel_classes=None, activation_key=_UNSET)
¶
Probe backend's candidate kernel classes, first supported wins.
A miss logs a DEBUG line and yields to the next candidate; whether that
is fatal stays with the caller. activation_key overrides this oracle's
own key for oracles whose activation key varies per backend.
Returns:
-
type[FusedMoEExperts] | None–(kernel_cls, rejected): the winning class, orNone, plus every -
list[Rejection]–(kernel_cls, reason)probed and rejected before it, in order, so -
tuple[type[FusedMoEExperts] | None, list[Rejection]]–that callers collecting reasons for a report keep one entry per
-
tuple[type[FusedMoEExperts] | None, list[Rejection]]–candidate rather than only the last.
Source code in vllm/model_executor/layers/fused_moe/oracle/base.py
make_moe_kernel(moe_quant_config, moe_config, experts_cls, routing_tables=None, prepare_finalize_kwargs=None, experts_kwargs=None, experts_log=None)
¶
Assemble a FusedMoEKernel from a prepare/finalize and an experts part.
This is the step every MoE oracle runs once its backend is chosen, so it lives here rather than being copy-pasted into each oracle module.
Parameters:
-
(moe_quant_config¶FusedMoEQuantConfig) –Quantization configuration of the layer.
-
(moe_config¶FusedMoEConfig) –MoE layer configuration.
-
(experts_cls¶type[FusedMoEExperts]) –Selected experts implementation.
-
(routing_tables¶tuple[Tensor, Tensor, Tensor] | None, default:None) –Optional pre-computed routing tables (EP).
-
(prepare_finalize_kwargs¶dict[str, Any] | None, default:None) –Extra kwargs for
maybe_make_prepare_finalize(e.g.input_dtype). -
(experts_kwargs¶dict[str, Any] | None, default:None) –Extra kwargs for the experts constructor (e.g. the W4A8
b_strides1/b_strides2/group_size). -
(experts_log¶str | None, default:None) –Optional
info_oncetemplate for the selected experts class, e.g."Using %s MoE backend".