tao-setup-nvidia-gpu-host

NVIDIA GPU 主机设置

在 TAO 工作流使用 docker、local-docker 或 kubernetes 后端运行前，请先使用此设置技能。它会将主机 GPU 运行时统一配置为：

• NVIDIA 驱动程序分支 580（优先使用开源内核模块）
• CUDA Toolkit 软件包 cuda-toolkit-13-0
• NVIDIA Container Toolkit 1.19.0
• Docker 引擎——仅在 docker / local-docker 后端中安装，且仅当 Docker 尚未安装时才安装。所选软件包取决于发行版系列（Debian 系列默认使用 docker.io，RHEL 系列使用 download.docker.com 上的 moby-engine / docker-ce，SUSE 系列使用 docker）。传入 --skip-docker-install 可选择不安装。

默认情况下，检查安全且只读——它适用于任何 Linux 发行版，因为它只会探测 nvidia-smi、CUDA 工具包路径、已安装的 Container Toolkit 软件包版本（通过 dpkg/rpm/nvidia-ctk 二进制文件版本获取），以及 Docker 守护进程的 NVIDIA 运行时。

安装必须获得用户明确授权，并使用 --install 重新运行。以下发行版系列支持自动安装：

系列	已测试的发行版	包管理器	备注
debian	Ubuntu 22.04 / 24.04、Debian 12（以及通过 UBUNTU_CODENAME / VERSION_CODENAME 识别的衍生版 Pop!_OS、Mint、Zorin、Raspbian、KDE Neon 等）	apt-get	添加 NVIDIA cuda-keyring 和 Container Toolkit .list。Docker 使用 docker.io（通过 $DOCKER_PACKAGE_DEBIAN 覆盖）。
rhel	Fedora 39+、RHEL / Rocky / AlmaLinux 9 和 10	dnf（或 yum）	添加 NVIDIA cuda-<distro>.repo 和 Container Toolkit .repo。Docker 优先使用 Fedora 的 moby-engine（若可用），否则使用 download.docker.com 上的 docker-ce。
suse	openSUSE Leap 15、SLES 15	zypper	添加相同的 NVIDIA .repo 文件。Docker 使用发行版的 docker 软件包。
其他（Arch、Alpine、Gentoo、NixOS、FreeBSD、……）	不适用	不适用	--install 会以清晰的错误信息退出，并列出目标版本和 NVIDIA 安装指南 URL。请手动安装，然后重新运行 --check-only。

快速开始

在技能库根目录中：

# Check the local Docker backend host.
bash skills/platform/tao-setup-nvidia-gpu-host/scripts/setup-nvidia-gpu-host.sh --backend docker --check-only

# Install or repair after user approval (prompts for confirmation; see the note below for non-interactive runs).
bash skills/platform/tao-setup-nvidia-gpu-host/scripts/setup-nvidia-gpu-host.sh --backend docker --install

# Check a Kubernetes GPU worker host.
bash skills/platform/tao-setup-nvidia-gpu-host/scripts/setup-nvidia-gpu-host.sh --backend kubernetes --check-only

⚠️ 注意——以非交互方式运行（Agent / 技能运行）： 技能运行没有终端，因此无法回答安装程序的 Continue? [y/N] 确认提示。运行 --check-only 预览缺少的内容并获得用户明确批准后，请在 --install 命令后添加自动确认标志（--yes），以便无需提示即可继续。该标志会自动确认系统软件包的安装（NVIDIA 驱动程序分支 580、CUDA Toolkit 13.0、NVIDIA Container Toolkit，以及 Docker 后端所需的 Docker），并会修改主机：添加 NVIDIA 软件包仓库、可能重启 Docker，并将调用命令的用户添加到 docker 组。因此，只能在你掌控且有权限修改的主机上执行此操作。用户在终端中直接运行 --install 时，脚本会先提示确切的软件包列表，再进行任何更改。

在包含 skills/ 的已安装插件副本中，使用：

bash skills/tao-setup-nvidia-gpu-host/scripts/setup-nvidia-gpu-host.sh --backend docker --check-only

工作流约定

Docker 和 Kubernetes 工作流必须在提交 GPU 任务前运行检查：

SETUP_SCRIPT="${TAO_SKILL_BANK_ROOT:-$PWD}/skills/tao-setup-nvidia-gpu-host/scripts/setup-nvidia-gpu-host.sh"
[ -x "$SETUP_SCRIPT" ] || SETUP_SCRIPT="${TAO_SKILL_BANK_ROOT:-$PWD}/platform/tao-setup-nvidia-gpu-host/scripts/setup-nvidia-gpu-host.sh"

bash "$SETUP_SCRIPT" --backend docker --check-only || {
  echo "MISSING: TAO GPU host runtime is not ready."
  echo "After user approval, run (append --yes for non-interactive agent runs):"
  echo "  bash \"$SETUP_SCRIPT\" --backend docker --install"
  exit 1
}

切勿静默安装。如果检查失败，请说明缺少什么，征求用户对修复的授权，然后运行安装命令并重新运行检查。

安装程序的功能

安装程序会根据检测到的发行版系列执行相应操作。在每个受支持的系列上，安装程序都会添加 NVIDIA 的 CUDA 和 Container Toolkit 软件源（如果尚未添加），安装指定版本的运行时软件包，可选安装 Docker，配置 NVIDIA Docker 运行时，并将运行安装程序的用户添加到 docker 组。

通用步骤（适用于所有系列）：

1. 如果缺少 NVIDIA 的 CUDA 软件源，则添加该软件源（apt 使用 cuda-keyring deb，dnf/zypper 使用 cuda-<distro>.repo）。
2. 如果缺少 NVIDIA 的 Container Toolkit 软件源，则添加该软件源（apt 使用 .list，dnf/zypper 使用 .repo）。
3. 安装与当前运行内核匹配的内核头文件／开发包。
4. 安装驱动程序分支 580 软件包、cuda-toolkit-13-0，以及固定为 1.19.0 版本的 Container Toolkit（dpkg 后缀版本 1.19.0-1 是 apt 中表示相同上游版本的形式）。
5. 对于 Docker 后端，如果尚未安装 Docker，则安装 Docker（可使用下方的覆盖／选择退出标志），启用并启动守护进程，然后运行 nvidia-ctk runtime configure --runtime=docker；如果有 systemctl，则重启 Docker。
6. 将运行安装程序的用户（如果有 $SUDO_USER，则使用该变量；否则使用 $USER）添加到 docker 组，这样后续 shell 无需 sudo 即可运行 docker——使用 --skip-docker-group 可选择不执行此操作。新的组成员身份不会在当前 shell 中生效：请注销后重新登录，或在每个新 shell 中运行 newgrp docker。
7. 尝试运行 modprobe nvidia，以便在重启前通过验证。

各系列的软件包选择：

步骤	debian-family	rhel-family	suse-family
内核头文件	linux-headers-$(uname -r)	kernel-devel-$(uname -r)、kernel-headers-$(uname -r)	kernel-default-devel
驱动程序	nvidia-driver-pinning-580、nvidia-open-580（覆盖项：$NVIDIA_DRIVER_PACKAGE_DEBIAN）	nvidia-driver-cuda、kmod-nvidia-open-dkms（覆盖项：$NVIDIA_DRIVER_PACKAGE_RHEL、$NVIDIA_DRIVER_KMOD_RHEL）	nvidia-open-driver-G06-signed-kmp-default（覆盖项：$NVIDIA_DRIVER_PACKAGE_SUSE）
CUDA 工具包	cuda-toolkit-13-0	cuda-toolkit-13-0	cuda-toolkit-13-0
Container Toolkit	nvidia-container-toolkit=1.19.0-1 + base/tools/libs	nvidia-container-toolkit-1.19.0 + base/tools/libs	与 rhel 相同
Docker	docker.io（覆盖项：$DOCKER_PACKAGE_DEBIAN）	Fedora 上优先使用 moby-engine+moby-cli（如果可用），否则从 download.docker.com 安装 docker-ce docker-ce-cli containerd.io	docker

验证

安装完成后，请验证：

nvidia-smi
/usr/local/cuda-13.0/bin/nvcc --version
docker info --format '{{json .Runtimes}}' | grep nvidia
sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

预期的 nvidia-smi 输出包含驱动程序版本 580.x 和 CUDA Version 13.0。 预期的 nvcc 输出包含 release 13.0。

Kubernetes 说明

对于自管理的 Kubernetes 集群，请在每个 GPU 工作节点上运行主机安装程序，或在安装 NVIDIA GPU Operator 或设备插件之前，将相同的软件包集打包到节点镜像中。

工作流检查还会在 kubectl 可用，但集群报告没有 nvidia.com/gpu 可分配容量时发出警告。这种情况下，请在工作节点主机运行时就绪后安装／配置 NVIDIA GPU Operator：

helm repo add nvidia https://helm.ngc.nvidia.com/nvidia
helm repo update
helm install --wait gpu-operator -n gpu-operator --create-namespace nvidia/gpu-operator

托管 Kubernetes 提供商可能会通过节点镜像或 GPU Operator 策略负责安装驱动程序。未经用户批准且没有回滚计划时，不要覆盖由提供商管理的 GPU 节点。

故障模式

不支持的发行版系列：--install 可自动配置 debian、rhel 和 suse 系列主机。在 Arch、Alpine、Gentoo、NixOS、FreeBSD，或任何没有 /etc/os-release 的系统上（例如 macOS），脚本会退出并显示清晰的错误信息，其中列出四个版本目标和 NVIDIA 上游安装指南的 URL：

• https://docs.nvidia.com/cuda/cuda-installation-guide-linux/
• https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
• https://docs.docker.com/engine/install/

请使用发行版的包管理器安装这四个组件，然后使用 --check-only 重新运行脚本进行验证。检查操作具有通用可移植性——它只会查询二进制文件和软件包数据库——因此，只要运行时已就绪，无论底层发行版是什么，都满足工作流约定。

不支持的 Ubuntu/Debian 衍生版：当 ID 为 pop、mint、zorin、raspbian 或其他 debian 系列衍生版时，脚本会通过 UBUNTU_CODENAME / VERSION_CODENAME 将主机映射到上游 Ubuntu/Debian CUDA 软件源（focal/jammy/noble → Ubuntu 20.04/22.04/24.04；bullseye/bookworm/trixie → Debian 11/12/12）。如果主机的代号与已知上游版本不匹配，--install 会退出，并提供上文所述的相同手动安装指南。

未安装 Docker：--check-only 会报告 MISSING: Docker is not installed，并根据检测到的发行版系列打印适用的准确重运行命令。默认的 --install 路径会安装 Docker（根据系列选择 docker.io / moby-engine / docker-ce / docker），启用并启动守护进程，配置 NVIDIA 运行时，并将调用脚本的用户添加到 docker 组。如果你更愿意自行管理 Docker，请在重新运行脚本前安装 Docker，或传入 --skip-docker-install。

已安装 Docker，但运行 docker run 仍需 sudo：脚本会将调用脚本的用户添加到 docker 组，但 Linux 只有在新的登录会话中才会刷新组成员身份。请注销后重新登录，或在每个新 shell 中运行 newgrp docker，直到新的成员身份生效。

仍缺少 Docker 运行时：重启 Docker，然后重新运行 nvidia-ctk runtime configure --runtime=docker。

检测到的驱动分支 != 580：在 debian 系列上，驱动分支会精确固定为 nvidia-open-580。在 rhel 和 suse 系列上，脚本会安装 NVIDIA CUDA 13.0 软件源中适用于所检测发行版的最新开源驱动，该驱动始终为 ≥ 580。如果你的主机需要更严格的固定版本，请在运行 --install 前将 $NVIDIA_DRIVER_PACKAGE_RHEL / $NVIDIA_DRIVER_KMOD_RHEL / $NVIDIA_DRIVER_PACKAGE_SUSE 设置为你需要的确切软件包名称。

已安装驱动，但 nvidia-smi 失败：使用 sudo modprobe nvidia 加载模块，或重启系统。在启用了安全启动的系统上，可能需要注册 MOK。

Kubernetes 仍无 GPU 容量：使用 nvidia-smi 确认每个 GPU 节点上的驱动都能正常工作，然后检查 GPU Operator / 设备插件 Pod 和节点标签。