tao-setup-nvidia-gpu-host

NVIDIA GPU 主机设置

单独安装？ 如果此会话并非由 TAO 技能库插件初始化，请先运行 tao-setup 技能（主机预检、凭据、跨技能发现）。

在 docker、local-docker 或 kubernetes 后端上运行 TAO 工作流前，请使用此设置技能。TAO 全局默认最低要求如下：

• NVIDIA 驱动程序 >=580（优先使用开放内核模块）
• 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 Toolkit 路径、已安装的 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.io 安装 Docker（可通过 $DOCKER_PACKAGE_DEBIAN 覆盖）。
rhel	Fedora 39+、RHEL / Rocky / AlmaLinux 9 和 10	dnf（或 yum）	添加 NVIDIA cuda-<distro>.repo 和 Container Toolkit .repo。优先在 Fedora 上通过 moby-engine 安装 Docker；若不可用，则通过来自 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.
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 驱动程序、CUDA Toolkit、NVIDIA Container Toolkit，以及 Docker 后端所需的 Docker）的安装并修改主机，因此仅应在你控制的主机上执行。用户直接在终端运行 --install 时则会看到提示。

工作流约定

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

SB="${TAO_SKILL_BANK_PATH:-${TAO_SKILL_BANK_ROOT:-$PWD}}"
SETUP_SCRIPT="${SB}/skills/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
}

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

模型运行时覆盖约定

当模型没有覆盖设置时，使用平台默认值。需要不同的、经过验证的主机堆栈的模型会在 references/skill_info.yaml 中声明相应设置：

runtime_requirements:
  gpu_host:
    min_driver_version: '<version>'
    min_cuda_version: '<version>'
    min_container_toolkit_version: '<version>'

在最终平台预检前读取这些值，并将其传递给匹配的 --min-*-version 标志。模型最低要求仅对该工作流优先适用；不要改写平台默认值或其他模型的要求。版本检查使用数字下限，因此更高且兼容的版本也会通过。始终保留所选镜像的 GPU 冒烟测试，因为版本下限无法证明其支持特定的 GPU 架构。

安装程序的作用

安装程序会根据检测到的发行版系列进行分发。在每个受支持的系列上，它都会添加 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. 从已配置的软件源安装当前版本的开放驱动和 Container Toolkit 软件包，以及由 --min-cuda-version 选择的 CUDA Toolkit 软件包，然后验证这三者是否都满足当前最低要求。
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-open（覆盖项：$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 Toolkit	根据当前最低版本派生的软件包，例如 cuda-toolkit-13-0	同上	同上
Container Toolkit	当前版本的 nvidia-container-toolkit + base/tools/libs，然后进行最低版本验证	同上	同上
Docker	docker.io（覆盖项：$DOCKER_PACKAGE_DEBIAN）	Fedora 上有可用版本时使用 moby-engine+moby-cli，否则从 download.docker.com 安装 docker-ce docker-ce-cli containerd.io	docker

验证

安装后，请验证：

nvidia-smi
nvcc --version
docker info --format '{{json .Runtimes}}' | grep nvidia
sudo docker run --rm --runtime=nvidia --gpus all "$TAO_IMAGE" nvidia-smi -L

检测到的驱动、CUDA Toolkit 和 Container Toolkit 版本必须满足 TAO 全局或特定模型的最低要求。然后运行所选镜像的 GPU 冒烟测试；仅比较版本不足以证明兼容性。

对于 Cosmos 后端，还要根据后端契约扩展冒烟测试，检查 Python 和入口点。Cosmos Framework 必须以非 root UID 执行 /workspace/.venv/bin/python，导入 cosmos_framework.callbacks.tao_status，找到原生 torchrun，并在主机报告计算能力为 8.0 时验证 A100 PatchEmbed 兼容性标记。Cosmos-RL 必须解析其请求的操作可执行文件，在视频工作流中导入系统 PyAV，解析受限的 FFmpeg h264_cuvid 解码器，加载 libnvcuvid.so.1，验证向后兼容的线性 Qwen3-VL PatchEmbed 标记，并验证其检查点加载器能够接受准备好的 qwen3_vl 目录。仅通过 nvidia-smi 的容器尚未准备好运行 Cosmos 训练。

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。

检测到的版本低于当前最低要求：获得批准后，使用相同命令并添加 --install 重新运行，同时保留任何型号专用的 --min-*-version 标志。软件包名称环境变量覆盖项用于选择特定发行版的驱动软件包，但不会放宽最低版本检查。

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

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