跳至内容

增量编译工作流程

在开发位于csrc/目录下的vLLM C++/CUDA内核时，每次修改后使用uv pip install -e .重新编译整个项目可能非常耗时。通过CMake实现的增量编译工作流可以在初始设置后仅重新编译必要的组件，从而加快迭代速度。本指南详细介绍了如何设置和使用这种工作流，它可以与你的可编辑Python安装相辅相成。

先决条件

在设置增量构建之前：

  1. 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

  2. CUDA工具包： 确认NVIDIA CUDA工具包已正确安装且nvcc可在PATH环境变量中访问。CMake依赖nvcc来编译CUDA代码。通常可以在$CUDA_HOME/bin/nvcc路径下找到nvcc，或通过运行which nvcc命令查找。若遇到问题，请参考官方CUDA工具包安装指南和vLLM的GPU安装文档进行故障排除。CMakeUserPresets.json文件中的CMAKE_CUDA_COMPILER变量也应指向您的nvcc可执行文件。

  3. 构建工具：强烈建议安装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文件，脚本会在覆盖前请求确认。

运行脚本后，会在你的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配置完成：

  1. 初始化CMake构建环境： 此步骤根据您选择的预设（例如release）配置构建系统，并在binaryDir目录下创建构建目录

    cmake --preset release

  2. 构建并安装vLLM组件： 该命令会编译代码并将生成的二进制文件安装到您的vLLM源代码目录中，使其可用于您的可编辑Python安装。

    cmake --build --preset release --target install

  3. 修改并重复测试！ 现在你可以开始使用可编辑安装的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文档。
优云智算