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

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

测试 PyTorch 发布候选版（RC）¶

在 PyTorch 正式发布后才更新 vLLM 中的 PyTorch 并非理想选择，因为届时发现的任何问题只能通过等待下一个版本发布或在 vLLM 中实现临时的变通方法来解决。更好的解决方案是测试 vLLM 与 PyTorch 发布候选版（RC）的兼容性，以确保在每次发布前都兼容。

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 dev-discuss 论坛上向社区发布。在此公告后，我们可以通过遵循以下 3 步流程起草一个 pull request 来开始测试 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
```

如果在 pull request 中发现失败，请在 vLLM 上将其作为 issue 提出，并抄送 PyTorch 发布团队，以启动关于如何解决这些问题的讨论。

更新 CUDA 版本¶

PyTorch 发布矩阵包含稳定版和实验版 CUDA 版本。由于限制，只有最新的稳定 CUDA 版本（例如，torch 2.7.1+cu126）会上传到 PyPI。但是，vLLM 可能需要不同的 CUDA 版本，例如 12.8 以支持 Blackwell。这使得过程变得复杂，因为我们无法使用开箱即用的 pip install torch torchvision torchaudio 命令。解决方案是在 vLLM 的 Dockerfiles 中使用 --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 平台¶

与其试图在一个 pull request 中更新所有 vLLM 平台，不如单独处理某些平台更容易管理。vLLM CI/CD 中不同平台的需求和 Dockerfiles 的分离，允许我们选择性地更新哪些平台。例如，更新 XPU 需要 Intel Extension for PyTorch 来自 Intel 的相应发布。虽然 Pull Request #16859 在 CPU、CUDA 和 ROCm 上将 vLLM 更新到 PyTorch 2.7.0， Pull Request #17444 完成了 XPU 的更新。