🔥 多卡炼丹必备！Docker Compose 多GPU配置终极指西(忘了东西又得查)
💡 你是否正在经历这些抓狂时刻？
▸ 容器启动报错 No CUDA-capable device is detected
▸ Docker多卡训练时总有一块GPU摸鱼不干活
▸ 容器重启后数据全消失，模型白训练...
这份保姆级指南将用5分钟解决你的多卡部署难题！
🛠️ 一、NVIDIA显卡核心配置（必须！）
🔧 开启持久化模式（解决容器无法识别GPU）
# 执行前必看！请确保已安装nvidia驱动
# 开启持久模式（减少GPU初始化延迟，docker容器使用显卡必须开启）
nvidia-smi -pm 1
# 关闭持久模式
nvidia-smi -pm 0
# 验证是否生效（看Persistence Mode显示为On）
nvidia-smi
Thu Mar 13 13:40:24 2025
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 550.54.14 Driver Version: 550.54.14 CUDA Version: 12.4 |
|-----------------------------------------+------------------------+----------------------+
| GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |
| | | MIG M. |
|=========================================+========================+======================|
| 0 NVIDIA GeForce RTX 3090 On | 00000000:05:00.0 Off | N/A |
| 0% 30C P8 24W / 350W | 21562MiB / 24576MiB | 0% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+
| 1 NVIDIA GeForce RTX 3090 On | 00000000:06:00.0 Off | N/A |
| 0% 29C P8 18W / 350W | 21562MiB / 24576MiB | 0% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+
| 2 NVIDIA GeForce RTX 3090 On | 00000000:0B:00.0 Off | N/A |
| 0% 29C P8 18W / 350W | 21562MiB / 24576MiB | 0% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+
| 3 NVIDIA GeForce RTX 3090 On | 00000000:13:00.0 Off | N/A |
| 0% 30C P8 17W / 350W | 21562MiB / 24576MiB | 0% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+
| 4 NVIDIA GeForce RTX 3090 On | 00000000:15:00.0 Off | N/A |
| 0% 31C P8 24W / 350W | 0MiB / 24576MiB | 0% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+
+-----------------------------------------------------------------------------------------+
| Processes: |
| GPU GI CI PID Type Process name GPU Memory |
| ID ID Usage |
|=========================================================================================|
| 0 N/A N/A 17917 C /usr/bin/python3 21546MiB |
| 1 N/A N/A 18067 C /usr/bin/python3 21546MiB |
| 2 N/A N/A 18068 C /usr/bin/python3 21546MiB |
| 3 N/A N/A 18069 C /usr/bin/python3 21546MiB |
+-----------------------------------------------------------------------------------------+
🚀 二、Docker Compose 高阶配置解析
1. 精准GPU调度（榨干每块显卡）
deploy:
resources:
reservations:
devices:
- driver: nvidia
capabilities: [gpu]
# 指定使用2块显卡
count: 2
# 使用GPU0和GPU1（nvidia-smi查看ID）
device_ids: ["0,1"]
📌 多卡策略：
| 场景 | 配置方案 |
|---|---|
| 指定单卡 | device_ids: ["1"] |
| 使用全部显卡 | 删除device_ids字段 |
| 负载均衡 | count: 2 + 多容器部署 |
2. 数据持久化黑科技（容器删除不丢数据）
volumes:
model_weights: # 声明命名存储卷
services:
trainer:
volumes:
# 挂载声明:左边是声明命名,右边是容器路径
- model_weights:/app/checkpoints
# 主机目录映射:左边是主机路径
- /host_data:/container_data
3. 环境变量智能管理（配置分离）
# 最佳实践：敏感信息放.env文件（不要提交到Git！）
# 多个环境变量一起放在.env文件
env_file: .env # 文件内容：API_KEY=your_key
environment:
# 可选 Nvidia 环境变量指定容器可见GPU；
- CUDA_VISIBLE_DEVICES=0,1
- MAX_BATCH_SIZE=8
# 配置HuggingFace镜像源
- HF_ENDPOINT=https://hf-mirror.com
# 设定HuggingFace缓存路径
- HUGGINGFACE_HUB_CACHE=/root/.cache/huggingface/hub
# HTTPS代理
- https_proxy=http://192.168.1.102:1088
# HTTP代理
- http_proxy=http://192.168.1.102:1088
Nvidia 环境变量CUDA_VISIBLE_DEVICES也可以指定容器可见GPU， 但是上一部分dockers设置管理GPU卡更加底层，容器只能看见选择的GPU卡； 注意，通过dockers设置可见gpu之后 CUDA_VISIBLE_DEVICES使用的GPU id应该以容器内部可见顺序为准。
⚡ 三、完整配置模板示例
services:
web:
image: luminainc/web:37ab9ae9
platform: linux/amd64 # 指定CPU架构
ports:
- "5173:8000" # 端口映射（主机:容器）
restart: always # 自动重启策略
segmentation:
deploy:
resources:
reservations:
# GPU资源声明
devices:
- driver: nvidia
capabilities: [gpu]
device_ids: ["4"]
volumes:
# 目录映射（主机:容器）共享默认模型下载文件夹
- /root/.cache/:/root/.cache/
# 共享内存映射
- /dev/shm:/dev/shm
minio:
healthcheck: # 健康检查配置
test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
interval: 30s # 检查间隔
🔥 四、高频操作速查表
| 命令 | 作用描述 |
|---|---|
docker-compose up | 创建并启动容器（带构建功能） |
docker-compose start | 启动已存在的容器 |
docker-compose stop | 停止运行中的容器 |
docker-compose down | 停止并删除容器/网络/镜像 |
docker exec -it [容器ID] bash | 进入运行中的容器调试（常用！） |
watch -n 1 nvidia-smi | 监控GPU使用情况（实时查看各容器占用） |
🚨 常见问题急救包
Q1：容器报错CUDA out of memory
👉 解决方案：
- 检查
device_ids是否指定了已占用GPU - 检查容器占用的GPU卡是否跟预期一致，无效配置将导致所有容器优先用第一张卡，导致浪费
Q2：多卡训练速度反而变慢
👉 检查项：
- 是否开启NCCL通信优化：
environment: NCCL_IB_DISABLE=0 - 是否配置共享内存映射：
/dev/shm
📢 互动话题：
👉 你在多卡训练中还遇到过哪些玄学问题？
