我一直觉得，vLLM Serve 的入门门槛不在安装，而在启动参数怎么排布。默认配置能跑通 demo，可一放到生产环境，显存爆了、吞吐上不去、长文本请求把短文本请求全拖死，这些问题十有八九都出在参数没理解透。这篇文章从实际部署经验出发，把 vLLM Serve 启动参数里最影响业务的几组拆开讲清楚：显存怎么留、并发怎么控、多卡怎么切、精度怎么省。每个参数我都会说清“它管什么、为什么这么管、实际怎么调”，有计算过程，也有踩坑记录，适合刚接触 vLLM 的读者，也适合已经上线但还想继续压性能的人。
1. 显存是 vLLM 部署的命门：内存管理参数
vLLM 的看家本领是 PagedAttention，它把 KV Cache 切成小块，按需分配，极大减少了显存碎片。但也正因为 KV Cache 是动态的，显存怎么预分、分给谁，全靠启动参数控制。这一组参数搞不明白，后面所有调优都是空中楼阁。我见过太多人把 gpu-memory-utilization 调到 0.98 图省显存，结果压测一跑就 OOM，反而怀疑框架有问题。实际上，这块显存不是越多越好，而是要留出足够的运行余量。
1.1 gpu-memory-utilization：显存利用率的边界怎么找
这个参数控制 vLLM 最多使用多少比例的 GPU 显存，默认是 0.9，即 90%。很多人以为剩下的 10% 是浪费，其实那部分空间要留给 GPU 驱动上下文、模型权重加载时的临时缓冲、前向计算产生的激活值，以及图执行优化预分配的显存。如果把这些都吃掉，一旦运行时有峰值分配请求，就直接 OOM。所以在生产环境里，我一般建议从 0.85 起步，压测稳定后再逐步往上探，而不是一上来就 0.95。
怎么找这块区域的边界，我常用的方法是：先用 0.9 启动，设一个较小的 max-num-seqs 让服务能跑起来，然后观察启动后显存占了多少、空闲还剩多少，再逐步把 gpu-memory-utilization 往上加，每加一次就跑一轮满载压测，看有没有 CUDA out of memory 或图执行相关的分配失败报错。如果压测半小时没出问题，这个值就算站住了；如果偶发 OOM，宁可往回调 0.02-0.03，也别赌“概率低就无视”。
另一个容易忽略的点是显存总容量。同样是 0.9，24G 显卡和 80G 显卡的绝对余量差很多。24G 卡上 0.9 意味着只有约 2.4G 的缓冲，稍微跑个长上下文就可能不够；80G 卡上 0.9 则有 8G 缓冲，从容得多。所以显存越小的卡，越要保守。你甚至可以反过来思考：如果模型权重大到基本把显存占满，留给 KV Cache 的空间所剩无几，那并发和上下文长度根本抬不起来，这时候合理的做法不是继续调利用率，而是换量化模型或者多卡并行。
1.2 max-model-len 与 KV Cache 的博弈
max-model-len 表示模型允许的最大上下文长度，也就是输入加输出的总 token 数上限。默认值会从模型配置里读取，但很多开源模型的配置非常激进，动不动就写 128K、256K，如果你按默认来，KV Cache 预算会被直接吃穿，导致能同时处理的请求数骤降。
KV Cache 的大小有一个很直观的计算公式：单条序列在某个上下文长度下所占的显存，约等于 2（K 和 V 两份）乘层数乘 KV 头数乘头维度乘序列长度乘每个元素的字节数。举个例子，假设某模型有 80 层、每层 8 个 KV 头、头维度 128，用 bf16 存储，那么 2048 个 token 的 KV 大约是 2 × 80 × 8 × 128 × 2048 × 2 字节，算出来约 0.64G。如果上下文从 2K 涨到 32K，这个数字就变成 10G 以上，涨得非常快。这也是为什么长上下文场景下，KV Cache 才是真正的显存大头，而模型权重反而是固定成本。
所以 max-model-len 和并发是联动的。你把上下文长度设大，腾给每个序列的 KV 空间就大，能同时跑的序列就少；反过来，把长度压缩到业务刚需，比如普通对话 16K 或 32K 就够，剩下大量显存可以给更多并发序列，整体吞吐反而上升。我遇到过一个业务，客服场景最多对话十几轮，模型原本配了 128K，我直接把 max-model-len 压到 32K，并发从 30 涨到 120，延迟还降了，这就是“上下文缩一缩，吞吐翻一番”的实践。唯一需要注意的，是别压到连业务峰值都覆盖不了，否则超长输入会被直接截断或报错。
1.3 enforce-eager：图优化要不要强制关闭
enforce-eager 是个容易被忽略但偶尔能救命的参数。vLLM 默认会启用 GPU 底层的图执行优化，把 decode 阶段那些细碎的小算子合并成固定图结构执行，减少内核启动开销，显著提升推理速度。但代价是：构建图需要额外显存，而且遇到图形状变化时可能要重新构建。如果显存已经紧到启动就报分配失败，或者频繁触发重建导致运行时延抖动，你可以在启动命令里加 --enforce-eager 强制走即时执行模式，牺牲一部分吞吐来换取稳定性和更低的基础显存占用。
我在单卡部署量化大模型时用过这个参数。当时模型权重几乎把显存占满，默认模式一启动就报错，加 --enforce-eager 后服务能正常起来，虽然吞吐低了一些，但总比完全不能用强。等后续换了更大的显卡或者换了更省显存的量化方案，再把这一项去掉即可。记住它是个“应急开关”，不是“默认优化项”。如果你的显存比较宽松，图优化带来的吞吐收益是实打实的，没必要为了参数简洁强行关闭。
2. 吞吐与延迟的平衡：调度参数怎么选
vLLM 的核心调度机制是连续批处理，也叫 continuous batching。传统静态批处理要等整批序列全部结束后再换下一批，GPU 空转严重；vLLM 则是在每一步都动态决定哪些序列继续解码、哪些新请求的 prefill 可以插进来，GPU 利用率因此高很多。但动态调度的“松紧度”是由几个启动参数决定的。参数太松，GPU 想要效率但显存不够；参数太紧，请求全被卡在队首，延迟一路飙升。这一章讲清楚这里面的取舍。
2.1 max-num-seqs：并发上限背后的显存账
max-num-seqs 限制的是同一时刻最多有多少个序列同时参与生成。这个值直接关系到两条线：一是显存里 KV Cache 够不够分，二是 GPU 的算力能不能被充分喂饱。很多新手把这个值调得特别大，以为并发高吞吐就高，实际上当序列数量远超 GPU 实际能力时，每个序列每个 step 只产生一个 token，矩阵碎片化严重，吞吐反而下降，延迟却一路走高。
我在压测里见过很有趣的现象：把 max-num-seqs 从 128 提到 256，吞吐还在涨；再提到 512，显存没爆，但总吞吐基本持平；到 1024，延迟直接翻倍，每秒完成请求数反而掉了。原因是 GPU 的并行能力是有限的，大量的短序列会让计算单元频繁切换上下文，调度开销也变大。这就像餐厅里翻台率不是只靠桌位多，厨师炒菜的速度才是瓶颈。实操上，我建议先给一个模型按它显存能支撑的并发上限粗算，再通过压测逐个档位试，观察总吞吐和响应延迟的交叉点，那个点通常就是最优 max-num-seqs。新版 vLLM 会根据显存自动推算初始值，但自动值往往偏保守，手动压测校准仍然是值得做的。
2.2 max-num-batched-tokens 与 chunked prefill
max-num-batched-tokens 决定每一个调度轮次里最多送入多少 token。它直接限制了一次批量计算的规模。如果这个值设得太小，GPU 每次吃进去的矩阵太小，利用率上不来；设得太大，调度轮次变长，早到的请求要等后面的大批 token 攒齐，延迟会上升。更关键的是 prefill 和 decode 混跑时的表现。
默认情况下，vLLM 会把完整的 prefill 当作一个整体来执行。如果进来一个长文档请求，它可能一口气吃掉 32K token，这时候其他短请求的 decode 全部被阻塞，等它算完才能继续，这就会导致长文本请求拖垮整体延迟。解决方法是 --enable-chunked-prefill，它允许把一条长序列的 prefill 拆成多个小块，穿插在 decode 步之间执行。打开之后，prefill 不再独占整个调度周期，p99 延迟会明显变稳，混合负载下的总吞吐通常也是提升的。
这个参数的玩法有点像单片机里的“时间片轮转”。我实际的配置习惯是：短对话为主的业务，max-num-batched-tokens 可以放到 4096 以上，prefill 次数少，矩阵计算更饱满；知识库、长文档场景则开 chunked prefill，并把 batched tokens 控制在 1024 到 2048，让长 prefill 被切碎后均匀混入 decode，避免队头阻塞。压测时注意同时看首 token 延迟和总吞吐，别只看一个指标。
2.3 连续批处理与传统排队：抢占和 swap 机制
连续批处理不是无限吸纳请求。当新请求进来，KV Cache 不够分时，vLLM 需要决定哪些序列被暂时挂起。这里面有两种处理方式：一是把序列的 KV 状态换出到 CPU 内存，叫 swap；二是干脆丢弃它的状态，等之后重新执行 prefill，叫 recompute。swap 空间大小由 --swap-space 控制，默认约 4G 的 CPU 内存。
很多人在碰到显存不足时第一反应是把 swap-space 调大，我不太支持这个做法。CPU 换出换入的速度和显存差几个数量级，一旦频繁发生 swap，吞吐会断崖式下跌，服务从“慢”变成“卡死”。swap-space 更像是一个兜底机制，防止极端流量瞬间把系统打挂，而不是用来承载正常业务的。正常调优时，如果监控日志里出现大量 swap 事件，优先怀疑的是 max-num-seqs 太大、max-model-len 太大，或者是 gpu-memory-utilization 给得太低，先解决根因，再考虑把 swap-space 调回合理值。与其靠 swap 续命，不如从源头减少“同时活着”的序列数，或者用下一章说的量化手段压缩 KV 体积。
3. 单卡到多卡：并行参数的完整拆解
当单张显卡装不下模型，或者单卡吞吐不满足业务压力时，就得上并行参数。vLLM 支持张量并行和流水线并行两种模式，对应 --tensor-parallel-size 和 --pipeline-parallel-size。这两个参数决定了模型怎么切、数据怎么流、卡间通信多频繁。并行配置错了，轻则性能不如单卡，重则直接起不来。
3.1 tensor-parallel-size 的选择逻辑
张量并行是把每一层权重矩阵切分成 N 份，放到 N 张卡上，计算时每张卡各算一块，再通过卡间通信把结果拼起来。它在每步前向和反向（如果是训练）都需要做全量聚合通信，因此对卡间互联带宽要求极高。如果你所在环境的卡间是高速互联（比如 NVLink 这类），TP=8 基本都是高效的；如果只是普通 PCIe 互联，TP=8 的通信开销可能吃掉大半收益，性能甚至不如 TP=2。
我的经验是：能一张卡塞下，就不要开 TP；一张卡塞不下，先考虑量化，再考虑 TP；TP 有 2、4、8 的档位，能选 4 就别选 8，能选 2 就别选 4，并行度越高，通信占比越大，收益越递减。举个例子，70B 级别的稠密模型，bf16 权重约 140G，3 张 80G 的卡理论装得下但只能开 TP=4，第四张卡空着；但如果用 4bit 量化，权重降到 35G 左右，单张 80G 卡就能跑。这里头的取舍，实际上是通信成本和显存成本之间的权衡。启动命令里只需要指定 --tensor-parallel-size N，vLLM 会自动把权重均匀加载到 N 张卡上。
3.2 pipeline-parallel-size 与大模型跨节点部署
流水线并行是另一种切法：把模型按层切成多段，每张卡负责一段，数据像流水线一样按层顺序经过各张卡。它最大的优点是卡间只需要传每一层的中间激活值，通信量远比张量并行小，所以非常适合跨节点部署。但缺点也很明显：因为层是串行执行的，一条数据在流水线上“流动”时，后面的卡会有一段空闲气泡，需要靠 micro-batch 把气泡填上，这会增加实现的复杂度和首 token 延迟。
跨节点场景里，我建议优先把 TP 控制在单个节点内部，用 PP 跨节点。典型做法是一台 8 卡机器内部做 TP=8，两台机器之间用 PP=2，这样节点内是高速互联，节点间只传少量中间激活，整体效果远好于 TP 直接横跨两台机器。如果你的模型在单节点内也放不下，那就得考虑 TP（节点内）和 PP（节点间）同时启用。需要注意的是，PP 的比例要尽量让各段计算量均衡，否则显存占用和计算时间都会失衡，有的卡很闲、有的卡在跑满。
3.3 多卡部署的显存均衡与通信约束
多卡部署时，显存利用率不是简单相加就能算准的。首先，张量并行下，模型权重是均匀分布在每张卡上的，但实际上每一层的中间激活、KV Cache 的分布也会占用显存，这些在模型结构不对称时可能出现偏斜。其次，图优化模式会在每张卡上额外预留构建图的显存，并行度越高，这部分总量越多。所以多卡启动时，建议把 gpu-memory-utilization 稍微调低一点，比如 0.85，给通信缓冲和图构建留足空间。
另一个容易踩的坑是显存型号混合。不同型号、不同显存容量的卡混插时，vLLM 会按最小的卡来匀权重，大卡的剩余空间会被浪费，整体部署成本不降反升。除非显存容量完全一致，否则我不建议混插异构卡做 TP。跨机部署还要求共用模型文件的存储路径、版本一致的驱动和镜像，我还遇到过节点间时间不同步导致分布式初始化失败的问题，这类环境因素排查起来比调参本身更耗时。
4. 精度与量化：权重和 KV Cache 怎么省显存
显存不够时，第一反应不该是降并发，而是压缩模型和 KV 的体积。vLLM 在精度控制上有两个层面的参数：模型权重的精度和 KV Cache 的精度。很多人只关注前者，忽略了后者，导致 KV 占了大半显存还不自知。这一章把两条线都讲透。
4.1 dtype 参数：auto、half 还是 bf16
启动参数 --dtype 控制模型权重的加载精度，默认 auto，即读取模型里保存的精度配置。目前主流模型大多用 bf16 或 fp16 发布。这两个格式的显存占用一样，都是每个参数 2 字节，但适用范围不同：bf16 的动态范围更大，数值稳定性更好，部分较新的加速架构对它有高效的执行支持；fp16 在一些老架构上更通用。如果显存稍微紧张，也可以尝试把权重加载为 8bit 或 4bit 的量化格式，但那需要配合量化参数，不是 dtype 单独能解决的。
有个常见误解是“fp32 精度最高，所以默认配置更稳”。没这回事。fp32 的显存是 bf16 的两倍，计算也慢，除非你的场景对精度有极端要求，否则生产环境老老实实用半精度。我在代码审查里经常看到有人把 dtype 显式写成 float32，多半是照着教程抄的，但并不知道自己在付出什么代价。对推理来说，模型训练时大部分就是半精度，推理继续用半精度完全足够。
4.2 量化参数：AWQ、GPTQ 与 FP8 的落地差异
vLLM 支持的量化方案主要有 AWQ、GPTQ、FP8 这几类，通过 --quantization 指定。需要特别强调的是，这个参数只是告诉推理引擎“该模型权重是按什么量化方式打包的”，并不负责把原模型“现场量化”。也就是说，你得先有对应格式的量化权重，比如从模型仓库下载 AWQ 版或 GPTQ 版权重，然后用 vLLM 加载，才能正确反量化推理。如果你拿原版 fp16 权重却指定 --quantization awq，大概率直接报错或输出乱码。
AWQ 和 GPTQ 都是 4bit 级别的经典量化方案，区别在于后者在量化时会按列做误差补偿，前者会更关注激活值的分布。实际效果都很好，常见场景下 4bit 量化与 16bit 的精度差距几乎不可感知，但显存占用只有四分之一。FP8 则属于新一代格式，要求显卡本身支持对应计算特性，但它是 8bit，显存减半、精度损失很小，性能通常也不错。落地时优先看模型仓库有没有现成的量化权重，其次再考虑自己量化，不要从零折腾量化工具链，除非你有很强的定制需求。
4.3 kv-cache-dtype=fp8：长文本场景的显存外挂
很多人不知道 vLLM 还有一个 kv-cache-dtype 参数，可以单独把 KV Cache 的存储精度改成 fp8。默认情况下 KV 和模型权重同精度，是 bf16/fp16，占 2 字节；改成 fp8 后占 1 字节，KV 显存直接减半。这在长上下文场景里收益极大，因为 KV 是随 token 数量线性增长的，上下文越长，省下来的显存越多。
我在处理一个知识库问答业务时，模型权重只占不到 30% 显存，剩下 70% 全被 KV 吃掉了。当时把 kv-cache-dtype 设置成 fp8，相同的显存预算下，可承载的并发序列数几乎翻倍，而且因为单序列 KV 变小了，调度上更充裕，吞吐也有提升。代价是 KV 精度下降带来的效果损失，但实测在对话和检索场景里几乎无感。这里有个前提：显卡需要支持 fp8 计算。老卡开了这个参数可能会回退或者报错，上线前一定要验证。如果业务是超短对话、上下文只有几百 token，KV 占比很小，开 fp8 的意义不大，反而白白损失精度。
5. 对外服务参数：接口、命名与可观测性
模型跑起来了，接下来的问题是给别人用。vLLM Serve 会启动一个兼容主流大模型 API 格式的 HTTP 服务，对外提供 /v1/chat/completions 这类接口。这里面的参数看似简单，但命名、鉴权和日志处理不好，上线后也会出乱子。尤其是多模型共存、多人调用、压测观察这类场景，服务参数的合理配置能省掉不少沟通成本。
5.1 served-model-name 与 API 鉴权
--served-model-name 是服务对外暴露的模型名，request 里填的名字要和它一致。默认情况下，vLLM 会拿模型路径的最后一段当作服务名，比如启动参数 --model /data/models/chat-8b-instruct，对外名字就变成 chat-8b-instruct。这在单模型部署时没问题，但如果你在同一套网关后面挂多个模型服务容器，必须给每个容器显式指定一个不冲突的名字，否则客户端容易把请求发错到另一个模型上。
生产环境还有一个经常被忽略的参数 --api-key。vLLM 默认不校验请求鉴权，裸奔在网络上特别危险。设置之后，客户端请求头里必须带 Bearer Token 才能访问接口，这能挡住绝大多数误用和恶意调用。密钥本身我建议从环境变量读取，不要明文写进启动脚本；日志里也不要打印完整的请求头，防止密钥泄露。这是我在多个团队里反复强调的底线：模型接口一旦谁都能调，消耗的不只是算力，可能还有合规风险。
5.2 日志、采样与可观测性参数
vLLM 在服务端会记录每个请求内容和响应内容，这在调试时有用，但压测阶段会被刷屏，日志吞吐反而成为瓶颈。用 --disable-log-requests 可以直接关闭每请求日志，只保留启动信息和统计信息，压测环境我基本必开。如果你还是想保留部分请求日志，新版一般也有日志长度限制的参数可用，不影响正文太长被刷出去的问题。
另外，服务端本身不负责限制客户端的采样参数。比如 temperature、top_p 这些由客户端在请求体里传，所以你想在服务端统一压采样、控制随机性，通常得在网关层做参数校验，或者让客户端方遵守约定。vLLM 的职责是把请求安全、高效地调度到模型上，而不是替你做业务策略。这一章的内容其实再次说明一个问题：vLLM 的很多“服务参数”是把分布式系统里你原本要自己实现的东西包好了，理解它、善用它，才能让整条推理链路更快更稳。
6. 实战调参：常见问题与排查记录
参数全部介绍完，下面进入实战篇。我在这部分整理了大家在部署 vLLM 时最常遇到的几类问题，每个问题都给出排查路径和实际解决过的方案。这些场景几乎每天都在发生，也是我认为比背参数更有价值的经验。
6.1 启动或运行阶段的显存不足排查
表现有两种：启动阶段报显存分配失败，或者压测跑到一半突然 OOM。启动阶段失败，大概率是 gpu-memory-utilization 给太高，或者图优化预留显存不够。先把参数回落到 0.8，再逐步往上探；如果 0.8 都不行，那可能不是参数问题，而是模型权重本身超出了单卡容量，需要走量化或并行。运行阶段 OOM，多发生在 KV 预算被长请求挤爆的时刻，优先检查 max-num-seqs 和 max-model-len 是不是对不上业务流量。
我的排查顺序是：先看启动后的基础显存占了多少，再算单个序列平均占用多少显存，然后把并发乘以单序列占用，和剩余显存做对比。如果理论上能放下但实际 OOM，再看是不是长尾请求特别长，把平均预算吃穿。这时候要么调小 max-num-seqs，要么开 kv-cache-dtype=fp8，要么缩 max-model-len，三选一或都做。最忌讳的是直接无脑加 swap-space，那只是把显存问题挪到了 CPU 内存，劣化更隐蔽。
6.2 吞吐上不去的参数组合拳
GPU 利用率低、吞吐上不去，最常见的原因是单次送入的 token 太少。先看 max-num-seqs 是否被默认值限制住了；再看 max-num-batched-tokens 是否太小。如果你跑的是短文本高频调用，但 max-num-batched-tokens 只有 512，GPU 大量时间在等待攒 token，利用率自然上不去。可以调大到 4096 或更高再看。另外，如果每个请求本身很短，某些框架优化默认配置不一定是最优的，要自己去压测校准。
另一个隐藏因素可能就是日志刷屏。开着每请求日志时，压测阶段大量请求日志会把磁盘和 CPU 都拖慢，这也容易造成吞吐上不去的假象。把 --disable-log-requests 打开，再测一遍，往往差距明显。最后一点，图和连续批处理的开关以及前缀缓存参数也会配合影响吞吐。如果业务里大量请求有相同的系统提示词或长前缀，开启 --enable-prefix-caching 可以复用已有 KV 计算，省下的就是真金白银的算力。
6.3 延迟抖动与排队超时的处理
p99 延迟忽高忽低，通常是长 prefill 阻塞短 decode 引起的。开启 chunked prefill 是第一步；第二步是检查 max-num-batched-tokens 的大小，因为大小决定了 prefill 块能占多少时间片。块太大，长请求照样阻塞；块太小，调度太频繁，吞吐掉。这里适合用“阶梯压测”的做法：固定并发，把 batched tokens 从 512、1024、2048、4096 各跑一轮，画一条延迟和吞吐随参数变化的曲线，取哪个值能同时满足 p99 目标和总吞吐。不要凭感觉定。
如果服务已经出现大量排队超时，说明承载能力确实到了上限。此时优先排查是不是并发数虚高、无效占用太多，把 max-num-seqs 降到合理区间。客户端侧的超时重试也要配合设置，比如把超时设成比该请求平均完成时间多 1.5 倍，避免无意义的快速重试把服务打爆。实际部署里，有一半的“服务不稳定”其实是客户端疯狂重试导致的雪崩，这种问题调参数反而没用，得在网关层做限流和熔断。
最后说一点个人体会
vLLM Serve 的参数调优没有一劳永逸的模板，每次换模型、换显卡、换业务负载，我都把上面这些参数当成积木重新拼一遍。很多参数看着是性能开关，本质上是一笔显存和延迟的账。我现在上线任何模型，都会先准备一套包含 gpu-memory-utilization、max-num-seqs、max-num-batched-tokens 的基准压测脚本，不改业务只改参数，记录两条曲线再上岗。这套方法比反复抄网上的配置可靠得多，磨刀不误砍柴工，也推荐你试试。
