增量編譯工作流程¶

當您在 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 文件。