# PR #48772 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[CI] Gate non-default release wheel builds
- 合并时间：2026-07-17 17:16
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/48772

---

# 执行摘要

- 一句话：限制自动构建 wheel 至 CUDA 13.0 x86_64/aarch64
- 推荐动作：此 PR 是 CI 基础设施的合理优化，值得关注其门控设计模式。建议阅读 `.buildkite/release-pipeline.yaml` 中的步骤重组，理解 Buildkite 的 block 和条件控制用法。对于维护 CI 的团队有参考价值。

# 功能与动机

常规 release-v2 构建在每次合并到 main 后构建所有 wheel 变体，消耗大量 CI 资源且多数变体并不常用。该 PR 默认只构建最常用的 CUDA 13.0 变体，其余变体保留在手动触发门后，以减少不必要的构建时间和成本。

# 实现拆解

1. **重新组织 pipeline 构建组**：在 `.buildkite/release-pipeline.yaml` 中，将原 `Build Python wheels` 组拆分为两个组 `Build CUDA 13.0 Python wheels`（自动运行）和 `Build additional Python wheels`（通过 `block` 步骤手动触发）。自动组只包含 aarch64 和 x86_64 的 CUDA 13.0 构建。手动组包含其他所有变体，并依赖一个 `block-build-additional-wheels` 步骤，当 `NIGHTLY != 1` 时阻塞。
2. **添加门控条件和依赖**：手动组使用 `if: build.env("NIGHTLY") != "1"` 条件控制阻塞；当 NIGHTLY=1 时该步骤自动通过，实现完整构建。手动组还设置 `allow_dependency_failure: true`。
3. **索引脚本更新保护**：在 `.buildkite/scripts/generate-and-upload-nightly-index.sh` 中，将更新 nightly 索引的条件改为检查 `UPDATE_NIGHTLY_INDEX` 环境变量（默认 1），并且仅当主分支且非 PR 时更新。同时版本索引更新也新增 `UPDATE_VERSION_INDEX` 变量控制。
4. **ROCm 构建索引保护**：在 `.buildkite/scripts/upload-rocm-wheels.sh` 中，将更新 ROCm nightly 索引的条件从之前的主分支或 NIGHTLY=1 改为只允许 NIGHTLY=1 时更新，防止手动构建覆盖移动索引。
5. **文档同步更新**：在 `docs/contributing/ci/nightly_builds.md` 中说明新的构建策略和门控方式。

关键文件：
- `.buildkite/release-pipeline.yaml`（模块 构建流水线；类别 config；类型 configuration）: 核心变更文件，重新组织构建步骤，添加门控组
- `.buildkite/scripts/generate-and-upload-nightly-index.sh`（模块 脚本工具；类别 other；类型 core-logic）: 索引上传保护逻辑，增加环境变量控制
- `.buildkite/scripts/upload-rocm-wheels.sh`（模块 脚本工具；类别 other；类型 core-logic）: ROCm 构建索引保护，仅允许 NIGHTLY=1 时更新 nightly 索引
- `docs/contributing/ci/nightly_builds.md`（模块 文档；类别 docs；类型 documentation）: 文档更新，反映新的构建策略

关键符号：未识别


# 评论区精华

PR 未产生实质性讨论。唯一评论来自 mergify[bot] 自动部署文档预览。由于 PR 由 AI 辅助生成，且无人工 Review 讨论，所有设计决策已在提交摘要中明确。

- 暂无高价值评论线程

# 风险与影响

- 风险：
 1. **CI 配置风险**：pipeline YAML 结构变更可能影响其他依赖此 pipeline 的工具或监控。但已通过 `bk pipeline validate` 和结构断言验证。
 2. **手动触发遗忘风险**：若开发人员需要 CUDA 12.9 等变体但未意识到需手动触发，可能延迟获取。文档中已说明新行为。
 3. **索引覆盖风险**：新增的环境变量控制降低了手动构建覆盖 nightly 索引的风险，但若环境变量误设仍可能发生。
 - 影响：**CI 维护团队**：减少每次合并后构建的 wheel 数量，节省计算资源和时间，降低 pipeline 失败概率。**普通开发者**：默认获取 CUDA 13.0 构建，需要其他变体时需手动触发或使用 NIGHTLY=1 的完整构建。**ROCm/CPU 用户**：构建不再自动更新 nightly 索引，需按需触发。
 - 风险标记：CI 配置变更影响全局 pipeline, 手动触发可能被忽略 , 环境变量依赖增加复杂性

# 关联脉络

- PR #48771 [macOS] Fix annotation context for macOS builds: 同期处理的 macOS 相关 PR，但本 PR 正交不重复。