--gpus 是什么
--gpus 把宿主机的 NVIDIA 显卡设备与驱动库挂进容器，让容器内的 CUDA 程序可以直接使用显卡。它不是 Docker 引擎自带能力，而是由 NVIDIA 容器工具包提供的运行时配合实现的：宿主要装好显卡驱动，再安装 nvidia-container-toolkit 并重启 Docker，容器才看得到显卡。除了显卡，AMD 与国产加速卡走的是 --device 挂设备的思路，写法不同。
基本信息
| 适用环境 | Linux 装有 NVIDIA 驱动的主机；Windows 通过 WSL2 后端支持 |
|---|---|
| 语法 | --gpus all / --gpus 1 / --gpus '"device=0,2"'（注意内层引号） |
| 前置条件 | 宿主驱动 + nvidia-container-toolkit，装完需重启 docker 服务 |
| 验证方式 | docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi |
| 等价旧写法 | --runtime=nvidia 搭配环境变量 NVIDIA_VISIBLE_DEVICES |
| 限制 | 纯 CPU 主机或未装工具包时该参数直接报错 |
典型使用场景
- 跑推理服务：把模型服务容器绑定到指定显卡，避免与其他任务抢卡
- 训练任务按卡编排：一台多卡机器上给不同容器分配不同设备编号
- 验证显卡可用性：进容器执行 nvidia-smi 核对驱动与显存
- 排查 CUDA 版本不匹配：确认容器内运行时与宿主驱动的兼容区间
- 编排平台里给 GPU 任务做资源隔离，配合调度器把卡留给关键作业
挂卡与验证
挂卡与验证
# 用全部显卡跑一次自检，确认驱动、工具包、运行时链路都通
docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi
# 只挂第 0 号卡，注意设备列表需要内层引号
docker run --rm --gpus '"device=0"' nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi
# 只挂一张卡（任意一张），适合单卡推理容器
docker run -d --gpus 1 --name infer app/infer:1.0
# 核对宿主序号与容器内可见设备是否对得上，避免占错卡
docker exec infer nvidia-smi -L常见现象对照
| 现象 | 可能原因 | 处理方向 |
|---|---|---|
| pull 或 run 报 unknown flag: --gpus | Docker 版本过低或引擎未启用 nvidia 运行时 | 升级 Docker，检查运行时配置 |
| 容器内 nvidia-smi 不存在 | 基础镜像不含该工具 | 换带驱动工具的镜像或自行安装 |
| nvidia-smi 报驱动通信失败 | 宿主驱动与容器工具包未打通 | 重装工具包并重启 docker |
| 显存可见但 CUDA 报错 | 镜像内 CUDA 版本超出驱动支持范围 | 换匹配的 CUDA 镜像版本 |
| 多卡机器占错卡 | 设备序号与物理槽位不对应 | 先看宿主 nvidia-smi 拓扑再定编号 |
显卡是宿主级独占资源：同一张卡被两个容器同时挂载时共享显存与算力，不会自动隔离，需要业务侧控制并发或依赖编排平台做调度。
容器内进程通常以 root 运行，能看到显卡设备节点，恶意代码可以直接读取或修改显存内容；多租户环境不要把显卡设备随意挂给不受信任的镜像。