跳到内容

为 vLLM 做贡献

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

  • 发现并报告任何问题或错误。
  • 请求或添加对新模型的支持。
  • 建议或实现新功能。
  • 改进文档或贡献一份操作指南。

我们也相信社区支持的力量；因此，回答疑问、提供 PR 审查以及帮助他人也是非常受重视和有益的贡献。

最后，支持我们最有影响力的方式之一是提高 vLLM 的知名度。在您的博客文章中谈论它，并重点介绍它是如何驱动您那些令人惊叹的项目的。如果您正在使用 vLLM，请在社交媒体上表达您的支持，或者简单地通过为我们的代码仓库点赞（star）来表达您的赞赏！

任务看板

不确定从哪里开始？可以查看以下链接，寻找可以参与的任务：

许可证

请参阅 许可证。

开发

为 vLLM 做贡献的第一步是克隆 GitHub 仓库：

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

然后，配置您的 Python 虚拟环境。

仅在 NVIDIA CUDA 上，建议使用 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 环境冲突的可能性。

代码检查（Linting）

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

uv pip install pre-commit
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 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 平台运行单元测试，请暂时依赖持续集成系统来运行测试。

问题（Issues）

如果您遇到错误或有功能请求，请先搜索现有的问题，看是否已有人报告。如果没有，请提交一个新的问题，并提供尽可能多的相关信息。

重要

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

拉取请求（Pull Requests）与代码审查（Code Reviews）

感谢您为 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] 用于错误修复。
  • [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++ 风格指南。
  • 通过所有代码检查器的检查。
  • 代码需要有良好的文档，以确保未来的贡献者能够轻松理解代码。
  • 包含足够的测试以确保项目保持正确和稳健。这包括单元测试和集成测试。
  • 如果 PR 修改了 vLLM 面向用户的行为，请在 docs/ 目录中添加文档。这有助于 vLLM 用户理解和使用新功能或更改。

添加或更改算子（Kernels）

在积极开发或修改算子时，强烈建议使用增量编译工作流以加快构建时间。每个自定义算子都需要一个模式（schema）和一个或多个实现，并注册到 PyTorch 中。

  • 确保自定义操作（ops）遵循 PyTorch 的指导方针进行注册：自定义 C++ 和 CUDA 操作 和 自定义操作手册。
  • 返回 Tensors 的自定义操作需要元函数（meta-functions）。元函数应在 Python 中实现和注册，以便可以自动处理动态维度。有关元函数的描述，请参见上述文档。
  • 使用 torch.library.opcheck() 来测试任何已注册操作的函数注册和元函数。请参阅 tests/kernels 中的示例。
  • 当更改现有操作的 C++ 签名时，必须更新其模式以反映这些更改。
  • 如果需要新的自定义类型，请参阅以下文档：PT2 中的自定义类支持。

重大变更须知

请尽量保持变更简洁。对于重大的架构性变更（>500 行代码，不包括算子/数据/配置/测试），我们期望您先提交一个 GitHub issue (RFC)，讨论技术设计和理由。否则，我们可能会给其打上 rfc-required 标签，并且可能不会审查该 PR。

对审查过程的期望

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

  • 提交 PR 后，PR 将被分配给一位审查者。每位审查者将根据其专业知识和时间安排来处理 PR。
  • PR 被分配后，审查者将每 2-3 天提供一次状态更新。如果 PR 在 7 天内未被审查，请随时提醒（ping）审查者或 vLLM 团队。
  • 审查后，如果需要修改，审查者会给 PR 打上 action-required 标签。贡献者应处理评论并提醒审查者重新审查 PR。
  • 请在合理的时间内回复所有评论。如果某个评论不清楚或您不同意某个建议，请随时要求澄清或讨论该建议。
  • 请注意，由于计算资源有限，并非所有 CI 检查都会执行。当 PR 准备好合并或需要进行完整的 CI 运行时，审查者会给 PR 添加 ready 标签。

致谢

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