增量编译工作流程¶

在 vLLM 的 C++/CUDA 内核（位于 csrc/ 目录）上工作时，每次更改都使用 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 工具包已正确安装，并且 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 环境中非常有用，因为在这些环境中不需要交互式提示。

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

示例 `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 和 buildPresets 中的 jobs 中精细调整 CMAKE_JOB_POOLS。过多的任务可能会使 RAM 或 CPU 核心有限的系统过载，导致构建速度变慢或系统不稳定。过少的任务则无法充分利用可用资源。
必要时进行清理构建： 如果遇到持续的或奇怪的构建错误，尤其是在进行重大更改或切换分支后，请考虑删除 CMake 构建目录（例如 rm -rf cmake-build-release）并重新运行 cmake --preset 和 cmake --build 命令。
特定目标构建： 当处理特定模块时，有时可以构建特定目标而不是完整的 install 目标，以实现更快的迭代，尽管 install 确保了您的 Python 环境中的所有必需组件都已更新。有关更高级的目标管理，请参阅 CMake 文档。