在生产环境中，直接使用宿主机安装 vLLM 虽操作简单，但在版本隔离、依赖管理、跨机器迁移等核心场景中存在明显短板。因此，生产级部署更推荐采用容器化方案，实现高效、可复用、易维护的 GPU 推理服务。

本文延续实战风格，全程提供可直接复制运行的命令，完整讲解如何通过 Docker 部署 vLLM，并成功运行 DeepSeek 模型服务，同时覆盖 NVIDIA CUDA 和 AMD ROCm 两大 GPU 环境，适配不同硬件场景。

✅ 使用 Docker 部署 vLLM，实现环境隔离与快速迁移
✅ 适配 NVIDIA CUDA / AMD ROCm 双 GPU 环境
✅ 部署 DeepSeek 模型，提供 OpenAI 兼容 API 服务
✅ 解决部署中的高频问题，适配生产环境需求

📌 系列文章

👉 大模型本地部署实践（总览）：为什么要做本地部署及方案选型
👉 如何在本地部署 DeepSeek？Ollama 一步跑通全流程实战
👉 Docker 部署 Ollama 全流程指南：支持 CPU/GPU、生产环境可用的工程化实践
👉 vLLM 本地部署 DeepSeek 全流程实战（Linux + NVIDIA GPU + OpenAI API 兼容）

一、为什么推荐 Docker 部署 vLLM？

在真实项目落地中，Docker 容器化部署相比宿主机直装，优势尤为突出，尤其适配 GPU 推理的生产场景：

• 环境完全隔离：容器内依赖独立管理，不污染宿主机系统，避免版本冲突

• 跨机快速迁移：打包好的镜像可直接在其他服务器运行，无需重复配置依赖

• 支持自动化部署：可无缝对接 CI/CD 流程，实现部署、升级、回滚的标准化

• 版本可控：通过固定镜像版本，确保不同环境部署的一致性，降低运维成本

目前，容器化已成为 GPU 推理服务的行业标准方案，也是企业级私有化部署的首选方式。

二、Docker 部署 vLLM（NVIDIA CUDA 环境）

适用于搭载 NVIDIA 独立显卡的服务器，也是最主流、兼容性最好的部署方案，全程手把手实战，新手可直接跟随操作。

2.1 安装 NVIDIA Container Toolkit（必做步骤）

要让 Docker 容器能够调用宿主机的 NVIDIA GPU，必须先安装 NVIDIA Container Toolkit，它是 GPU 容器与宿主机显卡通信的核心组件。

执行以下命令，一步完成安装与配置（复制时确保命令完整，避免换行遗漏）：

# 1. 添加 NVIDIA 官方 GPG 密钥（用于验证软件包合法性）
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
| sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

# 2. 添加 NVIDIA Container Toolkit 软件源
curl -fsSL https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
| sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
| sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# 3. 更新系统软件包列表
sudo apt-get update

# 4. 安装 NVIDIA Container Toolkit
sudo apt-get install -y nvidia-container-toolkit

# 5. 配置 Docker，让其支持 NVIDIA GPU 运行时
sudo nvidia-ctk runtime configure --runtime=docker

# 6. 重启 Docker 服务，使配置生效
sudo systemctl restart docker

安装完成后，执行以下命令验证是否成功（核心验证容器能否调用 GPU）：

docker run --rm --gpus all nvidia/cuda:12.3.0-base nvidia-smi

若终端能正常显示宿主机显卡型号、CUDA 版本、显存占用等信息，说明 NVIDIA Container Toolkit 安装成功，可进入下一步部署。

2.2 运行 vLLM 容器（核心步骤）

推荐使用 vLLM 官方镜像，无需手动构建，直接拉取即可运行，镜像已集成 vLLM 及相关依赖，适配 CUDA 环境。

官方镜像（Docker Hub）：vllm/vllm-openai:latest（openai 后缀表示默认支持 OpenAI API 兼容接口）

执行以下命令，启动 vLLM 容器并运行 DeepSeek 模型：

docker run --runtime nvidia --gpus all \
    -v ~/.cache/modelscope:/root/.cache/modelscope \
    --env VLLM_USE_MODELSCOPE=True \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B

关键参数详解（实战重点，必看）：

• --gpus all：允许容器使用宿主机的所有 GPU，若需指定 GPU，可改为 --gpus "device=0,1"（指定第 0、1 块 GPU）

• -p 8000:8000：将容器内的 8000 端口（vLLM 默认 API 端口）映射到宿主机 8000 端口，外部可通过宿主机 IP:8000 访问服务

• --ipc=host：共享宿主机的进程间通信资源，避免容器内共享内存不足，导致模型启动失败

• -v ~/.cache/modelscope:/root/.cache/modelscope：将宿主机的 ModelScope 模型缓存目录挂载到容器内，实现模型缓存持久化，避免每次重启容器重复下载模型（国内环境必加）

• --env VLLM_USE_MODELSCOPE=True：设置环境变量，让 vLLM 优先从 ModelScope 下载模型，解决国内访问 HuggingFace 速度慢的问题

• --model：指定要运行的模型，本文使用轻量版 DeepSeek 模型（deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B），适合入门测试，可替换为其他支持的模型

启动成功后，终端会输出监听日志，此时可访问：http://localhost:8000，若能正常显示 vLLM 服务信息，说明容器启动成功。

2.3 容器内手动部署模型（可选，用于调试）

若需进入容器内部进行调试、手动管理模型或修改配置，可执行以下步骤：

# 1. 查看正在运行的 vLLM 容器 ID
docker ps

# 2. 进入容器内部（替换 <container_id> 为实际容器 ID）
docker exec -it <container_id> bash

# 3. （可选）安装 ModelScope（若容器内未预装）
pip install modelscope

# 4. 手动启动 vLLM 服务，运行 DeepSeek 模型
vllm serve "deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B"

这种方式适合开发调试、手动更换模型或修改 vLLM 启动参数，生产环境建议直接使用 2.2 节的一键启动命令。

三、Docker 部署 vLLM（AMD ROCm 环境）

适用于搭载 AMD 独立显卡的服务器，部署逻辑与 NVIDIA CUDA 环境类似，但镜像和启动参数略有差异，全程适配 ROCm 6.3+ 版本。

官方镜像：rocm/vllm-dev:nightly（ROCm 专属 vLLM 开发版镜像，已集成 ROCm 依赖）

3.1 运行 ROCm 容器（核心步骤）

执行以下命令，启动 ROCm 容器，映射 GPU 设备并挂载模型缓存：

docker run -it --rm \
    --network=host \
    --group-add=video \
    --ipc=host \
    --cap-add=SYS_PTRACE \
    --security-opt seccomp=unconfined \
    --device /dev/kfd \
    --device /dev/dri \
    -v ~/.cache/modelscope:/root/.cache/modelscope \
    -e VLLM_USE_MODELSCOPE=True \
    rocm/vllm-dev:nightly

ROCm 容器关键参数详解：

• --device /dev/kfd、--device /dev/dri：将 AMD GPU 相关设备文件映射到容器内，是容器调用 AMD 显卡的核心

• --group-add=video：添加 video 用户组，让容器拥有访问 AMD 显卡的权限

• --network=host：使用宿主机网络，简化端口配置，无需手动映射端口（容器内端口直接暴露给宿主机）

• --cap-add=SYS_PTRACE、--security-opt seccomp=unconfined：提升容器权限，避免 ROCm 运行时权限不足

• -v ~/.cache/modelscope、-e VLLM_USE_MODELSCOPE=True：与 CUDA 环境一致，实现模型缓存持久化和国内源加速

3.2 容器内部署模型（调试/手动操作）

容器启动后，默认进入交互终端，若未自动进入，可执行以下命令进入容器并启动模型：

# 1. 查看 ROCm 容器 ID
docker ps

# 2. 进入容器内部（替换 <container_id> 为实际容器 ID）
docker exec -it <container_id> bash

# 3. 安装 ModelScope（若容器内未预装）
pip install modelscope

# 4. 启动 vLLM 服务，运行 DeepSeek 模型
vllm serve "deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B"

启动成功后，同样可通过 http://localhost:8000 访问服务，与 NVIDIA 环境的访问方式一致。

四、API 接口测试（验证部署成功）

vLLM 容器启动后，默认提供 OpenAI API 兼容接口，可直接通过 curl 命令、Postman 或业务代码调用，快速验证服务可用性。

执行以下 curl 命令，向本地 vLLM 服务发送请求（复制即可运行）：

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B",
    "messages": [
      {"role": "user", "content": "Docker 部署 vLLM 成功了吗？"}
    ]
  }'

若返回如下标准 JSON 响应（包含模型回答、token 用量等信息），说明部署完全成功，服务可正常对外提供 API 调用：

{
  "id": "chatcmpl-xxxx",
  "object": "chat.completion",
  "created": 1725122400,
  "model": "deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "恭喜你！Docker 部署 vLLM 已经成功，当前可正常调用 DeepSeek 模型进行推理。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 22,
    "total_tokens": 37
  }
}

五、常见问题及解决方案（高频踩坑汇总）

部署过程中，可能会遇到 GPU 调用失败、模型重复下载、显存不足等问题，以下是高频问题的解决方案，覆盖 90% 实战场景。

1️⃣ 容器启动报 GPU 相关错误

现象：启动容器时，提示 “no GPU found”、“CUDA error” 或 “ROCm device not found” 等错误。

常见原因及解决方式：

• 未安装对应 GPU 的容器工具（NVIDIA 未装 Container Toolkit，AMD 未配置 ROCm 环境）：重新执行对应环境的前置安装步骤。

• Docker 版本过旧：升级 Docker 到 20.10 及以上版本（旧版本不支持 GPU 容器），执行 sudo apt-get update && sudo apt-get install docker-ce docker-ce-cli containerd.io。

• 显卡驱动与容器环境不匹配：NVIDIA 需确保驱动版本适配 CUDA 版本，AMD 需确保 ROCm 版本与驱动兼容。

2️⃣ 模型重复下载，每次重启容器都要重新下载

原因：未挂载模型缓存目录，容器重启后，内部缓存的模型文件会被删除。

解决方案：启动容器时，必须添加以下挂载参数（已在前面的命令中包含，重点检查是否遗漏）：

-v ~/.cache/modelscope:/root/.cache/modelscope

挂载后，模型会缓存到宿主机的 ~/.cache/modelscope 目录，后续重启容器可直接复用，无需重复下载。

3️⃣ 启动模型时报显存不足（out of memory）

现象：启动模型时，终端提示显存不足，无法初始化模型。

解决方案：

• 限制 GPU 显存利用率，预留部分显存供系统使用，在启动命令中添加 --gpu-memory-utilization 0.8（表示使用 80% 的显存，可根据显卡容量调整为 0.7~0.9）。

• 调小模型最大上下文长度，减少显存占用，添加参数--max-model-len 2048（默认上下文长度较长，可根据需求调整）。

• 更换更小参数量的模型（如本文使用的 1.5B 轻量版，替换为更大模型时需确保显卡显存足够）。

六、生产部署建议（企业级落地优化）

若将 Docker + vLLM 用于生产环境，仅完成基础部署远远不够，需做好以下优化，提升服务稳定性和可维护性：

• 使用 docker-compose 管理容器：将启动参数、环境变量、挂载目录等配置写入 docker-compose.yml，实现一键启动、停止、重启，简化运维。

• 固定镜像版本：不要使用 latest 标签（镜像会自动更新，可能导致版本兼容问题），改为固定版本（如 vllm/vllm-openai:v0.5.0）。

• 添加容器重启策略：在启动命令或 docker-compose 中配置 --restart=always，确保容器意外退出后自动重启，避免服务中断。

• 使用 Nginx 做反向代理：统一入口，实现负载均衡、HTTPS 加密、请求限流，提升服务安全性和并发能力。

• 配置监控告警：集成 Prometheus + Grafana，监控容器运行状态、GPU 显存/使用率、API 调用量，出现异常及时告警。

七、总结

本文完整覆盖了 Docker 部署 vLLM 的全流程，分别适配 NVIDIA CUDA 和 AMD ROCm 两大 GPU 环境，核心完成了以下内容：

• NVIDIA CUDA 环境：安装 Container Toolkit、启动 vLLM 容器、运行 DeepSeek 模型

• AMD ROCm 环境：启动 ROCm 容器、部署模型，实现与 CUDA 环境一致的 API 服务

• API 接口测试：验证 OpenAI 兼容接口可用性，确保服务可正常调用

• 问题排查与生产优化：解决高频部署问题，给出企业级落地建议

当你面临企业私有化部署、GPU 服务器集群、高并发推理服务等场景时，Docker + vLLM 是兼顾效率、稳定性和可维护性的最优组合。

如果这篇文章对你的部署工作有帮助，欢迎点赞、收藏、关注，后续将持续更新 vLLM 生产级优化、多模型部署等实战内容～