vLLM推理时显存不足调整gpu_memory_utilization参数的实测配置

vLLM 推理时报 CUDA out of memory，最快能调整的参数就是 `--gpu-memory-utilization`，它控制 vLLM 启动时预留多大比例的显存给 KV cache。调低这个值，模型权重和推理中间结果能拿到更多显存，但 KV cache 变小，能同时处理的并发序列数和最大上下文长度都会下降。所以这个参数不是越高越好，也不是越低越稳，需要结合当前 GPU 总量、模型大小和实际并发需求找到平衡点。

调整前先确认显存占用在哪

不要一上来就改参数。先用 nvidia-smi 看显存总量和占用情况，然后从 vLLM 启动日志里找记录 GPU memory usage 和 KV cache size 的部分。vLLM 启动时会显示它给 KV cache 预留了多大显存，这一行是判断当前水位最直接的依据。

nvidia-smi `--query-gpu`=name,memory.total,memory.free `--format`=csv

另外确认模型上下文长度是否设置得过大。`--max-model-len` 直接决定 KV cache 的上限，序列越长，单条请求占用的 KV cache 越多。如果这个值设置远高于实际需求，调低它比调低 gpu_memory_utilization 更有效。

调整 gpu_memory_utilization 的配置方式

通过命令行启动 vLLM 服务时直接传参，以 Qwen/Qwen2.5-7B-Instruct 为例：

vLLM推理时显存不足调整gpu_memory_utilization参数的实测配置

vllm serve Qwen/Qwen2.5-7B-Instruct \
    `--gpu-memory-utilization` 0.80 \
    `--max-model-len` 8192 \
    `--max-num-seqs` 16

在 Python 代码中初始化 vLLM 引擎时，传入同名参数：

from vllm import LLM

llm = LLM(
    model="Qwen/Qwen2.5-7B-Instruct",
    gpu_memory_utilization=0.80,
    max_model_len=8192,
    max_num_seqs=16,
)

需要注意：这三个参数是联动的，调整时别只动一个。下面的表格说明调整方向：

gpu_memory_utilization：调低给 KV cache 的显存比例，降低显存峰值，但可能降低并发吞吐。
max_model_len：调低能直接压缩单请求的最大显存占用，效果最直接，但会截断超长上下文。
max_num_seqs：调低限制同时处理的请求数，能控制显存峰值，但排队等待时间会变长。

通常建议从 0.90 开始往下调，每次 0.05 步进。注意先观察服务启动时日志中 KV cache 分配的显存大小，再通过请求验证稳定性。

验证调整是否生效

启动服务后观察日志中是否出现 OOM 报错，同时用 nvidia-smi 确认显存占用是否符合预期。显存占用应稳定在设定的比例附近，而不是启动后持续爬升到接近上限。

curl http://localhost:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{"model": "Qwen/Qwen2.5-7B-Instruct", "messages": [{"role": "user", "content": "你好"}], "max_tokens": 256}'

只发一个请求不够，还要用稍微高一点的并发量跑一轮，确认多请求同时到达时不会触发 OOM。注意，并发测试和持续运行时间要根据你的实际负载决定，不要只看单次请求成功就认为问题已解决。

调低后仍然 OOM 的回退策略

如果 gpu_memory_utilization 已经调到 0.70 左右仍然报显存不足，说明瓶颈不在 KV cache 预留比例，可能在于模型权重本身超过当前 GPU 容量，或者 CUDA graph 构建占用了过多显存。可以尝试：

进一步调低 `--max-model-len`，缩短上下文长度上限。
加上 `--enforce-eager` 关闭 CUDA graph，该选项会减少额外显存开销，但推理速度会变慢。
换用量化后的模型权重，例如 AWQ 或 GPTQ 格式，需要先确认 vLLM 版本支持。
如果以上都无效，说明这块 GPU 跑不动当前模型，考虑改用多卡加载或换大显存实例，不建议继续压低参数。

另一种情况是调低后服务不再 OOM，但响应明显变慢、排队明显变多。这时可以小幅度回调 gpu_memory_utilization，同时压低 `--max-num-seqs` 控制峰值，反复多试几组，最终取启动不报错、并发请求稳定的组合。

最后提醒一点：gpu_memory_utilization 调整的是 KV cache 的显存上限，不是总的显存上限。只要模型权重、CUDA context、KV cache 总和不超过物理显存，服务就能稳定跑。调整后务必观察稳定运行数分钟的显存变化，而不是只信启动时的日志。