在 Ubuntu 22.04 系统上使用 Docker 和 vLLM 离线部署 Qwen3-4B 模型的方法。内容涵盖环境准备、NVIDIA Container Toolkit 安装、镜像导入、多卡部署命令详解及参数解析，并提供了服务验证与常见问题排查指南，适用于多 GPU 环境的模型推理服务搭建。
在大模型部署过程中，环境配置和依赖管理常常是令人头疼的问题。本文将详细介绍如何在 Ubuntu 22.04 系统上，使用 Docker 和 vLLM 离线部署 Qwen3-4B 模型，特别针对多 GPU 卡的环境进行优化配置。
在开始之前，请确保宿主机环境符合要求：
# 检查 NVIDIA 驱动是否正常安装
nvidia-smi
# 检查 Docker 是否安装
docker --version
如果 nvidia-smi 命令能够正常输出 GPU 信息，说明驱动已正确安装。
要让 Docker 容器能够使用宿主机的 GPU，需要安装 NVIDIA Container Toolkit。在离线环境下的安装步骤如下：
从 NVIDIA 官方 GitHub 仓库下载对应版本的 deb 安装包，主要包括：
libnvidia-container1_1.14.1-1_amd64.deb（基础库）libnvidia-container-tools_1.14.1-1_amd64.deb（基础工具）nvidia-container-toolkit-base_1.14.1-1_amd64.deb（基础组件）nvidia-container-toolkit_1.14.1-1_amd64.deb（主工具包）sudo dpkg -i *.deb
nvidia-ctk --version
如果成功输出版本号，说明安装成功。
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
此命令会自动修改 /etc/docker/daemon.json 文件，配置 Docker 使用 NVIDIA 运行时。
由于环境离线，需要先在联网环境中下载镜像，然后导出并转移到目标机器。
docker pull vllm/vllm-openai:v0.8.5.post1
docker save -o vllm-openai-v0.8.5.post1.tar vllm/vllm-openai:v0.8.5.post1
docker load -i vllm-openai-v0.8.5.post1.tar
使用 docker save 和 docker load 可以完整保存和恢复镜像的所有层和历史记录。
在部署之前，需要确保模型文件已正确放置：
vllm_docker/
└── models/
└── Qwen3-4B-Thinking-2507/
├── config.json
├── model.safetensors
└── ...（其他模型文件）
以下是针对多 GPU 卡部署的优化命令：
docker run -itd \
-e NCCL_DEBUG=INFO \
-e NCCL_IB_DISABLE=1 \
-e NCCL_SHM_DISABLE=0 \
-e OMP_NUM_THREADS=1 \
-e CUDA_VISIBLE_DEVICES=1,2 \
-e CUDA_DEVICE_ORDER=PCI_BUS_ID \
--gpus all \
-p 9996:8000 \
--shm-size 32g \
-v ./models:/models \
vllm/vllm-openai:v0.8.5.post1 \
--model /models/Qwen3-4B-Thinking-2507 \
--tensor-parallel-size 2 \
--gpu-memory-utilization 0.90 \
--max-model-len 120000 \
--served-model-name qwen3-4b-thinking-2507
-itd：以交互模式运行容器并分配伪终端，同时使容器在后台运行。--gpus all：让容器访问所有 GPU。-p 9996:8000：将容器的 8000 端口映射到宿主机的 9996 端口。--shm-size 32g：设置共享内存大小，对于多卡通信很重要。-v ./models:/models：将本地的 models 目录挂载到容器内的/models 路径。| 环境变量 | 值 | 作用 |
|---|---|---|
NCCL_DEBUG | INFO | 启用 NCCL 调试信息输出 |
NCCL_IB_DISABLE | 1 | 禁用 InfiniBand，避免在没有 IB 的环境中报错 |
CUDA_VISIBLE_DEVICES | 1,2 | 指定使用第 1 和第 2 号 GPU 卡 |
OMP_NUM_THREADS | 1 | 控制 OpenMP 线程数，避免资源冲突 |
--tensor-parallel-size 2：设置张量并行大小为 2，与使用的 GPU 数量一致。--gpu-memory-utilization 0.90：设置 GPU 显存利用率为 90%，留出部分显存以防溢出。--max-model-len 120000：设置模型处理的最大上下文长度。--served-model-name：设置 API 中使用的模型名称。当使用多卡部署时，需要确保 --tensor-parallel-size 参数设置正确：
部署完成后，可以通过以下方式验证服务是否正常：
docker logs <container_id>
查看是否有错误信息，确认服务正常启动。
# 检查模型列表
curl http://localhost:9996/v1/models
# 测试聊天接口
curl http://localhost:9996/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{ "model": "qwen3-4b-thinking-2507", "messages": [ {"role": "user", "content": "请介绍一下你自己" } ], "max_tokens": 100, "temperature": 0.7 }'
如果容器内无法识别 GPU，检查：
sudo systemctl restart dockernvidia-smi 在宿主机上是否正常工作如果出现显存不足错误：
--gpu-memory-utilization 参数值（如从 0.9 降到 0.8）--max-model-len 参数值--shm-size 可以提高性能。--network host 主机网络模式减少网络开销。--ipc host 参数可以改善进程间通信效率。通过以上步骤，可以在 Ubuntu 22.04 环境下成功离线部署支持多 GPU 的 Qwen3-4B 模型。此方案同样适用于其他支持 vLLM 的大模型部署。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online