增量編譯工作流程¶

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