Installation du conteneur Holoscan NGC

Objectif

Récupérer et vérifier le conteneur SDK Holoscan officiel depuis NGC (nvcr.io/nvidia/clara-holoscan/holoscan), en sélectionnant le bon tag CUDA/architecture pour le GPU hôte et en validant avec les exemples Python et C++ fournis.

Conditions préalables

Hôte Linux avec un GPU NVIDIA et un pilote fonctionnel (nvidia-smi).
Docker installé et l'utilisateur dans le groupe docker (ou sudo).
NVIDIA Container Toolkit installé (docker run --gpus all fonctionne).
~10–20 Go d'espace disque libre pour récupérer l'image.
Accès réseau à nvcr.io et docs.nvidia.com.

Limitations

Les images de conteneur couvrent seulement la matrice de tags ci-dessous — pas d'environnement Conda/pip à l'intérieur.
Les exemples GUI nécessitent le forwarding X11 ; cette skill exécute Holoviz sans affichage pour l'éviter.
Le suffixe du tag doit correspondre au GPU/pilote hôte (cuda13 / cuda12-dgpu / cuda12-igpu) — mauvais suffixe → échecs d'initialisation CUDA.

Instructions

Dépôt du conteneur : nvcr.io/nvidia/clara-holoscan/holoscan.
La page de documentation à https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html est la référence — consultez-la si quelque chose ci-dessous ne correspond pas.
Progressez dans les étapes ci-dessous dans l'ordre : choisissez le tag, vérifiez le passthrough du GPU et récupérez l'image, vérifiez avec les six exemples, puis remettez la commande de lancement.

Étape 1 : Choisir le tag

Tag = <version>-<suffixe>, par ex. v4.1.0-cuda13. Récupérez la version actuelle du SDK à partir de la page de documentation ci-dessus ; choisissez le suffixe à partir de nvidia-smi (le champ « CUDA Version », en haut à droite de l'en-tête du tableau) :

CUDA Version `nvidia-smi`	Suffixe
13.x+	`cuda13`
12.x, Ampere/Ada dGPU	`cuda12-dgpu`
12.x, ARM64 iGPU (nvgpu)	`cuda12-igpu`

La bannière « CUDA Forward Compatibility mode ENABLED » est attendue — ce n'est pas une erreur — quand le conteneur embarque une version mineure CUDA plus récente que celle que le pilote hôte supporte. Le shim de compatibilité ascendante permet au runtime CUDA du conteneur de fonctionner avec l'ancien pilote hôte dans la même version majeure.

Étape 2 : Vérifier le passthrough du GPU, puis récupérer l'image

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

Si Docker est absent → installez depuis https://docs.docker.com/engine/install/. Si le passthrough du GPU échoue → installez NVIDIA Container Toolkit selon https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html, puis réessayez.

Récupérez l'image (~10–20 Go — avertissez l'utilisateur avant de commencer) :

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

Étape 3 : Vérifier avec six exemples

Les tests couvrent : binding Python pur (1a), runtime C++ pur (1b, 2a), Python + Holoviz/Vulkan (2b, 3a), et C++ + Holoviz/Vulkan (3b). Les exemples Holoviz s'exécutent toujours sans affichage (injectez headless: true dans le YAML) — cela fonctionne que l'affichage soit attaché ou non et évite les modes de défaillance GUI sur SSH.

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
"

Étape 4 : Commande de lancement

Lisez https://catalog.ngc.nvidia.com/orgs/nvidia/teams/clara-holoscan/containers/holoscan.
Expliquez les flags docker ci-dessous à l'utilisateur.
Référez l'utilisateur à ce lien pour des flags supplémentaires (par ex., comment monter des appareils vidéo 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

Étapes suivantes :

Explorer : ls /opt/nvidia/holoscan/examples/
Parcourir un exemple : /holoscan-explain-example

Dépannage

docker: Error response from daemon: could not select device driver "nvidia". NVIDIA Container Toolkit est absent ou non configuré. Installez selon le lien dans l'Étape 2 et redémarrez Docker.
Échec d'initialisation CUDA à l'intérieur du conteneur. Le suffixe du tag ne correspond pas à l'hôte. Re-vérifiez la CUDA Version de nvidia-smi et le tableau dans l'Étape 1.
Segmentation fault au lancement d'un exemple. ulimit -s 32768 n'a pas été appliqué à l'intérieur du conteneur. Utilisez le motif bash -c "ulimit -s 32768 && ..." montré dans l'Étape 3.
L'exemple Holoviz se fige / pas de fenêtre sur SSH. Le YAML n'a pas été patché en headless: true. Utilisez l'injection sed montrée dans l'Étape 3.
video_replayer ne trouve pas les données. Définissez HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data — remplace le chemin codé en dur du YAML.

holoscan-install-container