增量编译工作流程¶

当您在 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 工具包是否已正确安装，并且 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 文件将在您的 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 文档。