为什么用官方镜像
官方镜像 vllm/vllm-openai 已经把 CUDA 运行时、PyTorch 与 vLLM 按版本配好，省掉宿主机装工具箱、编译 wheel 的环节。容器里用的仍然是宿主机的驱动，所以驱动版本必须满足镜像要求的 CUDA 上限；镜像 tag 决定引擎版本，生产环境应写具体版本号。
基本信息
| 镜像 | vllm/vllm-openai（官方），tag 建议固定 |
|---|---|
| 容器端口 | 8000，通过 -p 映射到宿主机或内网 |
| GPU 透传 | --gpus all 或 --gpus device=0,1，依赖 nvidia-container-toolkit |
| 共享内存 | --ipc=host，或给出足够大的 --shm-size |
| 模型目录 | 把宿主机权重挂进容器，避免容器内重复下载 |
docker run 部署示例
docker run 部署示例
# 一条命令拉起：透传 GPU、共享内存、挂载权重与模型缓存
docker run -d --name vllm --runtime nvidia --gpus all \
--ipc=host -p 8000:8000 \
-v /data/models:/models \
-v /data/hf-cache:/root/.cache/huggingface \
vllm/vllm-openai:v0.6.0 \
--model /models/Qwen --max-model-len 8192 --served-model-name my-model
# 跟踪日志确认权重加载完成
docker logs -f vllm启动参数读法
| 参数 | 作用 |
|---|---|
| --runtime nvidia | 指定容器运行时，新版 Docker 可省略 |
| --gpus all | 透传全部 GPU，也可写成 device=2 只给第 3 张卡 |
| --ipc=host | 与宿主共享 IPC 命名空间，避免多进程共享内存不足 |
| -v 权重目录 | 模型挂进容器，容器重建不丢数据 |
| -p 8000:8000 | 端口映射，生产只映射到内网或交给网关反代 |
| --model 等引擎参数 | 容器启动命令后追加的参数直接传给引擎 |
先验证 GPU 透传
先验证 GPU 透传
# 第一步：宿主机层面确认工具链与驱动可用
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
# 第二步：确认目标镜像能起来（不加载权重，只看环境）
docker run --rm --gpus all vllm/vllm-openai:v0.6.0 --help | head -5
# 第三步：确认容器内看到的设备数量与预期一致
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi -L镜像 tag 固定到具体版本：用 latest 时重建会静默升级引擎行为，压测基线与线上表现对不上时很难归因。
容器进程在宿主机 nvidia-smi 中同样可见：排查显存不足时要在宿主机确认是否有其他容器或用户进程占着同一张卡。
权重尽量在宿主机预下载后挂载：容器内直接拉取既慢又会在卷里留副本；多实例共享同一挂载目录能省磁盘，但要留意并发读取的磁盘压力。