AI Deploy大模型本地部署帮你部署

vLLM 长上下文部署与显存调优

说明如何启动服务并配置长上下文上限、批处理边界与 GPU 显存比例，同时依据 KV cache 日志、请求抢占和多卡并行参数定位容量问题。

vLLM 的长上下文部署，核心是用 max_model_len 限制模型上下文，并用 max_num_seqs 降低最大批大小来减少显存；单卡仍不够时，再评估多卡并行（见显存管理文档）。不要只追求更大的上下文值，而应先确定业务必需的上下文边界，再让上下文长度、批并发和 KV cache 容量相匹配。

部署前要确认 GPU 与并行方式

按GPU 安装文档，服务不原生支持 Windows，Windows 应使用兼容的 WSL 发行版；NVIDIA GPU 的 compute capability 需为 7.5 或更高，预编译包包含 C++ 与 CUDA 12.9 二进制。若 CUDA 版本不同或要复用现有 PyTorch，则需从源码构建，并使用 GCC/G++ 11.3 或更高版本。

按并行与扩缩容文档，单节点大型模型推理通常使用 tensor parallelism，在每层内把参数切到多张 GPU；pipeline parallelism 则把不同层放到不同 GPU 顺序处理。多节点时，可将 tensor_parallel_size 设为每个节点的 GPU 数，将 pipeline_parallel_size 设为节点数；同一节点没有 NVLINK 时，例如 L40S，文档建议使用 pipeline parallelism 以降低通信开销。启动日志中的 GPU KV cache size 表示 GPU KV cache 一次可存储的 token 总数。

安装并启动 vLLM 服务

按快速入门文档，基础环境是 Linux 与 Python 3.10–3.13。下面创建全新的 Python 3.12 环境，由 --torch-backend=auto 检查已安装的 CUDA driver；启动时省略 --host 和 --port，服务地址为 http://localhost:8000，且一个服务进程同一时间只承载一个模型。

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

启动时，可把引擎参数放在 vllm serve 后，具体定义以服务命令参考为准：

vllm serve YOUR_VALUE \
  --max-model-len YOUR_VALUE \
  --max-num-seqs YOUR_VALUE \
  --max-num-batched-tokens YOUR_VALUE \
  --gpu-memory-utilization YOUR_VALUE \
  --tensor-parallel-size YOUR_VALUE \
  --pipeline-parallel-size YOUR_VALUE

第一个 YOUR_VALUE 填模型名，其余值按业务上下文、并发规模和上节的并行规则填写，不要原样使用占位符。

显存调优：四个参数如何配合

按上述服务命令参考，max_model_len 是提示词与输出合计的上下文长度；不设置时会从模型配置推导。max_num_seqs 限制单次迭代处理的序列数，max_num_batched_tokens 限制单次迭代处理的 token 数。gpu_memory_utilization 是模型执行器使用的显存比例，范围为 0 到 1，不指定时默认是 0.92，并且它只是当前实例的限制。

实际配置时，先为 max_model_len 设置业务必需的硬上限，再依据并发量决定 max_num_seqs 和 max_num_batched_tokens。降低 max_model_len 与 max_num_seqs 都能减少内存占用；不要把 gpu_memory_utilization 当作同一 GPU 上所有实例共享的配额，多实例部署需要自行协调各自的参数。

验证部署与容量边界

启动完成后，先查看日志里的 GPU KV cache size，判断当前 KV cache 能同时容纳多少 token。随后沿用上面的快速入门命令检查模型列表：

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

返回模型列表说明服务能够响应且模型已提供，但这只检查启动与服务可用性，不等于验证了长上下文性能。实际业务请求仍需单独验证，不能从该检查结果推导出吞吐或延迟结论。

常见出错点

当 KV cache 空间耗尽时，服务会抢占请求，并在空间恢复后重新计算；V1 默认采用 RECOMPUTE，而不是 SWAP。根据优化与调优文档，频繁抢占时首先应提高 gpu_memory_utilization；无法继续提高时，再降低 max_num_seqs 或 max_num_batched_tokens，减少每批并发及 KV cache 需求。

同一文档还说明，V1 会在条件允许时默认启用 chunked prefill，并优先调度 decode 请求。较小的 max_num_batched_tokens 示例值 2048 可改善 ITL，较大值有利于 TTFT；若以吞吐为目标，文档建议在小型模型使用大型 GPU 时设置 max_num_batched_tokens > 8192。关闭 chunked prefill 时，max_num_batched_tokens 必须大于 max_model_len。

--enforce-eager 会完全关闭 graph capture。文档将其描述为最快启动、但牺牲稳态 decode 性能的取舍，不应把它当成无代价的通用加速开关。

这些步骤按正文所链接的官方文档整理，未运行或测量；使用前请对照当前版本复核。

资料来源