vllm github documentation

多数人第一次用 vLLM，都是照着一段别人给的启动命令跑起来，能出结果就算完。等到要改并行度、调显存占用、换量化格式，或者报了个看不懂的错，才发现文档几百页不知道从哪翻。这篇不讲参数怎么填，只讲目录结构怎么读：哪几块是给部署的人看的，哪几块是给调参的人看的，遇到具体问题时该往哪个方向找。

多数人第一次用 vLLM，都是照着别人给的一段启动命令跑起来，能出结果就算完。等到要改并行度、调显存占用、换量化格式，或者报了个看不懂的错，才发现文档几百页不知道从哪翻。这篇不讲参数怎么填，只讲目录结构怎么读：哪几块是给部署的人看的，哪几块是给调参的人看的，遇到具体问题时该往哪个方向找。

先明确一件事：vLLM 的文档不是教程，更像一份按目的编排的说明书。它同时服务三类人——只想起个服务的人、要压性能的人、想改代码的人。所以你拿「从头读一遍」的思路去翻，多半翻到一半就迷失了。正确姿势是先判断自己属于哪一类，再跳进对应章节。

为什么 vLLM 的文档不好直接翻

它的内容按功能组织，不按读者角色组织。同一个目录里可能既有「怎么装」，也有「怎么改调度器」，还有「支持哪些量化格式」。你如果按顺序读，会在跟自己无关的章节里耗掉大量时间。

• 文档是给三类人同时写的：只想起个服务的人、要压性能的人、想改代码的人，三类内容混在同一套目录里
• 很多关键信息不在正文，而在示例配置、参数说明表和后端支持矩阵里，光看首页导读找不到
• 版本迭代快，网上搜到的步骤经常对应旧结构，必须先确认自己看的是当前分支的文档

先按目的分三堆，再决定翻哪里

与其问「文档在哪」，不如问「我现在要干什么」。下面这张对照表是整篇文章的核心，建议先存下来。

卡在中间的情况很常见：服务能起但吞吐上不去。这时候不要两边都翻，先确认服务侧没问题，再进性能侧。顺序反了会浪费很多时间。

部署路径怎么按顺序读

部署这件事，最怕跳过前面几步直接看启动命令。按下面这个顺序走，基本不会返工。

1. 确认硬件与后端支持范围先查硬件支持矩阵，看你的卡型和目标后端组合在不在列表里。不在，后面参数怎么调都白搭，先换方案。
2. 选安装方式容器镜像和源码安装两条路。不改代码就用镜像，要改调度或加自定义算子就源码装，别为了省事硬用镜像然后到处打补丁。
3. 跑通服务化启动示例把模型路径、端口、并行度三个参数先定下来，其余保持默认。先用最小可用配置打通，再谈优化。
4. 回头对接口文档确认客户端调用格式，尤其是有没有用 OpenAI 兼容接口。这一步决定你现有的业务代码能不能直接改个 base_url 接上去。

每一步做完都有明确的验证动作：支持矩阵看命中、安装看导入成功、启动看端口能应答、接口看返回结构对得上。任何一步没验证就往下走，问题会累积到后面。

调参路径怎么读，别一上来就改默认值

调参最常见的错误是没量基线就开始改。你不知道起始点的延迟和吞吐是多少，改完之后也判断不出有没有变好。

具体做法：先用现成的接口测速工具把当前配置跑一遍，记录延迟和吞吐两组数。这个基线是你后面所有对比的锚点，可以到站内工具目录找现成的测速工具，路径是 /tools/speed-test。

显存不够

看量化与显存相关章节，先确认能不能靠量化或降低并行冗余腾出空间

吞吐上不去

看批处理与并行章节，重点在批大小和并行策略的配合

单请求慢

看调度策略相关章节，延迟通常卡在调度粒度而不是算力

并发上限别凭感觉设。先用显存和并发的估算口径算一遍理论值，再拿实测校正。估算和实测差太多，说明有别的瓶颈没被识别出来，回到上表重新定位。

每次只改一类参数并记录下来，改完回到基线复测。一次改五项，涨了你也不知道是哪项起的作用，跌了更不知道回退哪个。

几个常见的阅读误区

• 把示例配置当推荐配置：示例通常是为了跑通，不是针对你的卡型和流量调过的
• 只看二手教程不看原始参数表：参数含义和默认值以官方说明为准，教程可能落后
• 忽略版本差异：同一条命令在不同版本上行为可能不同，读之前先确认文档对应的版本
• 遇到报错先搜模型名：多数报错和模型无关，和参数组合、卡型支持有关
• 拿别人的并发数直接用：流量模式和卡型都不一样，数值没有参考意义

例外情况也要说清楚：如果你只是本地跑通一个小模型做验证，上面的调参路径和矩阵核对都可以简化，跑通就行。但一旦要上生产、要接真实流量，这几步一步都不能省。