holoscan-setup

Holoscan SDK 设置

目的

通过检查硬件、操作系统、CUDA 驱动程序和现有工具，确定当前主机适用的 Holoscan SDK 安装方法，然后委派给针对该方法的安装技能。涵盖 Ubuntu、RHEL、IGX Orin、Jetson 和 DGX Spark / Grace-Hopper 平台上的 NGC 容器、Debian/apt、pip wheel、Conda 和源码构建。

先决条件

• Linux 主机（Ubuntu 22.04/24.04、RHEL 9.x、IGX Orin、Jetson 或 DGX Spark / Grace-Hopper）
• 配有正常工作的驱动程序的 NVIDIA GPU（nvidia-smi 会返回 CUDA Version）
• 可访问 docs.nvidia.com 和 NGC 的网络
• 以下任一项：Docker + NVIDIA Container Toolkit、apt、带有 pip 的 Python 3.10–3.13、Conda，或构建工具链，具体取决于所选方法

可用脚本

脚本	用途	参数
scripts/check_conda.sh	即使 Conda 不在 PATH 中也能检测到其安装（搜索 ~/miniconda3、~/miniforge3、~/anaconda3、~/mambaforge、/opt/conda 和 shell rc 文件）；报告环境以及哪些环境可以导入 holoscan。	无
scripts/check_ngc_image.sh	检查指定 CUDA 标签后缀对应的 NGC Holoscan 容器镜像是否已拉取或可用。	<cuda-tag-suffix> — 可选 cuda13、cuda12-dgpu、cuda12-igpu

使用 run_script("scripts/check_conda.sh") 和 run_script("scripts/check_ngc_image.sh", "cuda13") 调用脚本。请以脚本输出为准，不要仅凭 which conda 或 docker images 等命令判断。

说明

采用对话式、逐步推进的方式，不要一开始就提供全部信息。完成每一步后，先报告结果再继续。

工作流规则（必须遵守）

1. 在第 5 步结束时，用加粗的一行建议点明方法（例如：**Recommendation:** NGC Container — bundles all deps, fastest path to a working install.）。
2. 对于受支持的 x86_64 主机上的首次使用者，如果 Docker 可用，建议方法必须是 NGC Container。
3. 给出建议后，停止并询问用户要使用哪种方法。此轮不要粘贴 docker pull、docker run、apt install、pip install 或其他安装命令；这些命令应由第 6 步委派的安装技能提供。
4. 如果考虑使用容器路径，请在第 4 步中自行验证 Docker + GPU 直通（运行该步骤所示命令）。不要让用户替你运行 nvidia-smi 或 docker --version。

第 1 步：先阅读文档

先获取 https://docs.nvidia.com/holoscan/sdk-user-guide/，再获取 sdk_installation.html，了解当前版本支持的平台、软件包名称和安装要求。不要依赖硬编码假设。

第 2 步：检查计算机

并行运行：

uname -a && (lsb_release -a 2>/dev/null || cat /etc/os-release)
uname -m
nvidia-smi 2>&1 | head -10
nproc && free -h | head -2

**说明：**读取 nvidia-smi 中的“CUDA Version”字段（表格标题右上角）；这是驱动程序支持的 最高 CUDA 版本，并决定选择 cuda12 还是 cuda13 软件包。

第 3 步：评估兼容性

平台	可用方法
Ubuntu 22.04/24.04，x86_64	容器、Debian/apt、pip wheel、Conda、源码
RHEL 9.x，x86_64	仅容器
IGX Orin（ARM64）	容器、Debian/apt、源码
Jetson AGX Orin / Orin Nano	容器、Debian/apt（iGPU）
Jetson AGX Thor	容器、Debian/apt
DGX Spark / Grace-Hopper	容器（请查阅文档了解操作系统要求）
其他 Linux，x86_64	容器可能可用；glibc ≥ 2.35 时可使用 pip wheel

步骤 4：检查工具并提供选项

并行运行：

docker --version 2>&1 | head -1; python3 --version 2>&1; pip3 --version 2>&1
dpkg -l | grep holoscan || true
pip3 show holoscan 2>/dev/null | grep -E "^(Name|Version)" || true
~/holoscan/venv/bin/pip show holoscan 2>/dev/null | grep -E "^(Name|Version)" | sed 's/^/venv: /' || true

然后自行验证 GPU 直通——不要让用户运行此命令：

docker run --rm --gpus all ubuntu:22.04 nvidia-smi 2>&1 | tail -5 || true

根据结果填写步骤 5 中的 Status 列：

• 缺少 docker → 容器行的 Status 为 ✗ — Docker not installed。
• 已安装 Docker，但出现 could not select device driver "nvidia" → ✗ — NVIDIA Container Toolkit missing。
• 出现 nvidia-smi 输出 → ✓。

然后通过 run_script 调用检测脚本：

• run_script("scripts/check_conda.sh") — 查看上文的 Available Scripts，了解为何优先使用此脚本，而非 conda --version。
• run_script("scripts/check_ngc_image.sh", "<cuda-tag-suffix>") — 将 <cuda-tag-suffix> 替换为步骤 2 中确定的标签（例如 cuda13、cuda12-dgpu、cuda12-igpu）。

如果已安装 Holoscan，请注明版本，并询问用户是要升级还是验证现有安装。

CUDA 变体规则（权威参考——以下所有步骤均须遵循）：

nvidia-smi CUDA 版本	原生软件包	容器标签
13.x+	holoscan-cu13 / holoscan-cuda-13	cuda13
12.x，Blackwell GPU	holoscan-cu12 / holoscan-cuda-12	cuda13（Forward Compat）或 cuda12-dgpu
12.x，Ampere/Ada dGPU	holoscan-cu12 / holoscan-cuda-12	cuda12-dgpu
ARM64 iGPU（Jetson、IGX）	holoscan	cuda12-igpu

原生安装将驱动 CUDA 版本视为硬性上限。容器支持 Forward Compatibility（出现“CUDA Forward Compatibility mode ENABLED”横幅属于预期情况，并非错误）。

步骤 5：提供选项并给出建议

表格中始终列出所有方法——不得省略任何一行。使用 Status 列标明该方法在主机上的可用性（不可用的方法显示 ✗，并附简短原因）。使用以下表格格式：

方法	适用场景	状态
NGC 容器	已包含所有依赖项（CUDA、TensorRT、LibTorch、ONNX Runtime、Vulkan）；支持 C++ 和 Python。需要 Docker + NVIDIA Container Toolkit。	根据 docker 是否存在标为 ✓/✗
Debian/apt	原生 Ubuntu；仅支持 C++	如果已安装软件包则标为 ✓/✗
pip wheel	仅限 Python 项目；需要 PATH 中有 CUDA Toolkit；Python 3.10–3.13。	如果虚拟环境 ~/holoscan/venv 中已安装 wheel，则标为 ✓/✗
Conda	仅支持 CUDA 13；适合已处于 conda 环境中的情况。	根据 check_conda.sh 的输出标为 ✓/✗（不能只看 which conda）
Source	修改 SDK 内部内容、自定义 CMake 标志、调试符号、不受支持的平台或尚未发布的分支。	如果已克隆到 ~/holoscan/holoscan-sdk，则标为 ✓/✗

表格后，以以下两行的确切格式结束本轮回复：

建议： <method> — <one-line why>

你想使用哪种方法？（container / apt / wheel / conda / source）

如果用户是 Holoscan 新手，且主机是受支持的 x86_64 平台并且有 Docker，则建议使用 NGC 容器。对于 RHEL 9 或其他只能使用容器的主机，建议使用容器。对于没有 Docker 的主机上的纯 Python 项目，建议使用 pip wheel。

本轮不要包含 docker pull、docker run、apt install 或 pip install 命令——这些命令属于步骤 6 中调用的安装技能。请保持回复简短，避免表格显示到一半时被截断。

步骤 6：委托给安装技能

选定安装方式后，调用相应的技能——不要直接重复列出安装步骤：

方式	要调用的技能
NGC 容器	/holoscan-install-container
Debian/apt	/holoscan-install-debian
pip wheel	/holoscan-install-wheel
Conda	/holoscan-install-conda
源码	/holoscan-install-source

调用技能时，将 CUDA 变体（cu12/cu13/igpu）以及步骤 2–4 中的其他相关信息作为上下文传入。

安装技能负责提供完整的命令集，包括推荐的容器标志（--gpus all、--ipc=host、--ulimit memlock=-1、--ulimit stack=67108864、内部的 ulimit -s 32768）和验证示例。不要在 holoscan-setup 中重复列出这些内容；请委托给安装技能，由它生成相关内容。

步骤 7：总结

如果安装成功且运行了测试，请输出测试结果汇总表。

限制

• RHEL 9.x 仅支持 NGC 容器方式——不提供原生软件包。
• Conda 软件包仅支持 CUDA 13；CUDA 12 主机必须使用容器、apt、pip wheel 或源码方式。
• 从 Holoscan v3.0.0 起，Debian/apt 仅安装 C++；Python 支持需要额外安装 pip wheel。
• pip wheel 要求 glibc ≥ 2.35 和 Python 3.10–3.13。
• 原生安装不能使用高于驱动报告的 CUDA Version；只有容器支持 CUDA 向前兼容。
• DGX Spark / Grace-Hopper 的操作系统要求会随版本变化——务必重新检查 sdk_installation.html。

故障排除

• conda --version 显示“command not found”，但已安装 Conda — 这在使用延迟加载 Conda 的 zsh 配置中很常见，也可能是因为只有 .bashrc 运行了 conda init。使用 run_script("scripts/check_conda.sh")；它会搜索安装目录和 rc 文件。
• nvidia-smi 显示的 CUDA Version 低于预期 — 该字段表示驱动支持的最高 CUDA 版本，而不是已安装的工具包版本。安装较新 CUDA 软件包前，请先升级驱动。
• Debian 安装成功，但 Python 中 import holoscan 失败 — 从 v3.0.0 起，apt 仅安装 C++。请继续安装 /holoscan-install-wheel。
• pip install holoscan 因 glibc 错误而失败 — 主机上的 glibc 版本低于 2.35。请改用容器或 apt。
• check_ngc_image.sh 报告映像缺失 — 请确认已登录 NGC（docker login nvcr.io），并确认标签后缀符合步骤 4 中的 CUDA 变体规则。