增量编译工作流¶

当在位于 csrc/ 目录下的 vLLM C++/CUDA 内核上工作时，每次更改都使用 uv pip install -e . 重新编译整个项目非常耗时。使用 CMake 的增量编译工作流可以通过在初始设置后仅重新编译必要的组件来实现更快的迭代。本指南详细介绍了如何设置和使用此工作流，它将作为您可编辑 Python 安装的补充。

先决条件¶

设置增量构建之前

vLLM 可编辑安装： 确保您已通过源码以可编辑模式安装了 vLLM。对于初始可编辑设置，使用预编译的 wheel 包可能会更快，因为 CMake 工作流将处理后续的内核重编译。
```
uv venv --python 3.12 --seed
source .venv/bin/activate
VLLM_USE_PRECOMPILED=1 uv pip install -U -e . --torch-backend=auto
```
CUDA 工具包： 验证 NVIDIA CUDA Toolkit 是否已正确安装，且 nvcc 可在您的 PATH 中访问。CMake 依赖 nvcc 来编译 CUDA 代码。通常可以在 $CUDA_HOME/bin/nvcc 中找到 nvcc，或者通过运行 which nvcc 来验证。如果遇到问题，请参考 CUDA 工具包官方安装指南以及 vLLM 主 GPU 安装文档进行排查。您的 CMakeUserPresets.json 中的 CMAKE_CUDA_COMPILER 变量也应指向您的 nvcc 二进制文件。
构建工具： 强烈建议安装 ccache，通过缓存编译结果来加快重构速度（例如 sudo apt install ccache 或 conda install ccache）。此外，请确保已安装 cmake 和 ninja 等核心构建依赖项。这些可以通过 requirements/build.txt 或系统的包管理器进行安装。
```
uv pip install -r requirements/build.txt --torch-backend=auto
```

设置 CMake 构建环境¶

增量构建过程通过 CMake 进行管理。您可以在 vLLM 仓库的根目录下使用 CMakeUserPresets.json 文件来配置构建设置。

使用辅助脚本生成 `CMakeUserPresets.json`¶

为了简化设置，vLLM 提供了一个辅助脚本，该脚本会尝试自动检测您的系统配置（如 CUDA 路径、Python 环境和 CPU 核心数），并为您生成 CMakeUserPresets.json 文件。

运行脚本

导航到您的 vLLM 克隆根目录并执行以下命令

python tools/generate_cmake_presets.py

如果脚本无法自动确定某些路径（例如 nvcc 或您的 vLLM 开发环境特定的 Python 可执行文件），它会提示您。请按照屏幕上的提示操作。如果发现已存在 CMakeUserPresets.json，脚本会在覆盖前要求确认。

强制覆盖现有文件

要自动覆盖现有的 CMakeUserPresets.json 而不进行提示，请使用 --force-overwrite 标志

python tools/generate_cmake_presets.py --force-overwrite

这在自动化脚本或 CI/CD 环境中特别有用，因为这些场景下不需要交互式提示。

运行脚本后，CMakeUserPresets.json 文件将在 vLLM 仓库的根目录中创建。

`CMakeUserPresets.json` 示例¶

以下是生成的 CMakeUserPresets.json 可能的样子。脚本会根据您的系统和您提供的任何输入来定制这些值。

{
    "version": 6,
    "cmakeMinimumRequired": {
        "major": 3,
        "minor": 26,
        "patch": 1
    },
    "configurePresets": [
        {
            "name": "release",
            "generator": "Ninja",
            "binaryDir": "${sourceDir}/cmake-build-release",
            "cacheVariables": {
                "CMAKE_CUDA_COMPILER": "/usr/local/cuda/bin/nvcc",
                "CMAKE_C_COMPILER_LAUNCHER": "ccache",
                "CMAKE_CXX_COMPILER_LAUNCHER": "ccache",
                "CMAKE_CUDA_COMPILER_LAUNCHER": "ccache",
                "CMAKE_BUILD_TYPE": "Release",
                "VLLM_PYTHON_EXECUTABLE": "/home/user/venvs/vllm/bin/python",
                "CMAKE_INSTALL_PREFIX": "${sourceDir}",
                "CMAKE_CUDA_FLAGS": "",
                "NVCC_THREADS": "4",
                "CMAKE_JOB_POOLS": "compile=32"
            }
        }
    ],
    "buildPresets": [
        {
            "name": "release",
            "configurePreset": "release",
            "jobs": 32
        }
    ]
}

各种配置的含义是什么？

CMAKE_CUDA_COMPILER：指向您的 nvcc 二进制文件的路径。脚本会自动尝试查找此路径。
CMAKE_C_COMPILER_LAUNCHER、CMAKE_CXX_COMPILER_LAUNCHER、CMAKE_CUDA_COMPILER_LAUNCHER：将这些设置为 ccache（或 sccache）可以通过缓存编译结果显著加快重构速度。请确保已安装 ccache（例如 sudo apt install ccache 或 conda install ccache）。脚本默认会设置这些项。
VLLM_PYTHON_EXECUTABLE：您的 vLLM 开发环境中 Python 可执行文件的路径。脚本会提示您输入此项，默认使用当前 Python 环境（如果适用）。
CMAKE_INSTALL_PREFIX: "${sourceDir}"：指定编译后的组件应安装回您的 vLLM 源码目录。这对可编辑安装至关重要，因为它使新构建的内核能够立即供您的 Python 环境使用。
CMAKE_JOB_POOLS 和构建预设中的 jobs：控制构建的并行度。脚本会根据系统中检测到的 CPU 核心数设置这些参数。
binaryDir：指定构建产物的存储位置（例如 cmake-build-release）。

使用 CMake 构建和安装¶

一旦您的 CMakeUserPresets.json 配置完成

初始化 CMake 构建环境： 此步骤根据您选择的预设（例如 release）配置构建系统，并在 binaryDir 创建构建目录
```
cmake --preset release
```
构建并安装 vLLM 组件： 该命令会编译代码并将生成的二进制文件安装到您的 vLLM 源码目录中，从而使其可供您的可编辑 Python 安装使用。
```
cmake --build --preset release --target install
```
进行更改并重复！ 现在您可以开始使用 vLLM 的可编辑安装，根据需要进行测试和修改。如果您需要根据更改再次构建，只需再次运行 CMake 命令以仅构建受影响的文件。
```
cmake --build --preset release --target install
```

验证构建¶

构建成功后，您会找到一个已填充的构建目录（例如，如果您使用了 release 预设和示例配置，则为 cmake-build-release/）。

> ls cmake-build-release/
bin             cmake_install.cmake      _deps                                machete_generation.log
build.ninja     CPackConfig.cmake        detect_cuda_compute_capabilities.cu  marlin_generation.log
_C.abi3.so      CPackSourceConfig.cmake  detect_cuda_version.cc               _moe_C.abi3.so
CMakeCache.txt  ctest                    _flashmla_C.abi3.so                  moe_marlin_generation.log
CMakeFiles      cumem_allocator.abi3.so  install_local_manifest.txt           vllm-flash-attn

cmake --build ... --target install 命令会将编译好的共享库（如 _C.abi3.so、_moe_C.abi3.so 等）复制到源码树中相应的 vllm 包目录中。这会使用新编译的内核更新您的可编辑安装。

其他提示¶

调整并行度： 在 CMakeUserPresets.json 中微调 configurePresets 下的 CMAKE_JOB_POOLS 和 buildPresets 下的 jobs。过多的作业可能会导致内存或 CPU 核心受限的系统过载，从而导致构建变慢或系统不稳定。过少则无法充分利用现有资源。
必要时进行清理构建： 如果遇到持续或奇怪的构建错误，特别是在进行重大更改或切换分支后，请考虑删除 CMake 构建目录（例如 rm -rf cmake-build-release），然后重新运行 cmake --preset 和 cmake --build 命令。
特定目标构建： 当处理特定模块时，为了更快的迭代，您可以有时选择构建特定目标而不是完整的 install 目标，尽管 install 能确保所有必要的组件在您的 Python 环境中得到更新。有关更高级的目标管理，请参考 CMake 文档。