From 9f44e2f93537a02575e2ffbffa42ba5947fa1cbc Mon Sep 17 00:00:00 2001 From: Kristopher Clark Date: Sat, 25 Jul 2026 11:21:16 -0500 Subject: [PATCH] [XPU] Prefer MXFP8 MoE XPU backend; forward softcap/ALIBI Mirror FP8's XPU-first oracle selection for MXFP8, forward softcap and alibi_slopes into vllm-xpu-kernels so unimplemented features raise, and document fail-closed attention / native MoE escape hatches. Co-authored-by: Cursor Agent Signed-off-by: Kristopher Clark --- .../installation/gpu.xpu.inc.md | 22 +++++++++++++++++++ vllm/_xpu_ops.py | 6 +++-- vllm/envs.py | 9 ++++++++ .../layers/fused_moe/oracle/mxfp8.py | 9 +++++++- 4 files changed, 43 insertions(+), 3 deletions(-) diff --git a/docs/getting_started/installation/gpu.xpu.inc.md b/docs/getting_started/installation/gpu.xpu.inc.md index e4c1aec71c4e..1c723037d21d 100644 --- a/docs/getting_started/installation/gpu.xpu.inc.md +++ b/docs/getting_started/installation/gpu.xpu.inc.md @@ -12,6 +12,28 @@ vLLM initially supports basic model inference and serving on Intel GPU platform. !!! warning The provided vllm-xpu-kernels whl is Python3.12 specific so this version is a MUST. +!!! note "XPU kernels runtime notes" + Install `vllm_xpu_kernels` from `requirements/xpu.txt` (release wheel by + default). Rebuild or reinstall that package when you change kernel configs. + + Runtime notes (enforced by the kernels package): + + - **Attention fail-closed (default):** missing FA2 / paged-decode AOT + shapes raise instead of silently falling back to a slow PyTorch + reference path. For eager debug only: + `export VLLM_XPU_ATTN_ALLOW_FALLBACK=1` (ignored under XPUGraph + capture). Softcap and ALiBi are not implemented on XPU FA2 and raise + when requested. + - **Page size 128:** default decode presets may include pagesize=128 + shapes. Serve with `--block-size 128` to use them; otherwise keep the + usual page-64 path. + - **Native MXFP8 / block-FP8 MoE (Xe2):** fused MoE uses the native + grouped-GEMM path by default. Escape hatches: + `VLLM_XPU_FUSED_MOE_NATIVE_MXFP8=0`, + `VLLM_XPU_FUSED_MOE_NATIVE_BLOCK_FP8=0`, or + `VLLM_XPU_FUSED_MOE_USE_REF=1` (force the Python reference expert + loop for A/B). + --8<-- [end:requirements] --8<-- [start:set-up-using-python] diff --git a/vllm/_xpu_ops.py b/vllm/_xpu_ops.py index 4cdba1e745ba..4eef9fb57e5f 100644 --- a/vllm/_xpu_ops.py +++ b/vllm/_xpu_ops.py @@ -976,6 +976,8 @@ def flash_attn_varlen_func( assert len(window_size) == 2 real_window_size = (window_size[0], window_size[1]) # noqa: F841 + # Forward softcap/alibi so the kernels package can fail closed when + # those features are requested but not implemented on XPU. return flash_attn_varlen_func( out=out, q=q, @@ -991,8 +993,8 @@ def flash_attn_varlen_func( block_table=block_table, s_aux=s_aux, window_size=real_window_size, - # alibi_slopes = alibi_slopes, - # softcap=softcap, + alibi_slopes=alibi_slopes, + softcap=softcap if softcap is not None else 0.0, return_softmax_lse=return_softmax_lse, q_descale=q_descale, k_descale=k_descale, diff --git a/vllm/envs.py b/vllm/envs.py index fb54619c7485..cfe766946d02 100755 --- a/vllm/envs.py +++ b/vllm/envs.py @@ -292,6 +292,9 @@ VLLM_NIXL_EP_MAX_NUM_RANKS: int = 32 VLLM_XPU_ENABLE_XPU_GRAPH: bool = False VLLM_XPU_USE_SAMPLER_KERNEL: bool = True + # Opt into slow PyTorch attention when an XPU FA2 shape is missing. + # Default (unset/0) is fail-closed in vllm-xpu-kernels. + VLLM_XPU_ATTN_ALLOW_FALLBACK: bool = False VLLM_LORA_ENABLE_DUAL_STREAM: bool = False VLLM_GPU_NIC_PCIE_MAPPING: str = "" VLLM_NIC_SELECTION_VARS: str = "" @@ -2000,6 +2003,12 @@ def _resolve_rust_frontend_path() -> str | None: "VLLM_XPU_USE_SAMPLER_KERNEL": lambda: bool( int(os.getenv("VLLM_XPU_USE_SAMPLER_KERNEL", "1")) ), + # Opt into PyTorch reference attention when an XPU FA2 AOT shape is + # missing. Default is fail-closed (raise). Eager debug only; ignored + # under XPUGraph capture. Read by vllm-xpu-kernels at runtime. + "VLLM_XPU_ATTN_ALLOW_FALLBACK": lambda: bool( + int(os.getenv("VLLM_XPU_ATTN_ALLOW_FALLBACK", "0")) + ), # Enable simple KV offload. "VLLM_USE_SIMPLE_KV_OFFLOAD": lambda: bool( int(os.getenv("VLLM_USE_SIMPLE_KV_OFFLOAD", "0")) diff --git a/vllm/model_executor/layers/fused_moe/oracle/mxfp8.py b/vllm/model_executor/layers/fused_moe/oracle/mxfp8.py index b9086cfa48aa..6d05198a0f22 100644 --- a/vllm/model_executor/layers/fused_moe/oracle/mxfp8.py +++ b/vllm/model_executor/layers/fused_moe/oracle/mxfp8.py @@ -158,8 +158,15 @@ def select_mxfp8_moe_backend( ) return backend, _select_kernel_cls(backend, config) + # Prefer XPU on Intel GPU before trying CUDA/ROCm backends. + backends = _SUPPORTED_BACKENDS + if current_platform.is_xpu(): + backends = (Fp8MoeBackend.XPU,) + tuple( + b for b in _SUPPORTED_BACKENDS if b != Fp8MoeBackend.XPU + ) + # Auto-select: pick the first supported backend. - for backend in _SUPPORTED_BACKENDS: + for backend in backends: try: experts_cls = _select_kernel_cls(backend, config) except ValueError: