跳到內容

為 vLLM 貢獻

感謝您對 vLLM 貢獻的興趣！我們的社群對所有人開放，並歡迎各種形式的貢獻，無論大小。您可以透過以下幾種方式為專案做出貢獻：

  • 識別並報告任何問題或錯誤。
  • 請求或新增對新模型的支援。
  • 建議或實現新功能。
  • 改進文件或貢獻操作指南。

我們也相信社群支援的力量；因此，回答問題、提供 PR 審查和幫助他人也是備受推崇且有益的貢獻。

最後，支援我們的最具影響力的方式之一是提高 vLLM 的知名度。在您的博文中談論它，並強調它如何推動您出色的專案。如果您正在使用 vLLM，請在社交媒體上表達您的支援，或者僅僅透過點讚我們的儲存庫來表示您的讚賞！

工作列表

不確定從哪裡開始？檢視以下連結以獲取要處理的任務：

許可證

請參閱 LICENSE。

開發

為 vLLM 貢獻的第一步是克隆 GitHub 儲存庫。

git clone https://github.com/vllm-project/vllm.git
cd vllm

然後，配置您的 Python 虛擬環境。

建議使用 uv，一個非常快速的 Python 環境管理器，來建立和管理 Python 環境。請按照 文件 安裝 uv。安裝 uv 後，您可以使用以下命令建立新的 Python 環境。

uv venv --python 3.12 --seed
source .venv/bin/activate

如果您只開發 vLLM 的 Python 程式碼，請使用以下命令安裝 vLLM：

VLLM_USE_PRECOMPILED=1 uv pip install -e .

如果您開發 vLLM 的 Python 和 CUDA/C++ 程式碼，請使用以下命令安裝 vLLM：

uv pip install -e .

有關從原始碼安裝以及為其他硬體安裝的更多詳細資訊，請檢視適用於您硬體的安裝說明，然後前往“從原始碼構建 wheel”部分。

有關在迭代 C++/CUDA 核函式時最佳化工作流，請參閱增量編譯工作流以獲取建議。

提示

vLLM 相容 Python 3.10 至 3.13 版本。但是，vLLM 的預設 Dockerfile 使用 Python 3.12 進行構建，並且 CI 中的測試（除 `mypy` 外）都使用 Python 3.12 執行。

因此，我們建議使用 Python 3.12 進行開發，以最大程度地減少本地環境與我們的 CI 環境衝突的可能性。

程式碼檢查

vLLM 使用 pre-commit 來檢查和格式化程式碼庫。如果您不熟悉 pre-commit，請參閱https://pre-commit.com/#usage。設定 pre-commit 非常簡單：

uv pip install pre-commit
pre-commit install

vLLM 的 pre-commit hooks 現在將在每次提交時自動執行。

提示

您可以使用以下命令手動執行 pre-commit hooks：

pre-commit run     # runs on staged files
pre-commit run -a  # runs on all files (short for --all-files)

某些 pre-commit hooks 僅在 CI 中執行。如果需要，您可以在本地使用以下命令執行它們：

pre-commit run --hook-stage manual markdownlint
pre-commit run --hook-stage manual mypy-3.10

文件

MkDocs 是一個快速、簡單且非常漂亮的靜態站點生成器，專為構建專案文件而設計。文件原始檔使用 Markdown 編寫，並透過單個 YAML 配置檔案進行配置，即 mkdocs.yaml。

開始操作：

uv pip install -r requirements/docs.txt

提示

確保您的 Python 版本與外掛相容（例如，mkdocs-awesome-nav 需要 Python 3.10+）。

MkDocs 內建了一個開發伺服器，可以在您編寫文件時預覽。在儲存庫的根目錄下執行：

mkdocs serve                           # with API ref (~10 minutes)
API_AUTONAV_EXCLUDE=vllm mkdocs serve  # API ref off (~15 seconds)

一旦您在日誌中看到 Serving on http://127.0.0.1:8000/，即時預覽就已準備就緒！在瀏覽器中開啟 http://127.0.0.1:8000/ 檢視。

有關其他功能和高階配置，請參閱：

測試

vLLM 使用 pytest 來測試程式碼庫。

# Install the test dependencies used in CI (CUDA only)
uv pip install -r requirements/common.txt -r requirements/dev.txt --torch-backend=auto

# Install some common test dependencies (hardware agnostic)
uv pip install pytest pytest-asyncio

# Run all tests
pytest tests/

# Run tests for a single test file with detailed output
pytest -s -v tests/test_logger.py

如果缺少 Python.h，請安裝 python3-dev。

如果以上任何命令因 Python.h: No such file or directory 而失敗，請使用 sudo apt install python3-dev 安裝 python3-dev。

警告

當前，儲存庫並未完全透過 mypy 檢查。

當前，在 CPU 平臺上執行時並非所有單元測試都能透過。如果您無法在 GPU 平臺上本地執行單元測試，請暫時依賴持續整合系統來執行測試。

問題

如果您遇到 bug 或有功能請求，請先搜尋現有問題，看看是否已報告。如果沒有，請提交新問題，提供儘可能多的相關資訊。

重要

如果您發現安全漏洞，請遵循 此處的說明。

拉取請求和程式碼審查

感謝您為 vLLM 做出貢獻！在提交拉取請求之前，請確保 PR 符合以下標準。這有助於 vLLM 保持程式碼質量並提高審查過程的效率。

DCO 和 Signed-off-by

在為本專案貢獻更改時，您必須同意 DCO。提交必須包含 Signed-off-by: 標頭，以證明您同意 DCO 的條款。

使用 git commit -s 將自動新增此標頭。

提示

您可以透過 IDE 啟用自動簽名提交：

  • PyCharm：在 Commit 視窗中，點選 Commit and Push... 按鈕右側的 Show Commit Options 圖示。這將開啟一個 git 視窗，您可以在其中修改 Author 並啟用 Sign-off commit。
  • VSCode：開啟設定編輯器並啟用 Git: Always Sign Off (git.alwaysSignOff) 欄位。

PR 標題和分類

只有特定型別的 PR 才會被審查。PR 標題應加上適當的字首以表明更改型別。請使用以下字首之一：

  • [Bugfix] 用於 bug 修復。
  • [CI/Build] 用於構建或持續整合改進。
  • [Doc] 用於文件修復和改進。
  • [Model] 用於新增新模型或改進現有模型。模型名稱應出現在標題中。
  • [Frontend] 用於 vLLM 前端（例如，OpenAI API 伺服器、LLM 類等）的更改。
  • [Kernel] 用於影響 CUDA 核函式或其他計算核函式的更改。
  • [Core] 用於 vLLM 核心邏輯（例如，LLMEngine、AsyncLLMEngine、Scheduler 等）的更改。
  • [Hardware][Vendor] 用於特定於硬體的更改。供應商名稱應出現在字首中（例如，[Hardware][AMD]）。
  • [Misc] 用於不屬於上述類別的 PR。請謹慎使用此選項。

注意

如果 PR 跨越多個類別，請包含所有相關的字首。

程式碼質量

PR 需要滿足以下程式碼質量標準：

  • 我們遵循Google Python 風格指南和Google C++ 風格指南。
  • 透過所有 linter 檢查。
  • 程式碼需要有良好的文件記錄，以確保未來的貢獻者能夠輕鬆理解程式碼。
  • 包含足夠的測試以確保專案保持正確和健壯。這包括單元測試和整合測試。
  • 如果 PR 修改了 vLLM 的面向使用者的行為，請在 docs/ 中新增文件。這有助於 vLLM 使用者理解和利用新功能或更改。

新增或修改核函式

在積極開發或修改核函式時，強烈建議使用增量編譯工作流以加快構建速度。每個自定義核函式都需要一個 schema 和一個或多個實現才能在 PyTorch 中註冊。

  • 確保自定義操作按照 PyTorch 指南進行註冊：自定義 C++ 和 CUDA 運算子和自定義運算子手冊。
  • 返回 Tensors 的自定義操作需要元函式。元函式應在 Python 中實現和註冊，以便動態維度可以自動處理。有關元函式的描述，請參閱上述文件。
  • 使用torch.library.opcheck() 來測試任何註冊運算子的函式註冊和元函式。有關示例，請參閱 tests/kernels。
  • 更改現有運算子的 C++ 簽名時，必須更新 schema 以反映更改。
  • 如果需要新的自定義型別，請參閱以下文件：PT2 中的自定義類支援。

關於大型更改的說明

請保持更改儘可能簡潔。對於重大的架構更改（超過 500 行程式碼，不包括核函式/資料/配置/測試），我們期望在 GitHub 問題（RFC）中討論技術設計和理由。否則，我們將標記為 rfc-required，並且可能不會繼續處理 PR。

關於審查的預期

vLLM 團隊的目標是成為一個透明的審查機器。我們希望使審查過程透明且高效，並確保沒有貢獻者感到困惑或沮喪。但是，vLLM 團隊規模很小，因此我們需要優先處理某些 PR。以下是您可以從審查過程中期待的內容：

  • PR 提交後，PR 將被分配給一名審查員。每位審查員將根據其專業知識和可用性來處理 PR。
  • PR 分配後，審查員將每 2-3 天提供狀態更新。如果 PR 在 7 天內未得到審查，請隨時提醒審查員或 vLLM 團隊。
  • 審查後，如果需要更改，審查員將在 PR 上新增 action-required 標籤。貢獻者應處理評論，並提醒審查員重新審查 PR。
  • 請在合理的時間內回覆所有評論。如果您對某條評論不清楚或不同意某項建議，請隨時尋求澄清或討論該建議。
  • 請注意，由於計算資源有限，並非所有 CI 檢查都會執行。當 PR 準備好合併或需要完整的 CI 執行時，審查員將新增 ready 標籤。

感謝

最後，感謝您花時間閱讀這些指南以及您對 vLLM 貢獻的興趣。您的所有貢獻都有助於使 vLLM 成為一個對每個人來說都很棒的工具和社群！