执行摘要

• 一句话：CMake 构建新增全局 PTX 请求警告并完善文档与测试
• 推荐动作：值得快速阅读，尤其是对 vLLM 构建系统感兴趣的读者：本 PR 揭示了 CUDA 构建中 per-source gencode 规范化机制及全局 PTX 请求被丢弃的原因，PR body 与文档对行为描述清晰。评审中'警告测试不值得写'的取舍也值得参考——对纯提示性逻辑，维护成本可能超过收益。若计划继续推进 #9129 的后续项，可在此基础上考虑是否真正支持全局 PTX。

功能与动机

实现 issue #9129 中的一项需求：在 per-file CUDA archs（#8845）落地后，用户通过 TORCH_CUDA_ARCH_LIST 传入的 8.0+PTX 会被 vLLM 静默忽略。PR body 原话：'currently if there is a +PTX in TORCH_CUDA_ARCH_LIST this will be ignored. We should warn when this is the case'，并说明 'vLLM strips the Torch-provided global -gencode flags and rebuilds per-source gencode flags, so the global PTX request is not preserved'。目的是把这个静默行为在 CMake configure 阶段显式暴露给用户，避免用户误以为构建产物包含 PTX 支持。

实现拆解

1. 重命名宏以明确语义：在 cmake/utils.cmake 中把 clear_cuda_arches 重命名为 clear_cuda_gencode_flags，并同步更新 CMakeLists.txt 中的唯一调用点。名称改动强调清除的对象是 CMAKE_CUDA_FLAGS 中的 -gencode 标志，而非 CUDA 目标架构列表，避免与 cuda_archs 系列辅助函数混淆。
2. 新增 PTX 警告函数：在 cmake/utils.cmake 中新增 warn_if_ptx_arch_requested，遍历 clear_cuda_gencode_flags 提取出的 CUDA_ARCH_FLAGS，用正则 code=.*compute_[0-9]+[af]? 匹配 PTX 虚拟架构目标，命中即输出 WARNING 并提前返回；在 CMakeLists.txt 的 CUDA 分支中紧跟宏调用之后执行，提示用户移除 +PTX 或依赖 vLLM 内置的 per-kernel PTX 选择。
3. 测试配套：tests/test_cmake_utils.py 新增 _get_cmake_bin 辅助函数（优先 PATH、其次当前 Python venv 目录），使测试在未安装系统级 cmake 的开发环境中也能运行；新增 test_clear_cuda_gencode_flags 验证宏从 CMAKE_CUDA_FLAGS 中剥离 -gencode 并把剩余选项与提取结果正确输出。依据 review 讨论移除了 test_warn_if_ptx_arch_requested。
4. 文档配套：docs/getting_started/installation/gpu.cuda.inc.md 在安装指南中新增 note，说明 vLLM 按源（per-source）规范化 CUDA 架构以优化构建时间和 wheel 体积，全局 +PTX 请求被忽略，仅对特定内部内核生成 PTX。

关键文件：

• cmake/utils.cmake（模块 构建脚本；类别 infra；类型 core-logic；符号 warn_if_ptx_arch_requested, clear_cuda_gencode_flags）: 核心变更文件：新增 warn_if_ptx_arch_requested 警告函数，并将 clear_cuda_arches 重命名为 clear_cuda_gencode_flags 以明确清除 -gencode 标志的语义。
• tests/test_cmake_utils.py（模块 构建测试；类别 test；类型 test-coverage；符号 _get_cmake_bin, test_clear_cuda_gencode_flags）: 新增 _get_cmake_bin 辅助函数与 test_clear_cuda_gencode_flags 测试，扩展 CMake 工具函数覆盖；依据 review 讨论移除 PTX 警告测试。
• CMakeLists.txt（模块 构建脚本；类别 infra；类型 entrypoint）: 构建入口：调用改名后的宏和新的警告函数，是本 PR 行为生效的接入点。
• docs/getting_started/installation/gpu.cuda.inc.md（模块 安装文档；类别 docs；类型 documentation）: 安装文档补充 CUDA 架构与 PTX 标志规范化说明，帮助用户理解警告含义。

关键符号：warn_if_ptx_arch_requested, clear_cuda_gencode_flags, _get_cmake_bin, test_clear_cuda_gencode_flags

关键源码片段

cmake/utils.cmake

核心变更文件：新增 warn_if_ptx_arch_requested 警告函数，并将 clear_cuda_arches 重命名为 clear_cuda_gencode_flags 以明确清除 -gencode 标志的语义。

# 新增的警告函数：检测用户是否通过全局 CUDA 架构标志请求 PTX 代码生成。
# PR #8845 之后，vLLM 会剥离 Torch 注入的全局 -gencode 标志，并为每个源文件
# 重新生成 gencode 标志，因此 TORCH_CUDA_ARCH_LIST 里的全局 +PTX 请求
#（例如 "8.0+PTX"）不会被保留。此函数仅在 CMake configure 阶段发出警告，
# 不改变构建产物，避免用户误以为二进制包含 PTX 支持。
function(warn_if_ptx_arch_requested CUDA_ARCH_FLAGS)
  # 逐个检查从 CMAKE_CUDA_FLAGS 中提取出的 -gencode 标志，判断其中
  # 是否包含 code=compute_XX 形式的虚拟架构（即 PTX 目标）。
  foreach(_ARCH_FLAG ${CUDA_ARCH_FLAGS})
    # 正则匹配如 -gencode arch=compute_90,code=compute_90 的 PTX 条目；
    # 末尾的 [af]? 兼容带 f 后缀的浮点架构编号。
    if(_ARCH_FLAG MATCHES "code=.*compute_[0-9]+[af]?")
      message(WARNING
        "PTX code generation requested in CUDA architecture flags "
        "(${_ARCH_FLAG}), but vLLM does not preserve global PTX requests "
        "when normalizing per-source CUDA architectures. Remove '+PTX' from "
        "TORCH_CUDA_ARCH_LIST or rely on vLLM's built-in per-kernel PTX "
        "selection.")
      return()
    endif()
  endforeach()
endfunction()

tests/test_cmake_utils.py

新增 _get_cmake_bin 辅助函数与 test_clear_cuda_gencode_flags 测试，扩展 CMake 工具函数覆盖；依据 review 讨论移除 PTX 警告测试。

# 解析可用的 cmake 可执行文件：优先使用 PATH 中的系统 cmake，
# 否则回退到当前 Python 虚拟环境目录下的 cmake，最后回退到裸命令。
# 这样测试在未安装系统级 cmake 的开发环境里也能稳定运行。
def _get_cmake_bin() -> str:
    cmake = shutil.which("cmake")
    if cmake:
        return cmake
    venv_cmake = Path(sys.executable).parent / "cmake"
    if venv_cmake.is_file():
        return str(venv_cmake)
    return "cmake"
​
​
# 验证 clear_cuda_gencode_flags 宏的行为：它只从 CMAKE_CUDA_FLAGS 中
# 剥离 -gencode 标志（本例为 sm_80），并把这些标志原样存入
# CUDA_ARCH_FLAGS 输出变量，其余编译选项（-Wall）保持不变。
def test_clear_cuda_gencode_flags(tmp_path: Path):
    repo_root = Path(__file__).parents[1]
    script = tmp_path / "test_clear_flags.cmake"
    script.write_text(
        f"""
cmake_minimum_required(VERSION 3.26)
include("{repo_root / "cmake" / "utils.cmake"}")
set(CMAKE_CUDA_FLAGS "-Wall -gencode arch=compute_80,code=sm_80")
clear_cuda_gencode_flags(CUDA_ARCH_FLAGS)
if(NOT "${{CMAKE_CUDA_FLAGS}}" STREQUAL "-Wall ")
  message(FATAL_ERROR "Expected '-Wall ', got '${{CMAKE_CUDA_FLAGS}}'")
endif()
if(NOT "${{CUDA_ARCH_FLAGS}}" STREQUAL "-gencode arch=compute_80,code=sm_80")
  message(FATAL_ERROR "Expected '-gencode arch=compute_80,code=sm_80', "
    "got '${{CUDA_ARCH_FLAGS}}'")
endif()
"""
    )
​
    subprocess.run([_get_cmake_bin(), "-P", script], check=True)

评论区精华

核心讨论围绕测试的价值展开：

"This case has two positive cases that will trigger the warning, but you are checking them as a whole. BTW IMHO I do not think these tests make very much sense." —— Harry-Chen

"Fair enough, the added overhead does not make testing for a warning worthwhile. I removed test_warn_if_ptx_arch_requested." —— shanewidanagama

作者接受评审意见删除了 PTX 警告测试（commit 65ad5c4），Harry-Chen 最终以 "Thanks!" 批准合并。此外，mergify bot 曾提示 pre-commit 检查失败，Harry-Chen 要求修复 linter 问题；作者修复后多次触发 /ci run 与 /ci retry，并反馈 Buildkite CI 失败疑似与 PR 变更无关。

• warn_if_ptx_arch_requested 测试是否值得保留 (testing): 移除 test_warn_if_ptx_arch_requested，保留对 clear_cuda_gencode_flags 行为的功能性断言。
• pre-commit 与 CI 失败处理 (other): 格式问题修复后 Harry-Chen 批准合并，未发现与本 PR 直接相关的 CI 失败。

风险与影响

• 风险：
  1. 警告检测依赖正则：warn_if_ptx_arch_requested 使用 code=.*compute_[0-9]+[af]? 匹配 PTX 虚拟架构，对非常规编码形式（如带特殊后缀的架构编号）可能漏报或误报；但该函数只输出警告、不改变构建行为，风险限于信息误导。
  2. 宏重命名的影响面：clear_cuda_gencode_flags 是全局宏，若第三方分支或嵌入式构建脚本仍引用旧名 clear_cuda_arches 会报未定义错误；本仓库内唯一调用点已同步更新，风险主要存在于外部派生版本。
  3. 测试覆盖有限：评审移除了对警告函数本身的测试，warn_if_ptx_arch_requested 的正则行为没有自动化保护，后续改动该函数时需人工回归。
  4. 无运行时/性能风险：变更全部发生在 CMake configure 阶段，仅增加一次字符串遍历，对编译产物和推理性能无影响。
     - 影响：对用户：从源码构建 vLLM 且 TORCH_CUDA_ARCH_LIST 含 +PTX 时，会在 configure 阶段收到明确警告，减少对产物 PTX 支持的误解；安装文档同步解释该行为。对系统：CMake configure 增加一次标志遍历与正则匹配，开销可忽略，不影响构建产物内容。对团队：宏命名更准确，降低后续维护时的语义误解；测试基础设施增强了在 venv 环境下定位 cmake 的能力。总体影响范围小，属于构建期用户体验与可维护性改进。
     - 风险标记：仅构建期警告，不影响运行时产物, PTX 检测依赖正则，可能漏报或误报, 宏重命名需要全仓调用点同步, 警告测试被移除，覆盖有限

关联脉络

• PR #8845 [CI/Build] Per file CUDA Archs (improve wheel size and dev build times): PR body 明确指出本 PR 的 PTX 警告针对 #8845 引入 per-file CUDA archs 后全局 +PTX 请求被剥离的行为，属同一构建系统演进线；本 PR 同时实现了 #9129 中对应的一项。