执行摘要

• 一句话：补 XPU 版 forward_xpu，修复 HunyuanOCR 强制 eager 崩溃
• 推荐动作：建议精读。该 PR 虽小，但清晰展示了 vLLM CustomOp 按平台分发的机制（forward_native / forward_cuda / forward_xpu），以及平台适配时如何避免 fallback 到不兼容的通用 kernel。对理解 XPU 支持模式和平台相关 bug 排查有很高参考价值。阅读时可重点关注 CustomOp.dispatch_forward() 的路由逻辑与 mrope 在 XPU 上的既有处理对比。

功能与动机

PR body 明确指出：XDRotaryEmbedding（rope_type xdrope，用于 tencent/HunyuanOCR）覆写了 forward_native 和 forward_cuda，但没有覆写 forward_xpu。在 --enforce-eager 下 CustomOp.dispatch_forward() 会 fallback 到基类 RotaryEmbedding.forward_xpu，其调用通用 kernel torch.ops._C.rotary_embedding，期望一维 positions 与 q/k 的 num_tokens 对齐，遇到 xdrope 的 2-D [4, num_tokens] 分段位置时报 RuntimeError: query, key and positions must have the same batch_size and seq_len，导致模型在 XPU 上完全无法服务。

实现拆解

1. 定位问题根因：分析 CustomOp.dispatch_forward() 的分发逻辑，确认默认 torch.compile 路径（custom_ops=[]）走 forward_native 正常，而 --enforce-eager（custom_ops=['all']）走 forward_xpu，XDRotaryEmbedding 未覆写该方法时 fallback 到基类通用实现，与 xdrope 的 2-D 分段位置不兼容。

2. 新增 forward_xpu 方法：在 vllm/model_executor/layers/rotary_embedding/xdrope.py 的 XDRotaryEmbedding 类中新增 forward_xpu 方法，签名与基类保持一致（positions, query, key, offsets），方法体直接委托 forward_native。注释中说明 XPU 无 fused xdrope kernel，且基类通用 kernel 会拒绝 2-D 位置，并注明这是镜像 mrope 在 XPU 上的既有处理方式。

3. 验证修复效果：作者使用 vllm serve tencent/HunyuanOCR --enforce-eager 等命令实测，修复前 EngineCore 在 profile_run 崩溃，修复后 Application startup complete，/health 返回 200，/v1/models 正常列出模型。

4. 配套与测试情况：本次为单提交、单文件、12 行纯新增改动；无测试文件、配置或部署配套变更，未新增自动化测试用例，依赖人工验证覆盖 XPU 特定路径。

关键文件：

• vllm/model_executor/layers/rotary_embedding/xdrope.py（模块 旋转嵌入；类别 source；类型 core-logic；符号 forward_xpu）: 这是本次唯一的变更文件。XDRotaryEmbedding 此前只覆写 forward_native 与 forward_cuda，缺少 forward_xpu 导致 --enforce-eager 下 fallback 到基类通用 C++ kernel，因无法处理 2-D xdrope 位置而崩溃。新增的 forward_xpu 委托给 forward_native，是修复的核心。

关键符号：forward_xpu

关键源码片段

vllm/model_executor/layers/rotary_embedding/xdrope.py

这是本次唯一的变更文件。XDRotaryEmbedding 此前只覆写 forward_native 与 forward_cuda，缺少 forward_xpu 导致 --enforce-eager 下 fallback 到基类通用 C++ kernel，因无法处理 2-D xdrope 位置而崩溃。新增的 forward_xpu 委托给 forward_native，是修复的核心。

# 新增于 vllm/model_executor/layers/rotary_embedding/xdrope.py 的 XDRotaryEmbedding 类中。
# 该方法专门为 XPU 平台补齐 CustomOp 分发入口，避免 fallback 到基类通用 kernel。
def forward_xpu(
    self,
    positions: torch.Tensor,
    query: torch.Tensor,
    key: torch.Tensor | None = None,
    offsets: torch.Tensor | None = None,
) -> tuple[torch.Tensor, torch.Tensor | None]:
    # XPU 上没有针对 xdrope 分段位置（2-D [4, num_tokens]）的 fused kernel。
    # 基类 RotaryEmbedding.forward_xpu 会调用通用 C++ kernel torch.ops._C.rotary_embedding，
    # 该 kernel 期望 1-D positions 与 q/k 的 num_tokens 对齐；遇到 2-D 位置会抛
    # "query, key and positions must have the same batch_size and seq_len"，
    # 导致 --enforce-eager 模式下 profile_run 崩溃，模型无法启动。
    # 这里直接委托给 forward_native，与 mrope 在 XPU 上的处理方式保持一致。
    return self.forward_native(positions, query, key, offsets)

评论区精华

本 PR 的 review 过程没有出现实质技术争论：claude[bot] 因 PR 来自 fork 而自动禁用了代码审核；维护者 jikunshang 通过 /ci run 触发 Buildkite CI（#84204）后直接 approve。无未解决的疑虑，修复方案得到维护者认可后合并。

• 自动化审核与 CI 触发 (other): 无实质技术争论，修复方案被维护者认可并合并。

风险与影响

• 风险：主要风险点：

• 缺少自动化测试覆盖：该修复没有任何单元测试或集成测试配套，仅靠作者本地手动验证。回归风险点集中在 XPU + --enforce-eager + xdrope 位置张量的组合路径，后续如果 CustomOp 分发逻辑或基类 forward_xpu 实现变化，该问题可能复发。

• 性能回退风险：forward_xpu 委托到 forward_native 的 Python 路径，未使用任何融合 kernel。但 XPU 上原本就没有 xdrope 专用融合实现，mrope 也是同样处理，因此性能退化实际有限且可接受。

• 影响面限制：改动仅影响 XPU 平台且 --enforce-eager 开启的路径；默认 torch.compile 路径、NVIDIA/AMD 等平台完全不受影响。风险整体较低。

• 影响：对用户：XPU 用户可以正常以 --enforce-eager 服务 HunyuanOCR 系列模型，消除了此前引擎启动即崩溃的阻断性问题。对系统：改动局限于 XDRotaryEmbedding 类，不涉及调度、KV cache 等核心模块，默认路径零影响。对团队：为 Intel GPU / XPU 平台模型兼容性补齐了一块缺口，同时也为后续接入其他使用 xdrope 位置编码的模型提供了可参考的适配范式。
• 风险标记：缺少测试覆盖, 平台特定路径, 性能回退风险, 模型启动阻断修复

关联脉络

• 暂无明显关联 PR