vllm api_server 参数

你拿到一张卡、一个权重目录，准备用 vLLM 起个兼容 OpenAI 的接口，结果卡在参数上：模型路径怎么写、张量并行开几、显存吃到多少、上下文给多长、端口和鉴权怎么配。这篇不讲框架原理，只按启动顺序把常用参数分成几组，说清每组管什么、什么时候必须动、什么时候别乱动，并给出起服务后的第一轮验证动作。

你拿到一张卡、一个权重目录，准备用 vLLM 起一个兼容 OpenAI 的接口，结果第一步就卡在参数上：模型路径怎么写、张量并行要不要开、显存那个比例填多少、上下文给多长、端口和鉴权怎么配。这些参数之间是互相拉扯的，拍脑袋填完能起来，但一上量就出问题。

这篇不讲框架原理，只按启动顺序把常用参数分成四组：先定什么、再调什么、什么别乱动。每节给判断标准和动作，最后给一份起服务后的验证清单。核心原则一句话：先让服务能跑起来，再让服务跑得稳，最后才谈跑得快。

第一批必须定下来的参数：模型、并行、显存

模型路径: 本地权重目录用绝对路径最稳，写相对路径的话，服务工作目录一变就找不到；用远程仓库名时，注意权重是拉到本地缓存的，第一次启动会慢。
信任远程代码: 远程仓库里带自定义建模代码时才需要开这个开关；开了等于让它在你机器上执行代码，只对你确认过来源的仓库开，否则优先把权重要下来本地加载。
张量并行度: 它决定用几张卡、卡之间怎么切分。注意它和「一张卡放不放得下」是两个独立问题：先按权重体积算显存，放不下再谈并行，而不是一上来就上多卡。
显存占用比例: 这是给权重加 KV cache 划的总盘子，不是越大越快。填得太满会把同卡上其他进程挤掉，填得太小又跑不动长请求。

参数组	管什么	什么时候必须动	什么时候别乱动
模型路径 / 加载方式	服务从哪读权重	换模型、换权重格式、迁到离线机器	同一台机器上日常重启
张量并行度	几卡协作、怎么切分	单卡装不下权重，或要压单条延迟	单卡显存够用、只是请求量大（那是并发的事）
显存占用比例	权重加缓存的预算上限	同卡还有别的进程，或长请求频繁 OOM	服务独占整卡且负载稳定
数据类型 / 量化	权重以什么精度运算	权重本身就是低精度格式，必须匹配	权重是标准全精度且显存不紧张

一个新参数最容易被忽略的点是「数据类型与量化必须和权重本身匹配」。如果加载时报精度或字段对不上的错，先怀疑权重格式，而不是反复调并行度和显存比例——后者调不出正确结果。

服务形态参数：端口、鉴权、并发与排队

这一组决定服务能不能被外部安全地调用。监听地址和端口要一起看：只绑本机回环地址，就只有本机能连；绑到对外地址，容器外或局域网才能访问，但这时候必须先确认鉴权配到位，不能裸奔。

监听地址与端口：对外提供前先确认有没有开鉴权，没有就只绑本机，用反向代理或网关挡在前面。
OpenAI 兼容接口路径默认是开的，客户端改 base_url 就能接；但不是所有官方字段都被支持，业务侧要能兜住缺失字段。
并发相关参数和显存互相拉扯：同时处理的请求数、单批 token 上限调大，吞吐上去，单条延迟和显存峰值也跟着上去。
排队策略要提前定：高峰期是老老实实排队，还是快速拒绝并返回明确错误码。别等被打爆再临时改。

并发调大后	变好的地方	要盯的地方
吞吐量	单位时间处理的请求数上升	显存峰值跟着涨，逼近上限会 OOM
单条延迟	不一定变好，可能变差	长请求被短请求挤到后面，尾延迟拉高
错误率	不一定变好	排队超时、被拒绝的请求会变成业务侧报错

判断标准很简单：先跑基线再压测。同一组请求、同一批数据，改一个参数复测一次，只有能对比的数据才有意义。至于各参数在你这张卡上的典型表现，可以到站内的速度测试页面看当时的实测数字，别照搬别人的结论。

上下文与缓存：别让长 prompt 把显存吃穿

最大上下文长度是最容易被无脑拉满的参数。它不是「越大越好」：显存里的 KV cache 占用大致按「上下文长度 × 并发数」放大，你把两边都拉高，显存就会穿。

先按场景定上下文统计真实请求的输入长度分布，取覆盖大多数请求的长度，而不是直接填上限。个别超长请求单独走别的通道或提前截断。
再按并发反推显存用「上下文长度 × 预期并发」估 KV cache 占用，加上权重体积，和卡的实际显存对一下。对不上就降并发或降上下文，别硬扛。
分页缓存开关看业务长文本、变长请求多的场景建议开，能减少内存碎片；短请求为主、长度很均匀的场景收益不明显，可以先不开，观察后再决定。
缓存复用看前缀重复率多轮对话、固定系统提示词的场景命中率高，值得开；如果每条请求前缀都不一样，开了也基本不命中，先看日志里的命中情况再决定。
超长输入行为要明确是截断还是直接报错，上线前定死。不定的后果是前端看到莫名报错、后端日志里却什么都没有，排查起来最费时间。

上下文长度、并发数、显存占用是三个绑在一起的数，动一个就得回头核另外两个。

起服务后的十分钟验证清单

参数填完启动成功，只是第一步。真正能省事的做法是每次起服务都跑同一套验证动作，把结果记下来，后面出问题才有基线可比。

打健康检查与模型列表确认服务真的起来了、对外暴露的模型名和你预期一致。这步不过就别接业务，先查监听地址、端口和模型路径。
发一条极短请求测通完整链路，记录首 token 延迟和整体耗时，作为后续调参的基线。以后改任何参数，都拿同一条件复测。
压一轮并发观察显存是否随并发上涨、有没有出现排队或拒绝。显存逼近上限就先降并发，而不是先加卡。
检查日志里的关键信息确认权重是按预期精度加载的、缓存命中情况如何、有没有反复出现的告警。日志里的异常比接口返回更早暴露问题。
把参数固化下来写进启动脚本或容器编排文件，别只留在命令行历史里。换机器、换卡型时按同一份清单重跑，才能复现同一套行为。

如果你的场景是多家供应商或中转站混用，那参数核对之外还要确认接口行为一致：字段支持范围、错误码、超时策略都可能不一样。这部分可以到站内的中转站检测和工具目录页面按当时的检测结果核对，别默认所有兼容接口行为都相同。

对照站内资料再确认一遍参数清单有了，但同一张卡、不同权重在不同版本的框架上表现会变。到价格追踪与模型资料库页面核对当时的记录，再回到你的启动脚本里改，比照着别人的博客抄参数靠谱。

常见问题

参数调完效果不好，最该先怀疑哪个？

先怀疑显存余量不够导致的降级，再怀疑上下文长度设太大把 KV cache 吃满。这两个占绝大多数。排查顺序是：先看显存峰值，再压并发看延迟曲线是否突然变陡，最后才去动并发和批处理相关参数。

一张卡跑不动，是该减上下文还是开张量并行？

先减上下文和并发，这两项对显存的弹性最大，且不用加卡。减完还是不够，再考虑量化权重。张量并行是跨卡方案，它解决的是单卡装不下权重的问题，代价是卡间通信开销，能用单卡就别上。

启动参数要不要做成配置文件？

建议做成一份带注释的启动脚本或容器编排文件，和环境一起进版本管理。理由不是好看：同一套参数要在不同机器上复跑，命令行历史最容易漏参数，出问题时也无法对比改动前后差异。具体数值按你的卡型到 /models/deploy 重新算一遍。