部署前先了解vLLM适合做什么

vLLM是常用的大模型推理框架，特点是高吞吐、显存利用率好，并提供兼容OpenAI接口风格的服务能力。

对于已经有模型权重的团队，希望在本地服务器或云主机上快速提供文本生成接口，用Docker部署可以减少环境差异带来的问题，避免反复安装CUDA、Python依赖和推理组件。

这类部署方式适合三种场景：

• 研发测试：快速验证Qwen、Llama、DeepSeek等模型的推理效果
• 业务接入：把模型能力包装成HTTP接口
• 多环境迁移：在开发、测试、生产服务器上使用一致的运行方式

注意：vLLM主要依赖NVIDIA GPU，CPU模式不是它的核心优势。部署前应确认显卡型号、显存容量、驱动版本与模型规模匹配。

环境准备与版本检查

开始前，建议准备一台Linux服务器，已安装Docker，并配置好NVIDIA Container Toolkit。

显卡驱动要能被容器识别，否则容器即使启动成功，也无法使用GPU推理。

先在宿主机执行：nvidia-smi，确认能看到显卡信息、驱动版本和显存状态。

再检查Docker是否可用：docker --version。

要验证容器访问GPU，可执行：docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi。

如果该命令能输出显卡信息，说明容器侧GPU运行时基本正常。

若提示找不到GPU、runtime异常或权限不足，应先修复Docker与显卡运行时配置，再部署vLLM。

拉取vLLM镜像

vLLM官方镜像通常发布在公开容器仓库中，常见镜像名为：vllm/vllm-openai。

建议不要盲目使用latest标签。生产环境应固定版本，便于回滚和排查。

例如：docker pull vllm/vllm-openai:v0.6.6。如果只是本地试用，也可以使用：docker pull vllm/vllm-openai:latest。

镜像拉取完成后可执行：docker images | grep vllm，确认镜像已存在。

镜像体积较大，拉取时间与网络状况有关。若下载失败，应优先检查仓库地址、DNS解析和服务器出站访问策略。

不建议随意下载来历不明的第三方改包镜像，避免引入不可控组件。

规划模型目录与缓存目录

vLLM运行时需要读取模型文件。模型可以提前下载到服务器本地，也可以在容器启动时从模型平台拉取。

为了便于复用和管理，建议在宿主机创建统一目录，例如：mkdir -p /data/models /data/vllm-cache。

其中/data/models用于保存模型权重，/data/vllm-cache用于保存运行缓存或下载缓存。

目录权限也要提前处理。如果容器内进程无法读取模型目录，会出现模型加载失败、Permission denied等错误。

简单测试环境可使用：chmod -R 755 /data/models /data/vllm-cache。

生产环境不建议给过宽权限，应按运行用户最小授权。

一键启动基础服务

假设模型已经位于宿主机/data/models/Qwen2.5-7B-Instruct，希望对外提供8000端口，可以执行以下命令启动：

docker run -d --name vllm-qwen --gpus all -p 8000:8000 -v /data/models:/models -v /data/vllm-cache:/root/.cache/huggingface --ipc=host vllm/vllm-openai:v0.6.6 --model /models/Qwen2.5-7B-Instruct --served-model-name qwen2.5-7b --host 0.0.0.0 --port 8000

这条命令包含几个关键点：

• --gpus all：容器可使用全部GPU
• -p 8000:8000：把宿主机8000端口映射到容器8000端口
• -v /data/models:/models：把本地模型目录挂载到容器内
• --ipc=host：减少部分共享内存相关问题
• --served-model-name：设置接口中显示和调用的模型名称

端口映射怎么配置更合理

Docker端口映射格式是宿主机端口:容器端口。

如果命令中vLLM监听容器内8000端口，那么-p 8000:8000表示用户访问服务器的8000端口即可到达服务。

若宿主机8000已被占用，可改为：-p 18000:8000，此时外部访问端口变为18000，而容器内仍是8000。

如果服务只给本机其他程序调用，可以绑定到本地地址：-p 127.0.0.1:8000:8000，这样外部机器无法直接访问该端口，安全性更高。

如果需要提供给同一内网的业务系统调用，应配合服务器访问控制策略，只放行必要来源。

不要把测试服务直接暴露到公网，尤其是没有鉴权、限流和日志审计的情况下。

验证接口是否可用

容器启动后，先查看日志：docker logs -f vllm-qwen。

模型加载需要时间，尤其是大参数模型，首次启动可能持续数分钟。看到服务监听端口、模型加载完成等信息后，可以测试模型列表接口：curl http://127.0.0.1:8000/v1/models。

也可以测试聊天接口：curl http://127.0.0.1:8000/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"qwen2.5-7b","messages":[{"role":"user","content":"用一句话介绍vLLM"}],"temperature":0.7}'。

如果返回正常JSON结果，说明基础部署成功。若返回模型不存在，通常是请求中的model字段与--served-model-name不一致。

常用启动参数建议

实际使用中，除了模型路径和端口，还常会调整显存利用率、最大上下文长度、并行方式等参数。

• --gpu-memory-utilization 0.9：尽量使用90%的显存
• --max-model-len 8192：限制最大上下文长度
• --tensor-parallel-size 2：让模型切分到两张GPU上（多卡部署）

参数不是越大越好。上下文长度越长，显存占用通常越高；显存利用率设置过满，可能在并发升高时出现OOM；并行数必须与显卡数量、模型结构和框架支持情况匹配。

建议先用低并发、小批量请求压测，再逐步调整。

容器管理与升级回滚

停止服务可执行：docker stop vllm-qwen；再次启动可执行：docker start vllm-qwen；删除容器可执行：docker rm vllm-qwen。

如果要更换启动参数，通常需要停止并删除旧容器，再用新参数重新创建。模型目录挂载在宿主机上，删除容器不会删除宿主机模型文件。

升级vLLM镜像前，应记录当前镜像标签、启动命令、模型版本和关键参数。

推荐先拉取新版本镜像，使用不同容器名和不同宿主机端口试运行，例如vllm-qwen-test和18000端口。

确认接口、性能和输出稳定后，再切换业务流量。若新版本出现兼容问题，可停止新容器，重新启动旧版本容器完成回滚。

常见问题排查

问题一：容器启动后立即退出

可用docker logs 容器名查看原因，常见是模型路径错误、显存不足、参数拼写错误或镜像版本不支持某些参数。

问题二：提示CUDA或GPU不可用

先在宿主机执行nvidia-smi，再用CUDA测试容器验证Docker能否访问GPU。若宿主机正常而容器异常，多半与NVIDIA Container Toolkit安装或Docker运行时配置有关。

问题三：接口能访问但响应很慢

可能是模型过大、显存不足导致调度压力高，也可能是并发超过机器承载能力。可降低最大上下文长度、减少并发、选择量化模型或升级显卡资源。

问题四：端口无法访问

检查容器是否运行：docker ps；检查端口映射是否正确；确认vLLM启动参数中的--host不是仅绑定在容器本地；同时检查服务器访问控制策略。

安全边界与实用建议

vLLM部署完成后，本质上就是一个模型推理服务。若没有额外鉴权，任何能访问端口的客户端都可能发起请求，带来资源消耗和数据泄露风险。

生产环境建议放在受控网络内，通过网关增加鉴权、限流、请求体大小限制和访问日志，不要直接暴露裸服务。

模型目录也要规范管理。不要把敏感业务数据、密钥文件和模型权重混放在同一目录。挂载目录尽量只读，例如确认无需写入时可使用-v /data/models:/models:ro。

同时保留启动命令、镜像标签和参数变更记录，方便出现问题时快速定位。

对于初次部署者，最稳妥的路径是：先用小模型跑通流程，再换目标模型，最后再做并发测试和参数优化。