vLLM 部署：显存需求估算与批处理配置

显存需求要先拆成权重、KV Cache、CUDA graph 与其他运行时占用，再用上下文长度和批处理上限约束容量。根据并行与扩展文档，启动后可在 vLLM 的日志中找到 GPU KV cache size：它表示 GPU KV Cache 同时可容纳的 token 数，可用来校准估算并指导后续调整。

部署前先写出容量边界

先记录每个实例可见的 GPU 数量、单卡物理显存、模型名称、实际权重精度、最大上下文、目标并发和单轮 token 上限。租用 GPU 时，这些值应取自实例配置；主机内存、容器限额与单卡显存不能混为一谈。

显存估算要分清权重、缓存与余量

可用下面的公式做首轮容量筛选：

总显存规划值 = 权重占用 + KV Cache + CUDA graph 与运行时余量
权重占用 = 参数量 × 每参数字节数
KV Cache 规划值 = 每 token 的 KV bytes × 活跃 token 数
活跃 token 保守上限 = max_num_seqs × max_model_len

这些是容量规划式，不是精确的显存保证值。权重项应按实际精度填写，不要套用未经模型配置确认的固定换算系数。Serve 参数参考列出的 --dtype 取值包括 auto、bfloat16、float、float16、float32 和 half；其中 auto 对 FP32、FP16 模型使用 FP16，对 BF16 模型使用 BF16。

官方显存优化说明指出，CUDA graph 默认开启并占用额外 GPU 内存，降低 max_model_len 或 max_num_seqs 可以进一步减少内存；--enforce-eager 可完全关闭 graph capture。如果需要直接限定 KV Cache，按CacheConfig 源码设置 kv_cache_memory_bytes，该值会覆盖 gpu_memory_utilization 的作用。

安装并启动 vLLM 服务

官方快速入门要求 Linux 和 Python 3.10 至 3.13；其环境创建与安装命令如下，其中 --torch-backend=auto 会检查已安装的 CUDA driver 版本并选择 PyTorch index：

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

先用文档中的单模型命令完成基础启动：

vllm serve Qwen/Qwen2.5-1.5B-Instruct

确认基础服务可用后，再加入容量参数，避免把安装问题与调参问题混在一起排查。

批处理参数这样配

在Serve 参数参考中，--max-model-len 是输入与输出合计的上下文长度，--max-num-seqs 限制单轮处理的序列数，--max-num-batched-tokens 限制单轮处理的 token 数；--gpu-memory-utilization 是 model executor 使用的显存比例，默认值为 0.92，并且只对当前实例生效。

可按规划值启动：

vllm serve Qwen/Qwen2.5-1.5B-Instruct \
  --dtype YOUR_VALUE \
  --max-model-len YOUR_VALUE \
  --max-num-seqs YOUR_VALUE \
  --max-num-batched-tokens YOUR_VALUE \
  --gpu-memory-utilization YOUR_VALUE

客户端并发数不等于 max_num_seqs；后者约束的是一次调度迭代处理的序列数。官方优化与调优文档给出了明确取舍：较小的 max_num_batched_tokens，例如 2048，有利于 token 间延迟；较大的值有利于首 token 时间；追求吞吐量时，文档建议设为 max_num_batched_tokens > 8192，尤其是小模型使用大 GPU 时。应先按你最重视的指标填写，再结合启动日志校准。

单卡不够时再切分

按显存优化说明，应通过 CUDA_VISIBLE_DEVICES 选择设备，而不是在启动前调用 PyTorch device functions；启用 tensor parallelism 后，每个进程仍会读取完整 checkpoint，磁盘加载时间会随并行规模增长。

根据并行与扩展文档，tensor_parallel_size 在每层内切分模型参数，是单机常见方式；pipeline_parallel_size 则把不同层放到不同 GPU 并依次处理。多节点部署的文档经验是：tensor_parallel_size 对应每个节点的 GPU 数，pipeline_parallel_size 对应节点数。

单节点可以采用下面的参数模板：

CUDA_VISIBLE_DEVICES=YOUR_VALUE \
vllm serve Qwen/Qwen2.5-1.5B-Instruct \
--tensor-parallel-size YOUR_VALUE

将两个 YOUR_VALUE 分别替换为实例实际可见的设备标识和并行规模，不能用整机总显存代替单卡预算。

启动后如何验证

快速入门规定服务默认监听 http://localhost:8000，一个服务进程一次承载一个模型，并给出了模型列表请求：

curl http://localhost:8000/v1/models

把返回的模型列表与启动日志中的 GPU KV cache size 一起检查。如果日志给出的 KV token 容量明显低于规划上限，应重新核对权重精度、上下文长度、序列上限和批 token 上限，再观察业务请求中是否仍发生抢占与重算。

常见配置错误

官方优化与调优文档说明，KV Cache 空间耗尽时可能抢占请求，并在空间恢复后重新计算；未固定 kv_cache_memory_bytes 时，文档先建议提高 gpu_memory_utilization，再建议降低 max_num_seqs 或 max_num_batched_tokens。同一说明还指出，--enforce-eager 以稳定状态 decode 性能换取更快启动；关闭 chunked prefill 时，max_num_batched_tokens 必须大于 max_model_len。

本文步骤按正文链接的官方文档整理，未做运行或性能测量；使用前应按当前版本复核。

资料来源

• 官方快速入门
• 显存优化说明
• Serve 参数参考
• CacheConfig 源码
• 优化与调优文档
• 并行与扩展文档