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

vLLM 在 RTX 4090 上的部署与调优

本文说明如何在 RTX 4090 上用 Linux 与 uv 安装并启动 vLLM，验证服务后按显存、上下文和批处理参数排查常见问题。

在 RTX 4090 上部署 vLLM，可按 vLLM 官方 Quickstart 使用 Linux、Python 3.12 全新虚拟环境与 uv 安装，再用 vllm serve 启动并查询 /v1/models。调优重点不是堆参数，而是显存比例、上下文长度、批处理上限与请求抢占。

部署前先核对显卡与系统条件

NVIDIA 的 RTX 4090 官方规格页为 Founders Edition 列出 24 GB GDDR6X、450 W 图形功耗和 850 W 系统电源要求；卡身尺寸为 304 mm 长、137 mm 宽、占用 3 个插槽。选型时应把模型权重和 KV cache 与 24 GB 总显存对照，同时检查机箱空间和整机供电；如果购买的不是 Founders Edition，应以具体显卡及整机供应商资料为准。

同时，vLLM GPU 安装文档要求 NVIDIA GPU 的 compute capability 为 7.5 或更高。该门槛不能仅凭显存容量反推，安装前仍应按当前文档核对实际显卡和驱动环境。

安装、启动并验证服务

安装、启动、默认监听地址和模型列表检查均以 vLLM 官方 Quickstart 为准。它列出的前置条件是 Linux 和 Python 3.10 到 3.13，并给出 Python 3.12 新环境流程；--torch-backend=auto 会检查本机已安装的 CUDA driver version，以选择对应的 PyTorch index。

先确保 uv 可用，再依次执行：

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

服务默认监听 http://localhost:8000，监听地址可由 --host 和 --port 设置。一个服务进程当前承载一个模型，因此切换模型时要检查启动参数对应的进程和端口。

服务启动后执行：

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

该请求用于确认模型列表接口可用；如果修改了监听地址或端口，应查询相应的服务地址。

用 vllm serve 调优显存与上下文

vllm serve CLI 参数文档说明了主要内存和批处理参数：

  • --gpu-memory-utilization 是模型执行器可使用的 GPU 显存比例，范围为 0 到 1，默认值为 0.92；它是每个实例的限制。
  • --kv-cache-memory-bytes 直接设置每张 GPU 的 KV cache 大小；设置后，KV cache sizing 不再采用 --gpu-memory-utilization。
  • --max-model-len 限制 prompt 与 output 合计的上下文长度；不设置时从模型配置推导，传入 -1 或 auto 时选择 GPU 内存能够容纳的最大长度。
  • --max-num-seqs 和 --max-num-batched-tokens 分别限制单次迭代处理的序列数和 token 数。

可以按下面的结构填入自己的数值：

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

RTX 4090 的 24 GB 显存并不能推出适用于所有模型的固定参数。应根据模型配置、实际上下文需求和并发量填写这些值；需要让系统选择可容纳的最大上下文时，可使用 --max-model-len auto。

显存不足或频繁抢占时怎么调

KV cache 空间耗尽时，vLLM 会抢占请求，并在空间恢复后重新计算；V1 的默认抢占模式是 RECOMPUTE，不是 SWAP。vLLM 调优文档给出的处理顺序是：频繁抢占时先提高 gpu_memory_utilization，也可以降低 max_num_seqs 或 max_num_batched-tokens，以减少一个批次需要容纳的 KV cache。

如果目标转为尽快启动，同一份调优文档说明：--enforce-eager 会跳过编译和 CUDA graph capture，以最快可能启动为代价牺牲稳态 decode performance；优化级别中，-O2 是默认值，-O0 不启用优化，启动最快但性能最低。每轮只改变一个参数，更容易判断影响来自显存、上下文还是批处理限制。

常见出错点

  • 直接在 Windows 原生环境运行：vLLM 不原生支持 Windows；Windows 的 GPU 安装说明给出的路线是使用 WSL 和兼容的 Linux 发行版。
  • CUDA 与编译环境不匹配：预编译 vLLM package 包含预编译的 C++ 和 CUDA 12.9 binaries；GPU 安装文档同时要求源码构建环境使用 GCC/G++ 11.3 或更新版本。
  • 模型路径或认证不对：vllm serve CLI 参数文档说明，--download-dir 可指定权重目录，未设置时使用 Hugging Face 默认缓存目录；需要认证时可传入 --hf-token YOUR_VALUE。由 hf auth login 生成的 token 默认保存在 ~/.cache/huggingface/token。

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

资料来源