---

NVIDIA GPU 容器化必备：Container Toolkit 详解

在当今人工智能、深度学习和高性能计算的浪潮中，GPU 已成为不可或缺的计算核心。无论是训练复杂的神经网络模型，还是进行大规模科学模拟，NVIDIA GPU 都提供了强大的并行计算能力。然而，随着云原生技术和容器化（如 Docker、Podman）的兴起，如何高效、便捷地在容器中利用主机的 NVIDIA GPU 成为了一个关键挑战。标准的容器运行时通常会隔离应用程序与主机硬件，使得直接访问 GPU 变得困难重重。

幸运的是，NVIDIA 官方提供了一个专门的解决方案来打破这一壁垒——NVIDIA Container Toolkit。本文将深入探讨 NVIDIA Container Toolkit 是什么，它为什么是 GPU 容器化的必备工具，其工作原理，如何安装和使用，以及它在现代 GPU 工作流中的重要作用。

一、 容器化 GPU 工作负载的必要性

在深入了解 Container Toolkit 之前，我们先回顾一下为什么我们需要在容器中运行 GPU 工作负载：

1. 环境一致性与可移植性： AI/ML 项目往往依赖于复杂的软件栈，包括特定版本的 CUDA 工具包、cuDNN、深度学习框架（TensorFlow, PyTorch 等）以及各种库。在不同的机器或云环境中部署这些依赖通常费时且容易出错。容器可以将所有依赖打包在一起，形成一个独立、可移植的单元，确保无论在哪里运行，环境都是一致的。
2. 简化部署与扩展： 使用容器编排平台（如 Kubernetes）可以轻松地自动化部署、管理和扩展 GPU 加速的应用。无论是单机多卡还是分布式训练，容器都提供了标准化的部署模型。
3. 隔离性： 容器为应用程序提供了进程、文件系统和网络的隔离，可以防止不同项目或用户之间的环境冲突，提高系统的稳定性和安全性。
4. 依赖管理： 容器镜像可以锁定特定版本的依赖，避免了“在我机器上可以运行”的问题，极大地简化了版本管理和问题排查。

尽管容器带来了诸多优势，但它们在设计上通常是为了隔离主机资源。传统的容器默认情况下无法直接看到或使用主机上的 NVIDIA GPU 设备及其相关的驱动库。这是因为 GPU 设备（如 /dev/nvidia0, /dev/nvidiactl 等）以及 NVIDIA 驱动的用户空间库位于主机的文件系统中，容器通常只能访问自己的文件系统视图。简单地通过 docker run -v /usr/lib/x86_64-linux-gnu:/usr/lib/x86_64-linux-gnu -v /dev:/dev 尝试将设备和库挂载进去不仅繁琐，而且容易引入兼容性问题，尤其是在容器内的 CUDA 版本与主机驱动不完全匹配时。

这就引出了 NVIDIA Container Toolkit 的核心价值。

二、 NVIDIA Container Toolkit 是什么？

NVIDIA Container Toolkit（前身为 nvidia-docker）是一套工具和库，它使得标准的容器运行时（如 Docker、Podman、containerd、CRI-O）能够感知并利用主机上的 NVIDIA GPU。它不是一个独立的容器运行时，而是一个与现有运行时集成的组件。

简单来说，Container Toolkit 的作用就像一座桥梁，连接了容器的隔离环境与主机上的 NVIDIA GPU 硬件及驱动。它通过在容器启动过程中动态地向容器注入必要的设备文件、驱动库以及环境变量，使得容器内的应用程序能够像在主机上一样访问和使用 GPU。

三、 nvidia-docker 到 Container Toolkit 的演进

了解 Container Toolkit 的历史有助于理解其设计理念。

最初，NVIDIA 推出了 nvidia-docker，它实际上是一个 Docker 的包装器脚本。当用户运行 nvidia-docker run ... 命令时，nvidia-docker 脚本会解析命令，然后调用底层的 Docker CLI，但在调用之前，它会向 Docker 传递一些额外的参数，用于将主机的 /dev/nvidia* 设备和 NVIDIA 驱动库目录绑定挂载到容器内部，并设置一些环境变量。

这种包装器的方式虽然解决了问题，但它紧耦合于 Docker，并且依赖于 nvidia-docker 这个额外的命令。随着容器生态系统的发展，特别是 Docker Engine 逐渐被更低层的容器运行时（如 containerd 和 CRI-O）所取代，以及 Kubernetes 成为主流的容器编排平台，一个更通用、更符合开放容器倡议（OCI）标准的解决方案变得必要。

NVIDIA Container Toolkit 正是为了满足这一需求而诞生的。它不再是一个简单的包装器，而是作为容器运行时的一个 低层组件或钩子（Hook） 工作。它符合 OCI 运行时规范，可以与任何支持 OCI 运行时规范的容器运行时集成。现代的 Docker Engine 后端也通常是基于 containerd，因此 Container Toolkit 可以直接配置到 Docker 的后台运行时中，使得用户可以直接使用标准的 docker run --gpus ... 命令来启用 GPU。

这种转变使得 NVIDIA GPU 的容器化集成更加标准化、灵活，并能更好地与 Kubernetes 等容器编排平台协同工作。

四、 Container Toolkit 的工作原理详解

NVIDIA Container Toolkit 的核心原理是在容器启动的早期阶段，通过与容器运行时交互，动态地修改容器的配置，使其能够访问主机 GPU 资源。具体流程大致如下：

1. 用户请求 GPU 资源： 用户通过容器运行时接口（如 Docker CLI 的 --gpus 参数，或者 Kubernetes 的 Pod 资源配置中的 nvidia.com/gpu 资源请求）指明该容器需要访问 GPU。
2. 容器运行时解析请求： 容器运行时（如 containerd, CRI-O, 或 Docker Engine 的 containerd 后端）接收到创建容器的请求，并识别出对 GPU 资源的需求。
3. 调用 OCI Runtime / Hooks： 容器运行时根据其配置，可能会调用一个特定的 OCI 运行时（如 nvidia-container-runtime），或者在容器生命周期的特定阶段触发配置好的 OCI 钩子（prestart hook 是常用的）。
4. NVIDIA Container Toolkit 介入： nvidia-container-toolkit 包中的核心库 libnvidia-container 被调用。这个库负责：
   • 检测主机环境： 扫描主机上的 /dev/nvidia* 设备，确定可用的 GPU。
   • 识别驱动版本： 读取主机的 NVIDIA 驱动信息。
   • 定位驱动库： 查找主机上 NVIDIA 驱动的用户空间库文件（例如 /usr/lib/x86_64-linux-gnu/nvidia, /usr/lib32/nvidia 等）。
   • 定位 CUDA 库 (可选/根据镜像)： 如果容器镜像是一个基于 nvidia/cuda:*-base 的基础镜像（这些基础镜像通常不包含完整的 CUDA 工具包和用户空间库），libnvidia-container 还可以选择性地检测主机上的 CUDA 安装，并将兼容的 CUDA 用户空间库注入到容器中。但更常见和推荐的做法是使用包含了完整 CUDA 工具包的 nvidia/cuda:* 镜像，这种情况下，Container Toolkit 主要负责注入设备和驱动库。
   • 处理设备和库： 基于用户指定的 GPU 需求（--gpus all, --gpus 0,1, --gpus '"device=GPU-UUID"' 等）和检测到的主机资源，libnvidia-container` 生成一个包含以下信息的配置：
     • 需要挂载到容器内的设备文件列表（例如 /dev/nvidia0, /dev/nvidiactl, /dev/nvidia-uvm, /dev/nvidia-modeset 等）。
     • 需要绑定挂载到容器内的驱动库目录列表。这些库会被挂载到容器内的特定位置，并通过设置环境变量 LD_LIBRARY_PATH 等方式确保容器内的应用程序能够找到它们。
     • 必要的环境变量，例如 NVIDIA_VISIBLE_DEVICES（指定容器内可见的 GPU）、NVIDIA_DRIVER_CAPABILITIES（指定驱动功能，如 compute, utility, graphics 等）。
5. 修改 OCI 配置： libnvidia-container 将这些设备挂载、卷挂载和环境变量信息添加到容器的 OCI 配置（一个 JSON 文件）中。
6. 容器运行时继续启动： 容器运行时拿到修改后的 OCI 配置，然后根据这个配置使用低层的 OCI 运行时（如 runc）启动容器。在启动过程中，运行时会按照配置执行设备和卷的挂载操作，并设置环境变量。
7. 容器内应用访问 GPU： 容器启动后，其内部的环境变量和文件系统已经被配置好，应用程序（如使用 CUDA、TensorFlow、PyTorch 编写的程序）可以通过标准的 CUDA API 或其他库访问到 /dev/nvidia* 设备，并通过加载注入的驱动库来与 GPU 进行交互。

关键点在于：

• Container Toolkit 负责将主机的 NVIDIA 驱动用户空间库注入到容器中。这解决了容器内应用程序与主机驱动版本兼容性的问题。容器内的应用程序通过这些注入的库与主机的驱动通信。
• 它根据用户指定的 --gpus 参数，精确控制容器内可见的 GPU 设备，实现 GPU 的隔离和分配。
• 它自动化了这个过程，用户无需手动查找设备文件和驱动库路径。

五、 安装 NVIDIA Container Toolkit

安装 NVIDIA Container Toolkit 需要几个先决条件：

1. 支持的操作系统： 通常是主流的 Linux 发行版（Ubuntu, CentOS/RHEL, Fedora 等）。
2. 正确安装的 NVIDIA 驱动： 主机上必须已经安装了与 GPU 硬件兼容且功能正常的 NVIDIA 驱动程序。这是 Toolkit 工作的基础。可以使用 nvidia-smi 命令验证驱动是否正常工作。
3. 支持的容器运行时： Docker Engine (19.03+ 推荐)、Podman (3.0+ 推荐)、containerd、CRI-O 等。

安装步骤通常涉及添加 NVIDIA 的官方软件包仓库，然后通过系统的包管理器进行安装。以 Ubuntu 为例：

“`bash

1. 添加 NVIDIA 包仓库 (如果尚未添加 NVIDIA 驱动仓库)

根据你的系统版本选择正确的 distribution (e.g., ubuntu18.04, ubuntu20.04, ubuntu22.04)

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | sudo apt-key add –
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

2. 更新包列表

sudo apt-get update

3. 安装 nvidia-container-toolkit

sudo apt-get install -y nvidia-container-toolkit

4. 配置 Docker daemon 使用 nvidia 运行时 (对于 Docker Engine)

这一步通常由安装脚本自动完成，但如果遇到问题，可以手动执行

sudo nvidia-ctk runtime configure –runtime=docker

5. 重启 Docker daemon 使配置生效 (对于 Docker Engine)

sudo systemctl restart docker

如果使用其他运行时（如 containerd 或 CRI-O），则需要根据其文档进行相应的配置。

例如，对于 containerd，可能需要在其配置文件 /etc/containerd/config.toml 中添加 nvidia 运行时配置。

“`

安装完成后，可以使用以下命令进行验证：

“`bash

验证 nvidia-container-toolkit 安装是否成功

nvidia-ctk –version

使用 Docker 验证 GPU 访问

运行一个基于 NVIDIA CUDA 基础镜像的容器，并在其中执行 nvidia-smi 命令

–rm: 容器退出后自动删除

–gpus all: 允许容器访问所有 GPU

docker run –rm –gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

预期输出应该是在容器内成功执行 nvidia-smi 并显示主机 GPU 信息。

如果只想访问特定 GPU (例如 GPU 0 和 1)

docker run –rm –gpus 0,1 nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

如果只想访问特定功能 (例如 utility capabilities)

docker run –rm –gpus all –env NVIDIA_DRIVER_CAPABILITIES=utility nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi
“`

如果 docker run --gpus all ... nvidia-smi 命令成功并显示 GPU 信息，则表明 Container Toolkit 已正确安装并与 Docker 集成。

六、 使用 Container Toolkit 运行 GPU 容器

现代容器运行时通过简单的命令行参数来启用 GPU 访问，这得益于 Container Toolkit 在后台的处理。

使用 Docker

使用 Docker 时，主要通过 --gpus 参数来控制 GPU 访问。

• 访问所有 GPU：
  bash
docker run --gpus all your_gpu_image:tag your_command
• 访问特定 GPU (按索引)： GPU 索引从 0 开始。
  bash
docker run --gpus 0,1 your_gpu_image:tag your_command # 访问 GPU 0 和 1
docker run --gpus 2 your_gpu_image:tag your_command # 访问 GPU 2
• 访问特定 GPU (按 UUID 或设备路径)： 对于多用户环境或需要精确控制时很有用。可以通过 nvidia-smi -L 查看 GPU UUID。
  bash
docker run --gpus '"device=GPU-f9f1c2d3-4b5e-6f7a-8b9c-0d1e2f3a4b5c"' your_gpu_image:tag your_command
docker run --gpus '"device=/dev/nvidia1"' your_gpu_image:tag your_command
• 限制功能： 可以通过设置环境变量 NVIDIA_DRIVER_CAPABILITIES 来限制容器可以使用的驱动功能，例如只允许计算 (compute) 功能，禁止图形 (graphics) 功能。通常 --gpus 参数会结合这个环境变量一起工作， --gpus 默认启用 utility,compute 等常用功能。你也可以手动覆盖。
  bash
docker run --gpus all -e NVIDIA_DRIVER_CAPABILITIES=compute your_gpu_image:tag your_command

使用 Podman

Podman 使用类似的 --gpu 参数（注意是单数 gpu）。

bash
podman run --gpu all your_gpu_image:tag your_command
podman run --gpu 0,1 your_gpu_image:tag your_command

Podman 也依赖于底层的 libnvidia-container 库。

使用 Kubernetes

在 Kubernetes 中利用 GPU 需要安装 NVIDIA Device Plugin for Kubernetes。这个 Device Plugin 负责：

1. 发现节点上的 NVIDIA GPU 资源，并通过 Kubernetes 的 Device Plugin API 向 kubelet 注册这些资源。
2. 当用户 Pod 请求 nvidia.com/gpu 资源时，kube-scheduler 会将 Pod 调度到有可用 GPU 的节点上。
3. 在 Pod 启动时，kubelet 会调用 Device Plugin 的 Allocate gRPC 请求。Device Plugin 会与底层的容器运行时（如 containerd 或 CRI-O，它们需要配置了 Container Toolkit）交互，指示运行时为该 Pod 的容器分配指定的 GPU 资源。
4. 最终，底层容器运行时（利用 Container Toolkit 的能力）将正确的设备、库和环境变量注入到 Pod 的容器中。

因此，在 Kubernetes 集群中，节点的 kubelet 需要配置一个支持 GPU 的容器运行时（如配置了 Container Toolkit 的 containerd），并且集群中需要部署 NVIDIA Device Plugin。用户只需在 Pod 的 YAML 文件中声明对 nvidia.com/gpu 资源的请求即可：

yaml
apiVersion: v1
kind: Pod
metadata:
name: gpu-pod
spec:
containers:
- name: cuda-container
image: your_gpu_image:tag
resources:
limits:
nvidia.com/gpu: 1 # 请求 1 个 GPU
command: ["your_command"]

Container Toolkit 是 Kubernetes 中实现 GPU 资源调度的底层基础之一。

七、 Container Toolkit 的配置与高级选项

nvidia-container-toolkit 的行为可以通过配置文件进行调整，主配置文件通常位于 /etc/nvidia-container-runtime/config.toml 或相关位置。通过修改此文件，可以控制 Toolkit 如何检测设备、库以及注入哪些环境变量等。

一些常见的配置场景包括：

• 禁用驱动要求检查 (disable-require)： 默认情况下，Toolkit 会检查主机驱动和容器镜像中的 CUDA 版本是否兼容。在某些特定场景下，你可能需要禁用这个检查（不推荐）。
• 排除某些功能 (exclude-capabilities)： 默认注入所有常用功能（compute, utility 等），你可以排除不需要的功能。
• 自定义注入的库路径： 在非标准安装路径下有用。

修改配置文件后，通常需要重启容器运行时服务。

此外，Container Toolkit 提供的 nvidia-ctk 命令行工具也很有用，可以用来检查配置、验证安装以及执行一些诊断操作。

八、 重要性与总结

NVIDIA Container Toolkit 是现代 NVIDIA GPU 容器化工作流中的基石。它解决了容器隔离环境与主机 GPU 硬件之间的核心矛盾，实现了 GPU 资源的无缝、高效、安全地容器化访问。

通过 Container Toolkit，开发者和运维人员可以：

• 构建包含特定深度学习框架和 CUDA 版本的容器镜像，并确保它们可以在任何安装了兼容驱动和 Toolkit 的主机上运行。
• 利用容器编排平台（如 Kubernetes）轻松调度和管理 GPU 工作负载，实现资源的高效利用和弹性伸缩。
• 为不同的项目或用户提供隔离的 GPU 环境，避免依赖冲突。
• 简化 GPU 应用的打包、分发和部署流程。

总之，无论是进行深度学习研究、模型训练、推理部署，还是运行高性能计算任务，只要涉及到在容器中使用 NVIDIA GPU，NVIDIA Container Toolkit 都是一个不可或缺的组件。掌握其原理、安装和使用方法，对于构建高效、可移植的 GPU 容器化应用至关重要。它极大地降低了在容器环境中利用 GPU 的复杂性，使得开发者能够更专注于应用程序本身，而不是底层的基础设施。

随着 AI 和 HPC 的不断发展，容器化将变得越来越普遍，而 NVIDIA Container Toolkit 将继续扮演连接软件与硬件的关键角色，助力创新和发现。

---