Ubuntu 22.04 离线部署 Qwen3-4B 模型：vLLM 与 Docker 多卡配置指南

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 路径。

环境变量配置

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 的大模型部署。