更新 vLLM OSS CI/CD 上的 PyTorch 版本¶

vLLM 当前的策略是在 CI/CD 中始终使用最新的 PyTorch 稳定版。当新的 PyTorch 稳定版发布时，尽早提交 PR 以更新 PyTorch 版本是标准做法。由于 PyTorch 各版本之间存在差异，此过程并非易事。以 Pull Request #16859 为例，本文档概述了实现此更新的常见步骤，以及可能出现的问题列表及其解决方法。

测试 PyTorch 发布候选版本 (RCs)¶

在正式发布后才在 vLLM 中更新 PyTorch 并不理想，因为届时发现的任何问题只能通过等待下一个版本或在 vLLM 中实施临时的权宜之计来解决。更好的解决方案是在每个版本发布之前，使用 PyTorch 发布候选版本 (RC) 对 vLLM 进行测试，以确保兼容性。

PyTorch 发布候选版本可以从 PyTorch 测试索引下载。例如，torch2.7.0+cu12.8 RC 可以使用以下命令安装：

uv pip install torch torchvision torchaudio \
    --index-url https://download.pytorch.org/whl/test/cu128

当最终的 RC 准备好进行测试时，会通过 PyTorch 开发讨论论坛向社区发布公告。在此公告发布后，我们可以通过遵循以下 3 个步骤起草拉取请求来开始测试 vLLM 集成：

更新 requirements 文件，使其指向 torch、torchvision 和 torchaudio 的新版本。
使用以下选项获取最终的发布候选版 wheel 包。一些常见平台包括 cpu、cu128 和 rocm6.2.4。
```
--extra-index-url https://download.pytorch.org/whl/test/<PLATFORM>
```
由于 vLLM 使用 uv，请确保应用以下索引策略：
- 通过环境变量：
```
export UV_INDEX_STRATEGY=unsafe-best-match
```
- 或者通过 CLI 标志：
```
--index-strategy unsafe-best-match
```

如果在拉取请求中发现失败，请在 vLLM 上提出 issue，并抄送 PyTorch 发布团队以发起关于如何解决这些问题的讨论。

更新 CUDA 版本¶

PyTorch 发布矩阵包括稳定版和实验版 CUDA 版本。受限于相关限制，只有最新的稳定 CUDA 版本（例如 torch 2.7.1+cu126）会被上传到 PyPI。然而，vLLM 可能需要不同的 CUDA 版本，例如用于支持 Blackwell 的 12.8。这使得流程变得复杂，因为我们无法直接使用开箱即用的 pip install torch torchvision torchaudio 命令。解决方案是在 vLLM 的 Dockerfile 中使用 --extra-index-url。

目前重要的索引包括：

平台	`--extra-index-url`
CUDA 12.8	https://download.pytorch.org/whl/cu128
CPU	https://download.pytorch.org/whl/cpu
ROCm 6.2	https://download.pytorch.org/whl/rocm6.2.4
ROCm 6.3	https://download.pytorch.org/whl/rocm6.3
XPU	https://download.pytorch.org/whl/xpu

更新以下文件以匹配步骤 1 中的 CUDA 版本。这确保了发布的 vLLM wheel 在 CI 上得到测试。
- .buildkite/release-pipeline.yaml
- .buildkite/scripts/upload-wheels.sh

在 BuildKiteCI 上手动运行 vLLM 构建¶

当使用新的 PyTorch/CUDA 版本构建 vLLM 时，vLLM sccache S3 存储桶不会有任何缓存的产物，这可能导致 CI 构建作业超过 5 小时。此外，vLLM 的 fastcheck 流水线以只读模式运行，不会填充缓存，因此对于缓存预热而言是无效的。

为了解决这个问题，可以在 Buildkite 上手动触发构建，以实现两个目标：

通过设置环境变量 RUN_ALL=1 和 NIGHTLY=1，针对 PyTorch RC 构建运行完整的测试套件。
使用编译后的产物填充 vLLM sccache S3 存储桶，从而实现更快的后续构建。

更新所有不同的 vLLM 平台¶

与其尝试在单个拉取请求中更新所有 vLLM 平台，不如分开处理某些平台更易于管理。vLLM CI/CD 中针对不同平台的 requirements 和 Dockerfile 的分离，使我们能够有选择地更新平台。例如，更新 XPU 需要来自英特尔 Intel Extension for PyTorch 的相应版本。虽然 Pull Request #16859 将 vLLM 更新至 CPU、CUDA 和 ROCm 上的 PyTorch 2.7.0， Pull Request #17444 完成了 XPU 的更新。