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

vLLM常见启动错误排查

用 /v1/models 验证 vllm 服务，并按官方文档排查安装、模型、显存和启动参数错误。

完成下面这套排查后，你应能让 vllm 用指定模型正常启动，并能分清问题出在安装环境、模型名、显存还是启动参数。开始前先准备目标运行环境、可用加速卡、可访问的模型文件和一份可复现的启动命令。

准备条件

走 NVIDIA GPU 路径时，GPU 计算能力需要达到 7.5 或更高；vLLM 不原生支持 Windows，官方给出的路径是在 WSL 中使用兼容的 Linux 发行版，见 GPU 安装文档。执行前保留原始启动命令和完整日志，不要同时修改模型、上下文长度、显存比例和并行参数，否则很难判断哪项参数改变了启动结果。

操作步骤：vllm 启动与参数隔离

  1. 建立独立环境并运行基线命令：

bash 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

官方 快速入门文档 要求 Linux 与 Python 3.10--3.13；上述顺序会建立 Python 3.12 虚拟环境、按已安装的 CUDA 驱动选择 PyTorch 索引，并让服务默认监听 http://localhost:8000，一个服务进程当前承载一个模型。

  1. 逐项追加显存和上下文参数，不要整块执行：

text --gpu-memory-utilization 0.5 --max-model-len auto

0.5 是每实例模型执行器显存比例的示例，而 --gpu-memory-utilization 的默认值是 0.92；--max-model-len auto 会选择能装入 GPU 的最大长度，未设置时则从模型配置推导，若同时设置 --kv-cache-memory-bytes，它会忽略显存比例，见 服务命令参考。

  1. 如需隔离 CUDA graph capture 问题，再追加：

text --enforce-eager

--enforce-eager 会完全关闭 graph capture，同一 显存优化文档 也说明，降低 max_model_len 和 max_num_seqs 可以减少内存使用。

  1. 容器部署可使用官方镜像：

bash docker run --runtime nvidia --gpus all \ -v ~/.cache/huggingface:/root/.cache/huggingface \ --env "HF_TOKEN=$HF_TOKEN" \ -p 8000:8000 \ --ipc=host \ vllm/vllm-openai:latest \ --model Qwen/Qwen3-0.6B

运行前把 HF_TOKEN 保存在 shell 环境变量中；Docker 使用文档 说明该镜像映射 8000 端口，容器需要 --ipc=host 或 --shm-size 才能使用主机共享内存，其他引擎参数应放在镜像标签之后。

怎么确认成功

服务启动后运行：

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

官方 快速入门文档 使用 GET /v1/models 列出模型；正确结果是返回模型列表，并包含你启动时指定的模型标识，若结果不符，应先回查模型名和启动参数，而不是继续调整显存参数。

常见出错点

安装后立即出现 CUDA 或 GPU 错误

重新建立全新环境，不要继续复用冲突的依赖；官方 NVIDIA CUDA 安装说明 指出版本不同或需要沿用已有 PyTorch 时，应改为从源码构建。

模型能加载，但 API 模型名不一致

如果客户端请求名与 /v1/models 返回值不同，先检查 --served-model-name：服务器接受设置的所有名称，但响应中的 model 字段使用列表中的第一个名称，见 服务命令参考。

如果普通请求可用、聊天请求却全部报错，检查 tokenizer 是否带有 chat template；在线服务文档 说明没有 chat template 时聊天请求会报错，也可用 --chat-template 指定文件路径或模板字符串。

显存余量小或频繁出现 preemption

KV cache 空间耗尽时，请求会被抢占并在空间恢复后重新计算，V1 的默认抢占模式是 RECOMPUTE；官方 优化与调优文档 给出的处理顺序是提高 gpu_memory_utilization，或降低 max_num_seqs、max_num_batched_tokens，不要同时大幅修改这些参数。

容器或 Kubernetes 服务地址异常

容器内若出现进程通信问题，先恢复上一步的 --ipc=host 或 --shm-size。在 Kubernetes 中，环境变量文档 说明 VLLM_PORT 和 VLLM_HOST_IP 用于内部用途，并不是 API Server 地址，同时不应把 Service 命名为 vllm，以免 Kubernetes 生成的环境变量发生冲突。

这些步骤依据正文所链接的官方文档整理，未在本网站自有机器上运行，因此请按当前版本复核命令与默认值。

资料来源