当前位置：首页 > news >正文

使用vLLM与Docker在Ubuntu 22.04上离线部署Qwen3-4B模型：多卡配置完整指南

news 2025/11/13 8:11:27

概述

在大模型部署过程中，环境配置和依赖管理常常是令人头疼的问题。本文将详细介绍如何在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参数设置正确：

与GPU数量匹配：tensor-parallel-size值必须等于使用的GPU数量。
注意力头数可整除：模型的注意力头数必须能被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. 模型加载失败

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

性能优化建议

共享内存：对于多卡通信，适当增加--shm-size可以提高性能。
网络模式：对于多机部署，考虑使用--network host主机网络模式减少网络开销。
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

查看全文

http://www.dtcms.com/a/601619.html