# PR #48677 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[XPU] upgrade to torch 2.13
- 合并时间：2026-07-29 16:24
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/48677

---

# 执行摘要

- 一句话：XPU 平台 PyTorch 升级至 2.13 及内核包更新
- 推荐动作：该 PR 值得阅读，尤其是 `vllm/_custom_ops.py` 中的 workaround 清理和 Dockerfile 的简化做法，展示了平台升级时应同步清理技术债务的良好工程实践。对于 XPU 开发者，需要关注新的 oneAPI 2026.0 基础镜像和 PyTorch 2.13 的兼容性问题。建议在合并后密切监控 XPU 相关 CI 测试结果。

# 功能与动机

PR body 明确说明升级目的："This PR upgrades to torch 2.13 on XPU platform and bump up v0.1.12 vllm-xpu-kernels."。此外，Issue 评论中 krisclarkdev 指出 "Full-graph FlashAttention capture needs torch.version.xpu >= 20260000 (oneAPI 2026 / torch 2.13)"，表明升级是后续 XPU 图捕获特性的必要前置条件。

# 实现拆解

1. **升级 PyTorch 与核心依赖**：修改 `requirements/xpu.txt`，将 torch 从 2.12.0 升至 2.13.0，auto_round_lib 升至 0.14.2，vllm_xpu_kernels 指向 v0.1.12 的 wheel 地址。同步更新 `requirements/test/xpu.txt` 中所有 Intel 相关包至 2026.0 系列版本。
2. **清理 MoE 路由 workaround**：在 `vllm/_custom_ops.py` 中删除 `topk_softmax` 和 `topk_hash_softplus_sqrt` 函数中的 XPU 特殊分支（该分支曾跳过 `is_padding` 参数）。新版 vllm-xpu-kernels v0.1.12 已支持 `is_padding`，因此可以统一调用同一接口。
3. **简化 Docker 构建流程**：`docker/Dockerfile.xpu` 不再通过 apt 添加 oneAPI 仓库并固定 2025.3 版本，而是直接 `FROM intel/hpux:oneapi-2026.0`，移除了手动下载 oneCCL 等中间步骤，简化了层次并减少了镜像体积。同时更新 `LD_LIBRARY_PATH` 等环境变量以匹配新基础镜像。
4. **调整构建配置与 CI 脚本**：`setup.py` 添加 `if not _is_xpu()` 条件，使 XPU 平台跳过 `spinloop` 和 `fs_io_C` 两个 C 扩展的编译（这些扩展在 XPU 上无用但曾导致编译错误）。`.buildkite/scripts/hardware_ci/run-intel-test.sh` 中删除了容器运行时对 `source /opt/intel/oneapi/setvars.sh` 的调用（镜像已内建）。
5. **更新文档**：`docs/getting_started/installation/gpu.xpu.inc.md` 中更新了版本号提示。

关键文件：
- `vllm/_custom_ops.py`（模块 自定义算子；类别 source；类型 core-logic；符号 topk_softmax, topk_hash_softplus_sqrt）: 核心逻辑变更：删除 XPU 特殊分支，统一 MoE 路由函数中的 is_padding 参数处理，依赖新版内核支持。
- `setup.py`（模块 构建配置；类别 source；类型 core-logic）: 构建配置变更：为 XPU 平台排除 spinloop 和 fs_io_C 扩展，避免编译错误。
- `docker/Dockerfile.xpu`（模块 Docker 构建；类别 infra；类型 infrastructure）: 基础设施核心变更：从手动安装 oneAPI 2025.3 改为使用 Intel 官方 oneAPI 2026.0 基础镜像，大幅简化 Dockerfile。
- `requirements/xpu.txt`（模块 依赖配置；类别 docs；类型 documentation）: 核心依赖升级：torch 2.13.0，auto_round_lib 0.14.2，vllm_xpu_kernels 0.1.12。
- `requirements/test/xpu.txt`（模块 测试依赖；类别 docs；类型 documentation）: 测试依赖同步升级：所有 Intel 组件升至 2026.0 系列，triton-xpu 3.7.2。
- `.buildkite/scripts/hardware_ci/run-intel-test.sh`（模块 CI 脚本；类别 infra；类型 infrastructure）: CI 脚本适应新镜像：移除 source setvars.sh 命令。
- `docs/getting_started/installation/gpu.xpu.inc.md`（模块 文档；类别 docs；类型 documentation）: 文档同步更新版本信息。

关键符号：topk_softmax, topk_hash_softplus_sqrt

## 关键源码片段

### `vllm/_custom_ops.py`

核心逻辑变更：删除 XPU 特殊分支，统一 MoE 路由函数中的 is_padding 参数处理，依赖新版内核支持。

```python
def topk_softmax(
    topk_weights: torch.Tensor,
    topk_ids: torch.Tensor,
    token_expert_indices: torch.Tensor,
    gating_output: torch.Tensor,
    renormalize: bool = False,
    e_score_correction_bias: torch.Tensor | None = None,
    is_padding: torch.Tensor | None = None,
) -> None:
    # 之前 XPU 平台因内核 v0.1.11 不支持 is_padding，需要特殊分支跳过该参数。
    # 升级到 v0.1.12 后统一调用带 is_padding 的接口。
    torch.ops._moe_C.topk_softmax(
        topk_weights,
        topk_ids,
        token_expert_indices,
        gating_output,
        renormalize,
        e_score_correction_bias,
        is_padding,
    )


def topk_hash_softplus_sqrt(
    topk_weights: torch.Tensor,
    topk_indices: torch.Tensor,
    token_expert_indices: torch.Tensor,
    gating_output: torch.Tensor,
    renormalize: bool = False,
    routed_scaling_factor: float = 1.0,
    e_score_correction_bias: torch.Tensor | None = None,
    input_tokens: torch.Tensor | None = None,
    hash_indices_table: torch.Tensor | None = None,
    is_padding: torch.Tensor | None = None,
) -> None:
    # 同理，移除了 XPU 分支，直接传递 is_padding。
    torch.ops._moe_C.topk_softplus_sqrt(
        topk_weights,
        topk_indices,
        token_expert_indices,
        gating_output,
        renormalize,
        routed_scaling_factor,
        e_score_correction_bias,
        input_tokens,
        hash_indices_table,
        is_padding,
    )

```

### `docker/Dockerfile.xpu`

基础设施核心变更：从手动安装 oneAPI 2025.3 改为使用 Intel 官方 oneAPI 2026.0 基础镜像，大幅简化 Dockerfile。

```dockerfile
# 不再手动添加 oneAPI 仓库和安装 2025.3 固定版本
# 直接使用官方 oneAPI 2026.0 基础镜像
# 之前需要多层：apt-key，deb repo，pin 版本，apt install
# 现在只需 FROM 即可
FROM intel/hpux:oneapi-2026.0 AS base
# 其他步骤保持不变，LD_LIBRARY_PATH 也简化为系统默认路径
ENV LD_LIBRARY_PATH=/opt/venv/lib:/usr/local/lib

```

# 评论区精华

**安全风险讨论**：depthfirst-app[bot] 指出 Docker 构建移除了 GPG 签名验证（之前通过 `signed-by=` 和 `wget -O-` 加 `gpg --dearmor`），建议添加 SHA256 校验。jikunshang 回应认为不应安装某些东西（可能指 oneAPI 组件），可能需要从源码安装 umf。该讨论未完全解决，但 Docker 构建已简化，安全风险由基础镜像承担。

**编码风格确认**：review 最终由 jikunshang 批准，未出现重大争议。

- Docker 构建安全风险 (security): 未明确解决，但 jikunshang 认为不应安装某些组件，后续可能改为源码编译 umf。当前设计信任基础镜像的安全性。
- oneAPI 组件安装方式 (question): 该讨论未在此 PR 中完全解决，但从删除的代码看，团队决定完全依赖基础镜像。

# 风险与影响

- 风险：
 1. **供应链安全风险**：Dockerfile 移除了手动添加 oneAPI 仓库和 GPG 签名验证，改为依赖 `intel/hpux:oneapi-2026.0` 基础镜像。若镜像被篡改或官方仓库被攻破，构建过程可能引入恶意代码。需确保镜像来源可信并定期更新。
 2. **内核兼容性回归**：vllm-xpu-kernels v0.1.12 改动较大（统一 `is_padding` 接口），如果 XPU 平台上的 MoE 路由出现异常，可能影响模型推理正确性。该 PR 未增加测试覆盖，回归风险需依赖 CI 暴露。
 3. **环境变量路径变更**：`LD_LIBRARY_PATH` 从手动指定多个 oneAPI 路径改为 `/opt/venv/lib:/usr/local/lib`，若某些原生库（如 oneCCL）未在标准路径，可能导致运行时链接失败。CI 脚本中也移除了 `source setvars.sh`，可能影响依赖环境变量的子进程。
 4. **编译排除风险**：`setup.py` 中为 XPU 排除 `spinloop` 和 `fs_io_C`，若未来这些扩展在 XPU 上变得必要，会遗漏编译。当前阶段是安全的。
 - 影响：**用户影响**：仅影响 XPU（Intel GPU）平台的用户。升级后需要拉取新 Docker 镜像或重新安装 PyTorch 2.13 及配套内核包。旧的 oneAPI 2025.3 环境不再兼容，用户需迁移至 oneAPI 2026.0。

**系统影响**：Docker 构建流程简化，镜像层数减少，构建更快。但移除了之前固定在 2025.3 版本的 oneAPI 组件，新版本 2026.0 可能引入 API 变更，需在测试中验证兼容性。

**团队维护影响**：清理了 `_custom_ops.py` 中的 XPU workaround，代码更清晰，后续维护更简单。CI 脚本简化，不再依赖手动环境变量加载。

- 风险标记：依赖供应链风险 , Docker 构建简化削弱安全验证 , 新内核兼容性回归 , 运行时路径变更可能影响链接

# 关联脉络

- PR #50038 [XPU] FA-in-graph / XPU graphs (placeholder): krisclarkdev 在 Issue 评论中指出 #50038 需要 torch 2.13 作为依赖，本 PR 为其前置条件。
- PR #49813 [XPU] softcap/MXFP8 support: 同为 XPU 特性 PR，krisclarkdev 提到生产环境 FA-in-graph 需要此 PR。