跳到内容

为 vLLM 做贡献

感谢您有兴趣为 vLLM 做出贡献！我们的社区对所有人开放，无论贡献大小，我们都欢迎各种形式的参与。您可以通过多种方式为该项目做出贡献：

  • 识别并报告任何问题或漏洞。
  • 请求或添加对新模型的支持。
  • 建议或实现新功能。
  • 改进文档或撰写使用指南。

我们也相信社区支持的力量；因此，回答查询、提供 PR（拉取请求）评审以及协助他人也是备受推崇的有益贡献。

最后，支持我们最有影响力的方式之一是提高 vLLM 的知名度。在您的博客中谈论它，并重点介绍它如何驱动您令人惊叹的项目。如果您正在使用 vLLM，请在社交媒体上表达您的支持，或者只需为我们的仓库点赞（Star）以表示您的赞赏！

任务看板

不知道从哪里开始？请查看以下链接以获取可进行的工作任务：

许可证

参见 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 --managed-python
source .venv/bin/activate

如果您仅开发 vLLM 的 Python 代码，请使用以下命令安装 vLLM：

VLLM_USE_PRECOMPILED=1 uv pip install -e .

如果您在开发 vLLM 的 Python 和 CUDA/C++ 代码，请先安装 Pytorch：

uv pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu129

然后从 requirements/build.txt 安装必要的构建依赖项，跳过 torch（因为它已在上一步中安装）：

grep -v '^torch==' requirements/build.txt | uv pip install -r -

最后使用以下命令安装 vLLM：

uv pip install -e . --no-build-isolation

有关从源码安装以及在其他硬件上安装的更多详细信息，请查看适用于您硬件的 安装说明，并跳转到“从源码构建 Wheel”部分。

为了在迭代 C++/CUDA 内核时获得优化的工作流程，请参阅 增量编译工作流程 (Incremental Compilation Workflow) 获取建议。

提示

vLLM 兼容 Python 3.10 到 3.13 版本。然而，vLLM 的默认 Dockerfile 使用 Python 3.12，且 CI 中的测试（mypy 除外）均使用 Python 3.12 运行。

因此，我们建议使用 Python 3.12 进行开发，以最大限度地减少本地环境与 CI 环境冲突的可能性。

代码检查

vLLM 使用 pre-commit 来对代码库进行 Lint 和格式化。如果您对 pre-commit 不熟悉，请参阅 https://pre-commit.git-scm.cn/#usage。设置 pre-commit 非常简单：

uv pip install pre-commit>=4.5.1
pre-commit install

vLLM 的 pre-commit 钩子现在将在您每次提交时自动运行。

提示

您可以手动运行 pre-commit 钩子：

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

有些 pre-commit 钩子仅在 CI 中运行。如果需要，您可以在本地运行它们：

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 平台以在本地运行单元测试，请暂时依赖持续集成 (CI) 系统来运行测试。

问题反馈

如果您发现错误或有功能请求，请先 搜索现有议题，看是否已有相关报告。如果没有，请 提交新议题，并提供尽可能多且相关的详细信息。

重要

如果您发现安全漏洞，请按照 此处的说明进行操作。

PR 与代码评审

感谢您对 vLLM 的贡献！在提交拉取请求 (PR) 之前，请确保该 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) 选项。

AI 辅助贡献

在做出 AI 辅助贡献之前，您必须：

  1. 保持参与：不要提交“纯代理”PR。人类提交者有责任审核所有更改的行，端到端验证行为，并运行相关测试。
  2. 确保意义：避免一次性的“繁杂工作”PR（单个拼写错误、孤立的样式清理、一个可变默认值的修复等）。将机械清理工作整合为清晰、系统的任务范围。

当 AI 工具在生成或修改代码方面提供非平凡的帮助时，您必须：

  1. 彻底审查：您仍对提交的所有代码负责。审查并理解 AI 生成的代码，其严谨程度应与手动编写代码相同。
  2. 在 PR 中披露：始终注明拉取请求何时包含 AI 生成的代码。在 PR 说明中添加备注。
  3. 标记提交：使用提交 Trailer（如 Co-authored-by:）添加署名（其他项目使用 Assisted-by: 或 Generated-by:）。例如：
Your commit message here

Co-authored-by: GitHub Copilot
Co-authored-by: Claude
Co-authored-by: gemini-code-assist
Signed-off-by: Your Name <[email protected]>

AI 辅助的代码必须符合所有质量标准：适当的测试、文档、遵循样式指南以及彻底的审查。署名有助于评审者在上下文中评估贡献，并保持项目的法律清晰度。

PR 标题和分类

只有特定类型的 PR 才会被审查。PR 标题应加上适当的前缀以表明更改类型。请使用以下前缀之一：

  • [Bugfix] 用于错误修复。
  • [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 的自定义算子需要元函数 (Meta-functions)。元函数应在 Python 中实现并注册，以便自动处理动态维度。请参阅上述文档以了解元函数的描述。
  • 使用 torch.library.opcheck() 测试任何已注册算子的函数注册和元函数。查看 tests/kernels 了解示例。
  • 更改现有算子的 C++ 签名时，必须更新 Schema 以反映更改。
  • 如果需要新的自定义类型，请参阅以下文档：PT2 中的自定义类支持。

大规模变更注意事项

请尽可能保持更改简洁。对于重大架构变更（>500 行代码，不含内核/数据/配置/测试），我们希望有一个 GitHub 议题 (RFC) 来讨论技术设计和理由。否则，我们将为其贴上 rfc-required 标签，该 PR 可能无法通过。

评审预期

vLLM 团队的目标是成为一个透明的评审机器。我们希望使评审过程透明高效，并确保没有任何贡献者感到困惑或沮丧。然而，vLLM 团队规模较小，因此我们需要确定一些 PR 的优先级。以下是您对评审过程的预期：

  • PR 提交后，将被分配给一名评审员。每位评审员将根据其专业领域和可用性选择 PR。
  • 分配 PR 后，评审员每 2-3 天会提供一次状态更新。如果 PR 在 7 天内未被评审，请随时通过 ping 提醒评审员或 vLLM 团队。
  • 评审后，如果需要更改，评审员会在 PR 上贴上 action-required 标签。贡献者应解决评论并 ping 评审员以重新评审 PR。
  • 请在合理的时间范围内回复所有评论。如果评论不明确或者您不同意建议，请随时寻求澄清或讨论该建议。
  • 请注意，由于计算资源有限，并非所有 CI 检查都会执行。当 PR 准备好合并或需要完整 CI 运行时，评审员会在 PR 上添加 ready 标签。

谢谢

最后，感谢您花时间阅读这些指南并关注 vLLM 的贡献。您的所有贡献都有助于使 vLLM 成为一个对每个人都出色的工具和社区！