跳到内容

为 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.git-scm.cn/#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 成为一个对每个人来说都很棒的工具和社区！