概述

在大模型部署过程中，环境配置和依赖管理常常是令人头疼的问题。本文将详细介绍如何在Ubuntu 22.04系统上，使用Docker和vLLM离线部署Qwen3-4B模型，特别针对多GPU卡的环境进行优化配置。

环境准备

系统要求

• 操作系统：Ubuntu 22.04 LTS
• GPU要求：至少2张NVIDIA GPU卡（根据tensor-parallel-size参数决定）
• CUDA版本：12.4
• Docker版本：19.03或更高

宿主机环境检查

在开始之前，请确保宿主机环境符合要求：

# 检查NVIDIA驱动是否正常安装
nvidia-smi

# 检查Docker是否安装
docker --version

如果nvidia-smi命令能够正常输出GPU信息，说明驱动已正确安装。

离线安装NVIDIA Container Toolkit

要让Docker容器能够使用宿主机的GPU，需要安装NVIDIA Container Toolkit。在离线环境下的安装步骤如下：

1. 下载离线安装包

从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（主工具包）

2. 安装所有deb包

sudo dpkg -i *.deb

3. 验证安装

nvidia-ctk --version

如果成功输出版本号，说明安装成功。

4. 配置Docker

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

此命令会自动修改/etc/docker/daemon.json文件，配置Docker使用NVIDIA运行时。

离线获取vLLM Docker镜像

由于环境离线，需要先在联网环境中下载镜像，然后导出并转移到目标机器。

1. 在联网环境中拉取镜像

docker pull vllm/vllm-openai:v0.8.5.post1

2. 导出镜像为tar文件

docker save -o vllm-openai-v0.8.5.post1.tar vllm/vllm-openai:v0.8.5.post1

3. 在目标机器上导入镜像

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

参数解析

Docker运行参数

• -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线程数，避免资源冲突

vLLM服务参数

• --tensor-parallel-size 2：设置张量并行大小为2，与使用的GPU数量一致。
• --gpu-memory-utilization 0.90：设置GPU显存利用率为90%，留出部分显存以防溢出。
• --max-model-len 120000：设置模型处理的最大上下文长度。
• --served-model-name：设置API中使用的模型名称。

张量并行配置注意事项

当使用多卡部署时，需要确保--tensor-parallel-size参数设置正确：

1. 与GPU数量匹配：tensor-parallel-size值必须等于使用的GPU数量。
2. 注意力头数可整除：模型的注意力头数必须能被tensor-parallel-size整除。例如，如果模型有40个注意力头，tensor-parallel-size可以是1、2、4、5、8、10、20、40。

服务验证与测试

部署完成后，可以通过以下方式验证服务是否正常：

1. 检查容器日志

docker logs <container_id>

查看是否有错误信息，确认服务正常启动。

2. 测试API接口

# 检查模型列表
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
  }'

常见问题排查

1. GPU无法识别

如果容器内无法识别GPU，检查：

• NVIDIA Container Toolkit是否正确安装
• Docker是否已重启：sudo systemctl restart docker
• nvidia-smi在宿主机上是否正常工作

2. 显存不足

如果出现显存不足错误：

• 降低--gpu-memory-utilization参数值（如从0.9降到0.8）
• 减少--max-model-len参数值
• 检查是否有其他进程占用显存

3. 模型加载失败

• 确认模型路径是否正确挂载
• 检查模型文件是否完整
• 查看容器内模型文件权限

性能优化建议

1. 共享内存：对于多卡通信，适当增加--shm-size可以提高性能。
2. 网络模式：对于多机部署，考虑使用--network host主机网络模式减少网络开销。
3. IPC设置：添加--ipc host参数可以改善进程间通信效率。

通过以上步骤，可以在Ubuntu 22.04环境下成功离线部署支持多GPU的Qwen3-4B模型。此方案同样适用于其他支持vLLM的大模型部署。

系统ubuntu 22,04  cuda12.4

安装nvidia-container-toolkit
可以离线安装


docker pull vllm/vllm-openai:v0.8.5.post1
可导出镜像 离线

vllm_docker 
 - models
  - Qwen3-4B-Thinking-2507
vllm_docker 下执行


多卡部署命令

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 32GB -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