vLLM 开发入门 #32
Description
作者：noooop
大家好！如果你对 vLLM 项目感兴趣，这里有一份来自社区成员的贡献指南，希望能帮你顺利上手。
vLLM 欢迎任何形式的帮助！ 例如：
- 发现并报告问题：在使用过程中遇到 Bug 或不一致的地方？
- 支持新模型：希望 vLLM 支持你喜欢的模型？可以提需求，或者自己动手实现。
- 提出想法或新功能：有好点子？或者直接动手添加一个新特性。
- 改进文档与教程：觉得文档哪里不容易理解？欢迎帮忙改得更清晰。
- 帮助其他小伙伴：在社区回答问题，或者协助 Review 代码，都是很棒的贡献。
- 帮忙宣传：如果觉得 vLLM 好用，欢迎在博客或社交媒体分享，或者给我们的 GitHub 点个 Star，这都是很大的支持！
如果不知道从何开始：
可以到项目的 Job Board（任务板） 看看，那里标注了许多适合入门的任务和新模型支持任务，挑一个感兴趣的即可！
🚀 第一步：准备好开发环境
- 把代码搞到本地：
git clone https://github.com/vllm-project/vllm.git
cd vllm - 配置Python环境：
推荐使用 uv 管理环境，更轻量快速。安装 uv 后，一键创建环境：
uv venv --python 3.12 --seed
source .venv/bin/activate
注意：建议使用 Python 3.12，vLLM 的主要测试和兼容性基于此版本，可减少本地与测试环境不一致的问题。 - 安装vLLM（两种方式）：
- 如果只改 Python 代码，可开启预编译加速安装：
VLLM_USE_PRECOMPILED=1 uv pip install -e . - 如果还需要修改底层 C++/CUDA 内核代码，使用标准安装方式：
uv pip install -e .
🔧 开发与调试小贴士 - 调试（Debug）：
如果使用 VS Code，可以直接复制下面提供的 launch.json 配置，一键启动带调试的 vLLM 服务。
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"name": "vllm server single",
"type": "debugpy",
"request": "launch",
"module": "vllm.entrypoints.cli.main",
"env": {
"VLLM_LOGGING_LEVEL": "DEBUG",
// "VLLM_USE_MODELSCOPE": "True",
// "MODELSCOPE_DOWNLOAD_PARALLELS": "10",
},
"args": [
"serve",
"Qwen/Qwen3-0.6B",
"--reasoning-parser",
"qwen3",
"--gpu-memory-utilization",
"0.8",
"--port",
"8000",
"--enforce-eager",
"--max-model-len",
"5120",
"-tp",
"1",
],
},
]
} - 性能分析（Profiling）：
- 启动服务时可通过 --profiler-config 参数开启性能分析：
vllm serve Qwen/Qwen3-0.6B --profiler-config '{"profiler": "torch", "torch_profiler_dir": "./vllm_profile"}' - 服务启动后，会提供 /start_profile 和 /stop_profile 接口，通过 curl 控制记录开始与结束：
- 启动服务时可通过 --profiler-config 参数开启性能分析：
We need first call /start_profile api to start profile.
$ curl -X POST http://localhost:8000/start_profile
Call model generate.
curl -X POST http://localhost:8000/v1/chat/completions
-H "Content-Type: application/json"
-d '{
"model": "Qwen/Qwen3-0.6B",
"messages": [
{
"role": "user",
"content": "9.11 and 9.8, which is greater?"
}
]
}'
After need call /stop_profile api to stop profile.
$ curl -X POST http://localhost:8000/stop_profile
- 生成的 .pt.trace.json.gz 文件可拖到 https://ui.perfetto.dev/ 可视化，查看函数调用和耗时详情。
We need first call /start_profile api to start profile.
$ curl -X POST http://localhost:8000/start_profile
Call model generate.
curl -X POST http://localhost:8000/v1/chat/completions
-H "Content-Type: application/json"
-d '{
"model": "Qwen/Qwen3-0.6B",
"messages": [
{
"role": "user",
"content": "9.11 and 9.8, which is greater?"
}
]
}'
After need call /stop_profile api to stop profile.
$ curl -X POST http://localhost:8000/stop_profile
[图片]
- 代码风格检查（Linting）：
vLLM 使用 pre-commit 自动检查代码格式。安装后，每次 git commit 会自动运行检查。
uv pip install pre-commit
pre-commit install - 也可手动检查所有文件：pre-commit run -a
📖 写文档和跑测试 - 文档
- vLLM 文档基于 MkDocs 编写，源文件为 Markdown。安装依赖后，运行mkdocs serve本地实时预览：
- 测试
- vLLM 测试主要使用 pytest 运行测试。安装测试依赖后，可运行全部测试或单个测试文件
pytest tests/
📬 正式贡献流程：提交 Issue 与 PR
提交 Issue（问题或需求）
- vLLM 测试主要使用 pytest 运行测试。安装测试依赖后，可运行全部测试或单个测试文件
- 遇到 Bug 或有新想法？请先到 GitHub Issues 搜索是否已有类似内容。
- 若没有，新建一个 Issue，尽量详细描述（如复现步骤、环境信息）。
- 重要！！！：如发现安全问题，请按安全指南私下报告，勿公开在 Issue 中。
- 提交 Pull Request（PR）
代码完成后即可提交 PR。为保障流程顺畅，请遵守以下约定：
- 同意开发者协议（DCO）
在每个 commit 信息中需添加一行 Signed-off-by: 你的名字 <邮箱>。
使用 git commit -s 可自动添加，也可在 VS Code 或 PyCharm 中设置自动添加。 - 撰写清晰的 PR 标题
标题前加上明确前缀，便于快速识别修改类型，例如：- [Bugfix]：修复 Bug
- [Doc]：文档更新
- [Model] Qwen2：模型支持或改进
- [Kernel]：CUDA 内核修改
- [Core]：核心引擎逻辑修改
- [Hardware][AMD]：硬件相关改动
- [Misc]：其他小改动（慎用）
若涉及多个方面，可合并相关前缀。
- 保证代码质量
- 遵循 Google 的 Python 与 C++ 代码风格指南。
- 通过所有 pre-commit 格式检查。
- 编写清晰的注释与文档。
- 记得补充测试，确保改动可靠。
- 若影响用户使用（如新增参数、功能），请同步更新 docs/ 下的文档。
- 关于内核（Kernel）代码
- 若修改底层 C++/CUDA 内核，建议了解“增量编译工作流程”以提升编译效率。
- 新增自定义算子时，请按规范在 PyTorch 中注册并编写对应测试。
- 大型改动请先讨论（RFC）
如果改动较大（代码超过 500 行，不含数据、配置、测试），请先创建 GitHub Issue 讨论技术方案与理由，达成共识后再编码。否则 PR 可能会被标记为 rfc-required 而暂缓审查。
🔍 审查流程（Review）是怎样的？
- PR 提交后，会分配给一位 Reviewer。
- 你可以在 vLLM 贡献者列表 查看各领域的 Reviewer。
- Reviewer 通常每 2–3 天反馈一次进度。若提交 7 天后仍无回复，可在 PR 中 @ 相关 Reviewer，或到 Slack 的 #pr-reviews 频道提醒。
- 如需修改，PR 会被标记为 action-required。修改完成后请通知 Reviewer 再次审查。
- 请及时回复评论。如有疑问或不同意见，随时提问讨论。
- 注意：为节省资源，并非每个 PR 都会立即运行全部 CI 测试。当 PR 基本就绪、准备合并时，Reviewer 会加上 ready 标签，触发完整 CI 检查。
🎉 开始你的 vLLM 贡献之旅吧！
关键步骤回顾：
领任务 → 搭环境 → 写代码 → 跑测试/检查 → 提 PR → 根据反馈修改 → 合并！
不必担心起点高低，社区伙伴都很友好。从一个小的修复或文档改进开始，就是很好的第一步。期待看到你的第一个 vLLM PR！
笔者也是从小白
参考
https://docs.vllm.ai/en/latest/contributing/
https://docs.vllm.ai/en/latest/governance/collaboration/
https://docs.vllm.ai/en/latest/governance/process/
https://docs.vllm.ai/en/latest/governance/committers/
###########################################################
原文：
###########################################################
如何为 vLLM 做出贡献
首先感谢你有兴趣为 vLLM 做出贡献！我们的社区向所有人开放，并欢迎各种形式的贡献，无论大小。你可以通过以下几种方式为项目做出贡献：
- 发现并报告问题或错误。
- 请求或添加对新模型的支持。
- 建议或实现新功能。
- 改进文档或贡献操作指南。
我们也相信社区支持的力量；因此，回答问题、提供 PR 审查以及帮助他人也是备受重视且有益的贡献。
最后，支持我们最有影响力的方式之一是提高对 vLLM 的认识。在你的博客文章中谈论它，并强调它如何推动你的出色项目。如果你正在使用 vLLM，请在社交媒体上表达你的支持，或者通过为我们的仓库加星来表达你的赞赏！
Job Board 任务板
如果不确定从哪里开始？可以去任务板查看取待处理的任务： - 入门问题
- 新模型支持
开发指南
为 vLLM 做出贡献的第一步是克隆 GitHub 仓库：
bash
git clone https://github.com/vllm-project/vllm.git
cd vllm
然后，配置你的 Python 虚拟环境。
推荐使用 uv。 uv是一个的 Python 环境管理器，用来创建和管理 Python 环境。请按照文档安装 uv。安装完成后，你可以使用以下命令创建一个新的 Python 环境：
bash
uv venv --python 3.12 --seedsource .venv/bin/activate
如果你仅修改 vLLM 的 Python 部分，请开启下载预编译模块加快安装速度：
bash
VLLM_USE_PRECOMPILED=1 uv pip install -e .
如果你同时开发 vLLM 的 Python 和 CUDA/C++ 代码，请使用以下命令安装 vLLM：
bash
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 环境发生冲突的可能性。
Debug 指南
如果你熟悉使用 VS Code，这里有一份 launch.json 配置，配置调试 vLLM.
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"name": "vllm server single",
"type": "debugpy",
"request": "launch",
"module": "vllm.entrypoints.cli.main",
"env": {
"VLLM_LOGGING_LEVEL": "DEBUG",
// "VLLM_USE_MODELSCOPE": "True",
// "MODELSCOPE_DOWNLOAD_PARALLELS": "10",
},
"args": [
"serve",
"Qwen/Qwen3-0.6B",
"--reasoning-parser",
"qwen3",
"--gpu-memory-utilization",
"0.8",
"--port",
"8000",
"--enforce-eager",
"--max-model-len",
"5120",
"-tp",
"1",
],
},
]
}
开始的你 vLLM 开发之旅吧～
Profiling 指南
vLLM 提供了 --profiler-config 参数来开启 profiling，如下所示
vllm serve Qwen/Qwen3-0.6B --profiler-config '{"profiler": "torch", "torch_profiler_dir": "./vllm_profile"}'
设置该参数后，vllm 会启动两个 http endpoint，/start_profile 和 /stop_profile, 你可以通过调用这个两个 http endpoint 来启动和停止 profiling
We need first call /start_profile api to start profile.
$ curl -X POST http://localhost:8000/start_profile
Call model generate.
curl -X POST http://localhost:8000/v1/chat/completions
-H "Content-Type: application/json"
-d '{
"model": "Qwen/Qwen3-0.6B",
"messages": [
{
"role": "user",
"content": "9.11 and 9.8, which is greater?"
}
]
}'
After need call /stop_profile api to stop profile.
$ curl -X POST http://localhost:8000/stop_profile
当你 调用 /stop_profile 后，目前/vllm_profile 下会生成一些文件 ，如下所示
1767687660802231168-rank-0.1767687963353114465.pt.trace.json.gz
1767687660802231168-rank-0.1767687964014426797.pt.trace.json.gz
1767687660802231168-rank-0.1767687964637556322.pt.trace.json.gz
1767687660802231168-rank-0.1767687966207743877.pt.trace.json.gz
你可以将这些文件通过 https://ui.perfetto.dev/ 进行可视化。
例如笔者对 DeepSeek V32 进行 profilling 后的效果
[图片]
可以看到非常详细的函数调用过程，耗时等，perfetto.dev 网站支持对每一个地方进行放大，你可以非常细节的观察vLLM 是如何进行工作的。
Linting 代码规范检查
vLLM 使用 pre-commit 来检查和格式化代码库。如果你不熟悉 pre-commit，请参阅 https://pre-commit.com/#usage。设置 pre-commit 非常简单：
uv pip install pre-commit
pre-commit install
pre-commit run --all-files
现在，每次提交代码时，vLLM 的 pre-commit 钩子都会自动运行。
提示
你可以使用以下命令手动运行 pre-commit 钩子：
bash
pre-commit run # 对暂存文件运行
pre-commit run -a # 对所有文件运行（--all-files 的缩写）
部分 pre-commit 钩子仅在 CI 中运行。如果需要，你可以在本地运行它们：
bash
pre-commit run --hook-stage manual markdownlint
pre-commit run --hook-stage manual mypy-3.10
文档
MkDocs 是一款快速、简单且非常美观的静态站点生成器，专为构建项目文档而设计。文档源文件使用 Markdown 编写，并通过单个 YAML 配置文件 mkdocs.yaml 进行配置。
开始使用：
bash
uv pip install -r requirements/docs.txt
提示
请确保你的 Python 版本与插件兼容（例如，mkdocs-awesome-nav 需要 Python 3.10+）。
MkDocs 自带一个内置的开发服务器，可以在你处理文档时实时预览。在仓库根目录下运行：
bash
mkdocs serve # 包含 API 参考（约 10 分钟）API_AUTONAV_EXCLUDE=vllm mkdocs serve # 关闭 API 参考（约 15 秒）
当你在日志中看到 Serving on http://127.0.0.1:8000/ 时，实时预览就准备好了！在浏览器中打开 http://127.0.0.1:8000/ 即可查看。
有关更多功能和高级配置，请参考：
- MkDocs 文档
- Material for MkDocs 文档（我们使用的 MkDocs 主题）
Testing 测试
vLLM 使用 pytest 测试代码库。
bash
安装 CI 中使用的测试依赖项（仅限 CUDA）
uv pip install -r requirements/common.txt -r requirements/dev.txt --torch-backend=auto
安装一些通用的测试依赖项（与硬件无关）
uv pip install pytest pytest-asyncio
运行所有测试
pytest tests/
对单个测试文件运行测试并输出详细信息
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。提交的 commit 必须包含 Signed-off-by: 标头，以证明你同意 DCO 的条款。
使用 -s 选项执行 git commit 将自动添加此标头。
提示
你可以通过你的 IDE 启用自动签名：
- PyCharm：在提交窗口中点击 Commit and Push... 按钮右侧的 Show Commit Options 图标。这将打开一个 git 窗口，你可以在其中修改作者并启用 Sign-off commit。
- VSCode：打开设置编辑器并启用 Git: Always Sign Off (git.alwaysSignOff) 字段。
PR Title and Classification 标题和分类
只有特定类型的 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 涉及多个类别，请包含所有相关前缀。
Code Quality 代码质量
PR 需要满足以下代码质量标准： - 我们遵循 Google Python 风格指南 和 Google C++ 风格指南。
- 通过所有 linter 检查。
- 代码需要充分文档化，以确保未来的贡献者能够轻松理解。
- 包含足够的测试，以确保项目的正确性和健壮性。这包括单元测试和集成测试。
- 如果 PR 修改了 vLLM 面向用户的行为，请向 docs/ 添加文档。这有助于 vLLM 用户理解并利用新功能或更改。
Kernels 添加或更改内核
当积极开发或修改内核时，强烈建议使用增量编译工作流程以获得更快的构建时间。每个自定义内核都需要一个模式以及一个或多个实现，并在 PyTorch 中注册。
- 确保自定义操作符遵循 PyTorch 指南注册：自定义 C++ 和 CUDA 操作符 和 自定义操作符手册。
- 返回张量的自定义操作需要元函数。元函数应在 Python 中实现并注册，以便自动处理动态维度。有关元函数的描述，请参阅上述文档。
- 使用 torch.library.opcheck() 测试任何已注册操作符的函数注册和元函数。有关示例，请参阅 tests/kernels。
- 更改现有操作符的 C++ 签名时，必须更新模式以反映更改。
- 如果需要新的自定义类型，请参阅以下文档：PT2 中的自定义类支持。
RFC 大型更改注意事项
请尽量保持更改简洁。对于重大的架构更改（>500 LOC，不包括内核/数据/配置/测试），我们期望有一个 GitHub 问题（RFC）来讨论技术设计和理由。否则，我们将会为其打上 rfc-required 标签，并且可能不会审查该 PR。
Reviewing 审查流程说明
vLLM 团队的目标是成为一个透明的审查机器。我们希望使审查过程透明高效，并确保没有贡献者感到困惑或沮丧。然而，vLLM 团队规模较小，因此我们需要优先处理某些 PR。以下是你可以期望的审查流程：
- PR 提交后，将被分配给一名审查者。每位审查者将根据他们的专业知识和可用性挑选 PR。
- 分配后，审查者将每 2-3 天提供一次状态更新。如果 PR 在 7 天内未被审查，请随时联系审查者或 vLLM 团队。
- 审查后，如果需要更改，审查者会在 PR 上打上 action-required 标签。贡献者应解决评论并联系审查者重新审查 PR。
- 请在合理的时间内回应所有评论。如果某个评论不清晰或者你不同意某个建议，请随时要求澄清或讨论该建议。
- 注意，由于计算资源有限，并非所有 CI 检查都会执行。当 PR 准备好合并或需要完整 CI 运行时，审查者会添加 ready 标签。
- 如果你不清楚 自己的PR 是vLLM团队谁负责审查。 可以进一步在 slack #pr-reviews 频道中发送你的PR。