⚡

NVIDIAGPU主机环境配置Skill tao-setup-nvidia-gpu-host

检查并安装 NVIDIA GPU 主机所需的驱动、CUDA 工具包、容器工具包和 Docker，为 TAO Docker/Kubernetes 工作流准备 GPU 环境。支持 debian/rhel/suse 系 Linux 发行版，提供只读检查和自动安装模式。关键词：NVIDIA、GPU驱动、CUDA、NVIDIA容器工具包、Docker、Kubernetes、TAO、主机环境设置。

智能体工具 0 次安装 0 次浏览 更新于 9/6/2026
名称 tao-setup-nvidia-gpu-host
描述 >- 用于 TAO GPU 后端的主机设置。检查并在用户批准后安装最低兼容的 NVIDIA 驱动、CUDA 工具包和 NVIDIA 容器工具包版本，适用于 Docker/local-Docker 和 Kubernetes GPU 工作节点。TAO 范围的默认值可以被所选模型的运行时配置文件覆盖。--check-only 路径适用于任何 Linux 发行版；--install 自动化 debian 系（Ubuntu/Debian/Pop!_OS/Mint/Zorin/Raspbian）、rhel 系（Fedora/RHEL/Rocky/AlmaLinux）和 suse 系（openSUSE/SLES）主机，并为其他发行版打印可行的手动安装步骤。当用户要求“设置 NVIDIA GPU 主机”、“检查 TAO Docker GPU 运行时”或为 TAO 准备 Kubernetes GPU 工作节点时使用。
开源协议 Apache-2.0 compatibility: 在任何 Linux 发行版上运行 --check-only。--install 自动化 Ubuntu 22.04/24.04 + Debian 12 (apt)、Fedora + RHEL/Rocky/AlmaLinux 9/10 (dnf) 和 openSUSE Leap / SLES 15 (zypper)。需要 sudo/root、可访问 NVIDIA 软件包仓库（以及 rhel 系上的 download.docker.com）的互联网连接，以及 x86_64 或 aarch64 (sbsa) 主机。其他发行版（Arch、Alpine、Gentoo、NixOS 等）会得到清晰的错误，指明版本目标和 NVIDIA 安装指南 URL。 metadata:
作者 NVIDIA Corporation
版本 “0.1.1” allowed-tools: Read Bash tags: - setup - nvidia - cuda - docker - kubernetes

NVIDIA GPU 主机设置

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

在 TAO 工作流运行于 docker、local-docker 或 kubernetes 后端之前，使用此设置技能。TAO 范围的默认最低版本：

  • NVIDIA 驱动 >=580（优先使用开源内核模块）
  • CUDA 工具包 >=13.0
  • NVIDIA 容器工具包 >=1.19.0
  • Docker 引擎——仅为 docker / local-docker 后端安装，且仅在 Docker 缺失时安装。所选包取决于发行版系列（debian 系默认为 docker.io，RHEL 系为 moby-engine / 来自 download.docker.com 的 docker-ce，SUSE 系为 docker）。传递 --skip-docker-install 以选择不安装。

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

安装必须由用户明确授权，并通过 --install 重新运行。安装路径为以下发行版系列自动化：

系列 已测试的发行版 管理器 备注
debian Ubuntu 22.04 / 24.04、Debian 12（及派生版本 Pop!_OS、Mint、Zorin、Raspbian、KDE Neon 等，通过 UBUNTU_CODENAME / VERSION_CODENAME） 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 软件包。
other (Arch、Alpine、Gentoo、NixOS、FreeBSD 等) 不适用 不适用 --install 退出并显示清晰的错误，列出版本目标和 NVIDIA 安装指南 URL。手动安装，然后重新运行 --check-only。

快速开始

从技能库根目录开始：

# 检查本地 Docker 后端主机。
bash skills/platform/tao-setup-nvidia-gpu-host/scripts/setup-nvidia-gpu-host.sh --backend docker --check-only

# 在用户批准后安装或修复。
bash skills/platform/tao-setup-nvidia-gpu-host/scripts/setup-nvidia-gpu-host.sh --backend docker --install

# 检查 Kubernetes GPU 工作节点主机。
bash skills/platform/tao-setup-nvidia-gpu-host/scripts/setup-nvidia-gpu-host.sh --backend kubernetes --check-only

⚠️ **注意——非交互式运行（Agent/技能运行）：**技能运行没有终端，因此安装程序的 继续？[y/N] 提示无法回答。在运行 --check-only 预览并获得用户批准后，请在 --install 命令后附加 --yes 标志，以便无需提示继续——这会自动确认安装系统包（NVIDIA 驱动、CUDA 工具包、NVIDIA 容器工具包，以及用于 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 "缺失：TAO GPU 主机运行时尚未就绪。"
  echo "获得用户批准后，运行（对于非交互式 Agent 运行请追加 --yes）："
  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 和容器工具包仓库（如果缺失），安装满足活动最低要求的软件包，可选地安装 Docker，连接 NVIDIA Docker 运行时，并将调用用户添加到 docker 组。

通用步骤（所有系列）：

  1. 如果缺失，添加 NVIDIA 的 CUDA 仓库（apt cuda-keyring deb、dnf/zypper 的 cuda-<distro>.repo）。
  2. 如果缺失，添加 NVIDIA 的容器工具包仓库（apt 的 .list、dnf/zypper 的 .repo）。
  3. 为正在运行的内核安装匹配的内核头文件 / devel 软件包。
  4. 从配置的仓库安装当前的开源驱动和容器工具包软件包，以及通过 --min-cuda-version 选择的 CUDA 工具包软件包，然后根据活动最低要求验证全部三个。
  5. 对于 Docker 后端且缺少 Docker 时，安装 Docker（覆盖/退出标志如下），在可用时通过 systemctl 启用/启动守护程序，然后运行 nvidia-ctk runtime configure --runtime=docker 并重新启动 Docker。
  6. 将调用用户（如果有 $SUDO_USER，否则 $USER）添加到 docker 组，以便后续 shell 无需 sudo 即可运行 docker——通过 --skip-docker-group 选择不执行。新组会员资格在当前 shell 中不会生效：注销并重新登录，或在每个新 shell 中运行 newgrp docker。
  7. 尝试 modprobe nvidia，以便验证可以在重启之前通过。

特定系列的包选择：

步骤 debian 系列 rhel 系列 suse 系列
内核头文件 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 工具包 从活动最低值派生的软件包，例如 cuda-toolkit-13-0 相同 相同
容器工具包 当前 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 工具包和容器工具包版本必须满足活动的 TAO 范围或特定模型最低要求。然后运行所选图像的 GPU 冒烟测试；仅版本比较不足以证明兼容性。

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（focal/jammy/noble → Ubuntu 20.04/22.04/24.04；bullseye/bookworm/trixie → Debian 11/12/12）将主机映射到上游 Ubuntu/Debian CUDA 仓库。如果主机的代号与已知的上游版本不匹配，--install 会退出并给出上面描述的手动安装指南。

Docker 未安装：--check-only 报告 缺失：Docker 未安装 并打印适合检测到的发行版系列的确切重新运行命令。默认 --install 路径安装 Docker（根据系列选择 docker.io / moby-engine / docker-ce / docker），启用/启动守护程序，配置 NVIDIA 运行时，并将调用用户添加到 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 和节点标签。