在 docker-compose.yml 中不能仅靠 devices 挂载 /dev/nvidia* 设备节点来使用 GPU，必须通过 gpus 字段（如 gpus: "all"）配合 runtime: nvidia 和 NVIDIA Container Toolkit，由 nvidia-container-runtime 注入驱动、库及环境变量，才能真正启用 GPU 加速。
在 docker-compose.yml 中通过 devices 参数直接调用物理 GPU 不可行，因为 devices 只能挂载设备文件（如 /dev/nvidia0），但不提供驱动、运行时库和 CUDA 上下文支持，容器内无法真正使用 GPU。
真正启用 GPU 的标准方式是使用 Docker 的 --gpus 机制（需 Docker 19.03+ 和 nvidia-container-toolkit），而 docker-compose 从 v2.20+（2022 年底起）开始原生支持 deploy.resources.reservations.devices，但更推荐、更通用、更可靠的方式是使用 runtime: nvidia + gpus（适用于 compose v2.17+）或 gpus under deploy（v2.20+）。下面分场景说明：
✅ 正确做法：用 gpus 字段（推荐）
确保满足前提：
- 宿主机已安装 NVIDIA 驱动（
nvidia-smi可运行） - 已安装并配置
nvidia-container-toolkit - Docker 版本 ≥ 19.03，
docker-compose≥ v2.17（CLI 插件模式）
version: "3.8"
services:
my-cuda-app:
image: nvidia/cuda:12.2.0-runtime-ubuntu22.04
runtime: nvidia # 必须声明，否则 gpus 不生效（旧版必需，新版仍建议保留）
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1 # 或 "all"、"0,1" 等
capabilities: [gpu, compute, utility]
# 或更简洁写法（compose v2.20+ 支持的 shorthand）：
# gpus: "all" # ← 这行等价于上面 deploy.devices 块（推荐！）✅
gpus: "all"是最常用写法；也可写gpus: "0"、gpus: "0,1"、gpus: "device=0"。
验证是否生效：
docker-compose run --rm my-cuda-app nvidia-smi
应正常显示 GPU 信息。
⚠️ 为什么不能只靠 devices:？
以下写法无效（即使容器能访问 /dev/nvidia*，也无法运行 CUDA 程序）：
# ❌ 错误示范：仅挂载设备节点，无驱动/库/环境 devices: - "/dev/nvidia0:/dev/nvidia0" - "/dev/nvidiactl:/dev/nvidiactl" - "/dev/nvidia-uvm:/dev/nvidia-uvm"
原因：
- 缺少
libcuda.so、libcudnn.so等运行时库 - 缺少
nvidia-smi、CUDA 工具链 - 缺少
NVIDIA_VISIBLE_DEVICES、NVIDIA_DRIVER_CAPABILITIES等关键环境变量 -
nvidia-container-runtime才负责自动注入这些
? 补充：检查与排错
- 确认
nvidia-container-toolkit已注册为默认 runtime：cat /etc/docker/daemon.json # 应含：{"runtimes": {"nvidia": {"path": "nvidia-container-runtime", ...}}} - 重启 Docker：
sudo systemctl restart docker - 查看可用 GPU：
docker run --rm --gpus all nvidia/cuda:12.2.0-runtime-ubuntu22.04 nvidia-smi - Compose 版本检查：
docker compose version（注意是docker compose，不是docker-compose）
? 小结关键点
-
devices:用于挂载任意块设备（如/dev/sdb），不适用于 GPU - GPU 必须用
gpus:（顶层字段）或deploy.resources.reservations.devices（显式声明） - 必须配合
runtime: nvidia（旧版强制，新版建议保留） - 基础镜像需包含 CUDA runtime（如
nvidia/cuda:xx-runtime-ubuntuyy） - 宿主机驱动版本需兼容容器中 CUDA 版本（CUDA 兼容性表）
不复杂但容易忽略。
