holoscan-install-container

本指南用于通过 NGC Docker 容器安装 Holoscan SDK，仅覆盖容器方式，不涉及 apt/pip/Conda 原生安装。前置条件：具备 NVIDIA GPU 和可用驱动的 Linux 主机（nvidia-smi 可用）、已安装 Docker 且用户在 docker 组（或使用 sudo）、已安装 NVIDIA Container Toolkit（docker run --gpus all 可用）、约 10–20 GB 可用磁盘空间，以及能访问 nvcr.io 和 docs.nvidia.com。容器仓库为 nvcr.io/nvidia/clara-holoscan/holoscan。安装按以下顺序进行：一、选择标签，格式为 <version>-<suffix>，后缀根据 nvidia-smi 的 CUDA Version 字段选择：13.x 及以上用 cuda13，12.x 且为 Ampere/Ada 独立 GPU 用 cuda12-dgpu，12.x 且为 ARM64 iGPU 用 cuda12-igpu；后缀与主机不匹配会导致 CUDA 初始化失败。二、验证 GPU 直通并拉取镜像：docker run --rm --gpus all ubuntu:22.04 nvidia-smi，缺失 Docker 或直通失败时按官方链接安装相应组件；拉取命令为 docker pull nvcr.io/nvidia/clara-holoscan/holoscan:<TAG>。三、用六个示例验证，覆盖 Python 与 C++ 绑定及 Holoviz/Vulkan，Holoviz 示例统一以 headless 方式运行，通过在 YAML 中注入 headless: true 并通过 sed 调整计数与重复等参数实现，示例位于 /opt/nvidia/holoscan/examples/。四、给用户的启动命令使用 --runtime=nvidia --gpus all --cap-add CAP_SYS_PTRACE --ipc=host --ulimit memlock=-1 --ulimit stack=67108864，可加 -v 挂载文件；GUI 示例还需挂载 X11。限制：容器镜像仅覆盖上述标签矩阵，内部不含 Conda/pip 环境；GUI 示例需 X11 转发。故障排查包括：缺少或未配置 NVIDIA Container Toolkit 时出现设备驱动选择错误；标签后缀不匹配导致 CUDA 初始化失败；未在容器内执行 ulimit -s 32768 导致段错误；YAML 未改为 headless 导致 Holoviz 示例挂起；video_replayer 找不到数据时设置 HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data。