Issue Station
Sign In
Tools hereToolbox

vllm - ✅(Solved) Fix [Feature]: Unify MoE "Oracles" with Class Structure [1 pull requests, 5 comments, 4 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
vllm-project/vllm#37753•Fetched 2026-04-08 01:13:05
View on GitHub
Comments
5
Participants
4
Timeline
15
Reactions
0
Author
robertgshaw2-redhatrobertgshaw2-redhat
Participants
bzubsbzubsrobertgshaw2-redhatrobertgshaw2-redhatWaknisWaknisZijun9Zijun9
Assignees
Zijun9Zijun9
Timeline (top)
commented ×5labeled ×3referenced ×2assigned ×1

Fix Action

Fixed

PR fix notes

PR #37776: [MoE] Unify MoE oracles with class structure

Description (problem / solution / changelog)

Purpose

Resolves #37753.

Introduces MoEKernelOracle(ABC, Generic[BackendT]) as a base class for all MoE kernel selection oracles. Each oracle (FP8, NvFP4, MXFP4, MXFP8, Unquantized) now inherits from this base class, standardizing the 4 core operations:

  • select_backend – choose the best kernel backend
  • convert_to_kernel_format – shuffle weights for a backend
  • make_quant_config – build a FusedMoEQuantConfig
  • make_kernel – construct the FusedMoEKernel

Plus 2 shared helper methods (backend_to_kernel_cls, map_backend) as abstract methods.

Key design decisions:

  • Module-level wrapper functions are preserved for full backward compatibility — zero changes required from external callers.
  • Method signatures intentionally vary across subclasses (different quant types need different weight/scale parameters), documented in base class docstring.
  • Optional methods (convert_to_kernel_format, make_quant_config, make_kernel) default to NotImplementedError for oracles that delegate (e.g. MXFP8 reuses FP8's kernel logic).

Additional fixes:

  • Fixed class methods calling module-level wrapper functions instead of self.method() in fp8, nvfp4, mxfp4.
  • Fixed map_backend type annotation inconsistency (str → MoEBackend) in mxfp8 and mxfp4.
  • Fixed potential UnboundLocalError in unquantized.py select_backend (changed if/if chain to if/elif with else fallback).
  • Fixed missing else branch in unquantized.py make_kernel.
  • Renamed private _select_kernel_cls to select_kernel_cls in mxfp8.
  • Exported MoEKernelOracle from oracle/__init__.py.

Test Plan

pytest tests/kernels/moe/test_oracle_class_structure.py -v -s
pytest tests/kernels/moe/test_unquantized_backend_selection.py -v -s

Test Result

tests/kernels/moe/test_oracle_class_structure.py: 20 passed
tests/kernels/moe/test_unquantized_backend_selection.py: 8 passed
Total: 28 passed, 0 failed
<details> <summary> Essential Elements of an Effective PR Description Checklist </summary>
  • The purpose of the PR, such as "Fix some issue (link existing issues this PR will resolve)".
  • The test plan, such as providing test command.
  • The test results, such as pasting the results comparison before and after, or e2e results
  • (Optional) The necessary documentation update, such as updating supported_models.md and examples for a new model.
  • (Optional) Release notes update. If your change is user facing, please update the release notes draft in the Google Doc.
</details>

Changed files

  • tests/kernels/moe/test_oracle_class_structure.py (added, +113/-0)
  • vllm/model_executor/layers/fused_moe/oracle/__init__.py (modified, +4/-0)
  • vllm/model_executor/layers/fused_moe/oracle/base.py (added, +86/-0)
  • vllm/model_executor/layers/fused_moe/oracle/fp8.py (modified, +503/-390)
  • vllm/model_executor/layers/fused_moe/oracle/mxfp4.py (modified, +763/-647)
  • vllm/model_executor/layers/fused_moe/oracle/mxfp8.py (modified, +89/-45)
  • vllm/model_executor/layers/fused_moe/oracle/nvfp4.py (modified, +388/-282)
  • vllm/model_executor/layers/fused_moe/oracle/unquantized.py (modified, +271/-183)

Code Example

class MoEKernelOracle(ABC)
 ...

class Fp8MoEKernelOracle(MoEOracle):
 ...
RAW_BUFFERClick to expand / collapse

🚀 The feature, motivation and pitch

We currently have the following MoE "oracles", which select the right MoE kernel for each model

  • model_executor/layers/fused_moe/oracle

We have:

  • fp8
  • nvfp4
  • mxfp8
  • unquantized

and will soon have mxfp4

Each of these has the following functions:

  • select_XX_moe_backend - called by the quantization integration to get the backend
  • convert_to_XX_moe_kernel_format - called by the quantization integration to shuffle the weights
  • make_XX_moe_quant_config - called by the quantization integration to make the quant config
  • make_fp8_moe_kernel - called by the quantization integration to construct the kernel

Now that we have the structure standardized, we need to create a generic class that implements this logic. Then, each oracle can inherit from this.

So, we would have the following:

class MoEKernelOracle(ABC)
 ...

class Fp8MoEKernelOracle(MoEOracle):
 ...

and so on and so forth

Alternatives

just use conventions. this is a bad idea due to drift and duplicated code

Additional context

No response

Before submitting a new issue...

  • Make sure you already searched for relevant issues, and asked the chatbot living at the bottom right corner of the documentation page, which can answer lots of frequently asked questions.

extent analysis

Fix Plan

To create a generic class for the MoE kernel oracles, we will:

  • Define an abstract base class MoEKernelOracle with abstract methods for the common functions
  • Create concrete subclasses for each oracle type (e.g. Fp8MoEKernelOracle, Nvfp4MoEKernelOracle, etc.)

Example Code

from abc import ABC, abstractmethod

class MoEKernelOracle(ABC):
    @abstractmethod
    def select_moe_backend(self):
        pass

    @abstractmethod
    def convert_to_moe_kernel_format(self):
        pass

    @abstractmethod
    def make_moe_quant_config(self):
        pass

    @abstractmethod
    def make_moe_kernel(self):
        pass

class Fp8MoEKernelOracle(MoEKernelOracle):
    def select_moe_backend(self):
        # implementation for fp8
        return "fp8_backend"

    def convert_to_moe_kernel_format(self):
        # implementation for fp8
        return "fp8_kernel_format"

    def make_moe_quant_config(self):
        # implementation for fp8
        return "fp8_quant_config"

    def make_moe_kernel(self):
        # implementation for fp8
        return "fp8_moe_kernel"

class Nvfp4MoEKernelOracle(MoEKernelOracle):
    def select_moe_backend(self):
        # implementation for nvfp4
        return "nvfp4_backend"

    def convert_to_moe_kernel_format(self):
        # implementation for nvfp4
        return "nvfp4_kernel_format"

    def make_moe_quant_config(self):
        # implementation for nvfp4
        return "nvfp4_quant_config"

    def make_moe_kernel(self):
        # implementation for nvfp4
        return "nvfp4_moe_kernel"

Verification

To verify that the fix worked, create instances of each oracle subclass and call the methods to ensure they return the expected results.

Extra Tips

  • Use a consistent naming convention for the oracle subclasses and their methods.
  • Consider adding a registry or factory function to create instances of the oracle subclasses based on a given type or configuration.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#parallel task#integration issue#index setup#retrieval issue#search optimization

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

vllm - ✅(Solved) Fix [Feature]: Unify MoE "Oracles" with Class Structure [1 pull requests, 5 comments, 4 participants]