holoscan-install-container

Holoscan NGC 容器安装

目的

从 NGC（nvcr.io/nvidia/clara-holoscan/holoscan）拉取并验证官方 Holoscan SDK 容器，根据主机 GPU 选择合适的 CUDA/架构标签，并使用捆绑的 Python 和 C++ 示例进行验证。

先决条件

• 装有 NVIDIA GPU 且驱动正常工作的 Linux 主机（nvidia-smi）。
• 已安装 Docker，且用户属于 docker 组（或使用 sudo）。
• 已安装 NVIDIA Container Toolkit（docker run --gpus all 可以正常运行）。
• 有约 10–20 GB 可用磁盘空间用于拉取镜像。
• 可以访问 nvcr.io 和 docs.nvidia.com。

限制

• 容器镜像仅覆盖下方的标签矩阵 — 容器内没有 Conda/pip 环境。
• GUI 示例需要 X11 转发；此技能以无头模式运行 Holoviz，避免此问题。
• 标签后缀必须与主机 GPU/驱动匹配（cuda13 / cuda12-dgpu / cuda12-igpu）— 后缀不匹配会导致 CUDA 初始化失败。

说明

• 容器仓库：nvcr.io/nvidia/clara-holoscan/holoscan。
• https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html 页面是权威来源 — 如果下方内容有出入，请获取该页面。
• 按顺序完成以下步骤：选择标签，验证 GPU 直通并拉取镜像，使用六个示例进行验证，然后交付启动命令。

步骤 1：选择标签

标签 = <version>-<suffix>，例如 v4.1.0-cuda13。从上述文档页面获取当前 SDK 版本；根据 nvidia-smi 选择后缀（表格标题右上角的 “CUDA Version” 字段）：

nvidia-smi CUDA 版本	后缀
13.x+	cuda13
12.x，Ampere/Ada dGPU	cuda12-dgpu
12.x，ARM64 iGPU（nvgpu）	cuda12-igpu

当容器包含的 CUDA 次要版本高于主机驱动支持的版本时，出现 “CUDA Forward Compatibility mode ENABLED” 提示是预期行为，并非错误。前向兼容性垫片可让容器的 CUDA 运行时在相同主版本内使用较旧的主机驱动。

步骤 2：验证 GPU 直通，然后拉取镜像

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

如果缺少 Docker → 从 https://docs.docker.com/engine/install/ 安装。如果 GPU 直通失败 → 按照 https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html 安装 NVIDIA Container Toolkit，然后重试。

拉取镜像（约 10–20 GB — 开始前提醒用户）：

docker pull nvcr.io/nvidia/clara-holoscan/holoscan:<TAG>

步骤 3：使用六个示例进行验证

测试涵盖：基础 Python 绑定（1a）、基础 C++ 运行时（1b、2a）、Python + Holoviz/Vulkan（2b、3a）以及 C++ + Holoviz/Vulkan（3b）。Holoviz 示例始终以无头模式运行（向 YAML 注入 headless: true）— 无论是否连接显示器都能运行，并避免通过 SSH 使用 GUI 时可能出现的问题。

IMG=nvcr.io/nvidia/clara-holoscan/holoscan:<TAG>
RUN=(docker run --rm --runtime=nvidia --gpus all --cap-add CAP_SYS_PTRACE --ipc=host --ulimit memlock=-1 --ulimit stack=67108864)

# 1a. hello_world (Python) — expect "Hello World!"
"${RUN[@]}" "$IMG" bash -c \
  "ulimit -s 32768 && python3 /opt/nvidia/holoscan/examples/hello_world/python/hello_world.py"

# 1b. hello_world (C++) — expect "Hello World!"
"${RUN[@]}" "$IMG" bash -c \
  "ulimit -s 32768 && /opt/nvidia/holoscan/examples/hello_world/cpp/hello_world"

# 2a. tensor_interop (C++) — expect tensors doubling each pass, "Graph execution finished."
"${RUN[@]}" "$IMG" bash -c \
  "ulimit -s 32768 && /opt/nvidia/holoscan/examples/tensor_interop/cpp/tensor_interop"

# 2b. tensor_interop (Python, 10 frames) — Holoviz, headless. The YAML has no
#     headless field by default, so inject one under `holoviz:`. Expect
#     "message received (count: 10)".
"${RUN[@]}" "$IMG" bash -c "
  ulimit -s 32768
  sed -e 's/count: 0/count: 10/' \
      -e 's/repeat: true/repeat: false/' \
      -e 's/realtime: true/realtime: false/' \
      -e 's/^holoviz:/holoviz:\n  headless: true/' \
      /opt/nvidia/holoscan/examples/tensor_interop/python/tensor_interop.yaml > /tmp/ti.yaml
  cd /opt/nvidia/holoscan/examples/tensor_interop/python
  python3 tensor_interop.py --config /tmp/ti.yaml
"

# 3a. video_replayer (Python, 10 frames) — Holoviz, headless. Inject `headless: true`
#     under `holoviz:` (above `width: 854`). Same sed works for the C++ YAML in 3b —
#     both files share the same `holoviz:` section shape.
"${RUN[@]}" "$IMG" bash -c "
  ulimit -s 32768
  sed -e 's/count: 0/count: 10/' \
      -e 's/repeat: true/repeat: false/' \
      -e 's/realtime: true/realtime: false/' \
      -e 's/^  width: 854/  headless: true\n  width: 854/' \
      /opt/nvidia/holoscan/examples/video_replayer/python/video_replayer.yaml > /tmp/vr.yaml
  cd /opt/nvidia/holoscan/examples/video_replayer/python
  HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data python3 video_replayer.py --config /tmp/vr.yaml
"

# 3b. video_replayer (C++, 10 frames) — same headless injection as 3a. The C++
#     YAML hard-codes `directory: "../data/racerx"`, but HOLOSCAN_INPUT_PATH
#     overrides it, so we don't need to patch that field.
"${RUN[@]}" "$IMG" bash -c "
  ulimit -s 32768
  sed -e 's/count: 0/count: 10/' \
      -e 's/repeat: true/repeat: false/' \
      -e 's/realtime: true/realtime: false/' \
      -e 's/^  width: 854/  headless: true\n  width: 854/' \
      /opt/nvidia/holoscan/examples/video_replayer/cpp/video_replayer.yaml > /tmp/vr_cpp.yaml
  cd /opt/nvidia/holoscan/examples/video_replayer/cpp
  HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data ./video_replayer --config /tmp/vr_cpp.yaml
"

步骤 4：启动命令

• 阅读 https://catalog.ngc.nvidia.com/orgs/nvidia/teams/clara-holoscan/containers/holoscan。
• 向用户说明下方的 docker 标志。
• 告知用户访问该链接以了解其他标志（例如如何挂载 V4L2 视频设备）。

docker run -it --rm \
  --runtime=nvidia --gpus all --cap-add CAP_SYS_PTRACE \
  --ipc=host --ulimit memlock=-1 --ulimit stack=67108864 \
  nvcr.io/nvidia/clara-holoscan/holoscan:<TAG>
# Examples: /opt/nvidia/holoscan/examples/
# Mount files: -v /host/path:/container/path
# GUI examples: add -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY

接下来：

• 探索：ls /opt/nvidia/holoscan/examples/
• 查看一个示例：/holoscan-explain-example

故障排除

• docker: Error response from daemon: could not select device driver "nvidia"。 缺少 NVIDIA Container Toolkit 或尚未正确配置。按照步骤 2 中的链接安装并重启 Docker。
• 容器内 CUDA 初始化失败。 标签后缀与主机不匹配。重新检查 nvidia-smi 的 CUDA Version 和步骤 1 中的表格。
• 启动示例时发生段错误。 容器内未应用 ulimit -s 32768。使用步骤 3 中所示的 bash -c "ulimit -s 32768 && ..." 模式。
• Holoviz 示例卡住 / 通过 SSH 无窗口显示。 YAML 未修改为 headless: true。使用步骤 3 中所示的 sed 注入方式。
• video_replayer 找不到数据。 设置 HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data — 这会覆盖 YAML 中硬编码的路径。