使用 Docker 的专用配置

环境变量 (OCI 规范)

用户可以使用环境变量控制 NVIDIA 容器运行时的行为 - 特别是用于枚举 GPU 和驱动程序的功能。每个环境变量都映射到来自 libnvidia-container 的 nvidia-container-cli 的命令行参数。这些变量已在 NVIDIA 提供的基础 CUDA 镜像中设置。

GPU 枚举

可以使用 Docker CLI 指定 GPU，方法是使用 Docker 19.03 或更高版本中的 --gpus 选项，或者使用环境变量 NVIDIA_VISIBLE_DEVICES。此变量控制哪些 GPU 将在容器内部可访问。

NVIDIA_VISIBLE_DEVICES 变量的可能值是

可能的值	描述
0,1,2, 或 GPU-fef8089b	GPU UUID 或索引的逗号分隔列表。
all	所有 GPU 都将可访问，这是基础 CUDA 容器镜像中的默认值。
none	没有 GPU 将可访问，但驱动程序功能将被启用。
void 或 empty 或 unset	nvidia-container-runtime 的行为将与 runc 相同（即，既不暴露 GPU 也不暴露功能）

注意

当使用 --gpus 选项来指定 GPU 时，应使用 device 参数。这在下面的示例中显示。 device 参数的格式应封装在单引号内，然后使用双引号表示要枚举到容器的设备。例如：'"device=2,3"' 将枚举 GPU 2 和 3 到容器。

当使用 NVIDIA_VISIBLE_DEVICES 变量时，您可能需要将 --runtime 设置为 nvidia，除非已设置为默认值。

下面显示了一些用法示例

1. 启动启用 GPU 的 CUDA 容器；使用 --gpus

   $ docker run --rm --gpus all nvidia/cuda nvidia-smi
   

2. 使用 NVIDIA_VISIBLE_DEVICES 并指定 nvidia 运行时

   $ docker run --rm --runtime=nvidia \
       -e NVIDIA_VISIBLE_DEVICES=all nvidia/cuda nvidia-smi
   

3. 在两个 GPU 上启动启用 GPU 的容器

   $ docker run --rm --gpus 2 nvidia/cuda nvidia-smi
   

4. 在特定 GPU 上启动启用 GPU 的容器

   $ docker run --gpus '"device=1,2"' \
       nvidia/cuda nvidia-smi --query-gpu=uuid --format=csv
   

   uuid
   GPU-ad2367dd-a40e-6b86-6fc3-c44a2cc92c7e
   GPU-16a23983-e73e-0945-2095-cdeb50696982
   

5. 或者，您也可以使用 NVIDIA_VISIBLE_DEVICES

   $ docker run --rm --runtime=nvidia \
       -e NVIDIA_VISIBLE_DEVICES=1,2 \
       nvidia/cuda nvidia-smi --query-gpu=uuid --format=csv
   

   uuid
   GPU-ad2367dd-a40e-6b86-6fc3-c44a2cc92c7e
   GPU-16a23983-e73e-0945-2095-cdeb50696982
   

6. 使用 nvidia-smi 查询 GPU UUID，然后将其指定给容器

   $ nvidia-smi -i 3 --query-gpu=uuid --format=csv
   

   uuid
   GPU-18a3e86f-4c0e-cd9f-59c3-55488c4b0c24
   

   $ docker run --gpus device=GPU-18a3e86f-4c0e-cd9f-59c3-55488c4b0c24 \
        nvidia/cuda nvidia-smi
   

驱动程序功能

NVIDIA_DRIVER_CAPABILITIES 控制哪些驱动程序库/二进制文件将被挂载到容器内部。

NVIDIA_DRIVER_CAPABILITIES 变量的可能值是

可能的值	描述
compute,video 或 graphics,utility	容器需要的驱动程序功能的逗号分隔列表。
all	启用所有可用的驱动程序功能。
empty 或 unset	使用默认驱动程序功能：utility，compute

下面提供了支持的驱动程序功能

驱动程序功能	描述
compute	CUDA 和 OpenCL 应用程序所需。
compat32	运行 32 位应用程序所需。
graphics	运行 OpenGL 和 Vulkan 应用程序所需。
utility	使用 nvidia-smi 和 NVML 所需。
video	使用视频编解码器 SDK 所需。
display	利用 X11 显示所需。

例如，指定 compute 和 utility 功能，允许使用 CUDA 和 NVML

$ docker run --rm --runtime=nvidia \
    -e NVIDIA_VISIBLE_DEVICES=2,3 \
    -e NVIDIA_DRIVER_CAPABILITIES=compute,utility \
    nvidia/cuda nvidia-smi

$ docker run --rm --gpus 'all,"capabilities=compute,utility"' \
    nvidia/cuda:11.6.2-base-ubuntu20.04 nvidia-smi

约束

NVIDIA 运行时还提供了定义容器支持的配置约束的能力。

NVIDIA_REQUIRE_* 约束

此变量是用于定义容器上软件版本或 GPU 架构约束的逻辑表达式。

下面提供了支持的约束

约束	描述
cuda	CUDA 驱动程序版本的约束。
driver	驱动程序版本的约束。
arch	所选 GPU 的计算架构的约束。
brand	所选 GPU 品牌的约束（例如 GeForce、Tesla、GRID）。

可以在单个环境变量中表达多个约束：空格分隔的约束是 OR 关系，逗号分隔的约束是 AND 关系。多个 NVIDIA_REQUIRE_* 形式的环境变量是 AND 关系。

例如，可以将以下约束指定给容器镜像，以约束支持的 CUDA 和驱动程序版本

NVIDIA_REQUIRE_CUDA "cuda>=11.0 driver>=450"

NVIDIA_DISABLE_REQUIRE 环境变量

用于禁用所有 NVIDIA_REQUIRE_* 形式的约束的单个开关。

注意

如果您运行的是早于 CUDA 11.7 的 CUDA 基础镜像（并且无法更新到具有更新约束的新基础镜像），则可以通过将 NVIDIA_DISABLE_REQUIRE 设置为 true 来禁用 CUDA 兼容性检查。

NVIDIA_REQUIRE_CUDA 约束

容器使用的 CUDA 工具包的版本。它是通用 NVIDIA_REQUIRE_* 情况的一个实例，由官方 CUDA 镜像设置。如果 NVIDIA 驱动程序的版本不足以运行此版本的 CUDA，则容器将不会启动。此变量可以以 major.minor 的形式指定

此变量的可能值：cuda>=7.5、cuda>=8.0、cuda>=9.0 等等。

Dockerfiles

功能和 GPU 枚举可以通过环境变量在镜像中设置。如果环境变量在 Dockerfile 内部设置，则无需在 docker run 命令行中设置它们。

例如，如果您正在创建自己的自定义 CUDA 容器，则应使用以下内容

ENV NVIDIA_VISIBLE_DEVICES all
ENV NVIDIA_DRIVER_CAPABILITIES compute,utility

这些环境变量已在 NVIDIA 提供的 CUDA 镜像中设置。