Installation du conteneur Holoscan NGC

Objectif

Télécharger et vérifier le conteneur officiel du SDK Holoscan depuis NGC (nvcr.io/nvidia/clara-holoscan/holoscan), en sélectionnant la balise CUDA/arch adaptée au GPU hôte et en validant le tout à l'aide des exemples Python et C++ fournis.

Prérequis

• Hôte Linux équipé d’un GPU NVIDIA et d’un pilote fonctionnel (nvidia-smi).
• Docker doit être installé et l'utilisateur doit faire partie du groupe docker (ou disposer des droits sudo).
• NVIDIA Container Toolkit doit être installé (la commande «docker run --gpus all » doit fonctionner).
• Environ 10 à 20 Go d'espace disque libre pour le téléchargement de l'image.
• Accès réseau à nvcr.io et docs.nvidia.com.

Restrictions

• Les images de conteneurs ne couvrent que la matrice de balises ci-dessous — aucun environnement Conda/pip n’y est inclus.
• Les exemples d’interface graphique nécessitent un transfert X11 ; cette compétence exécute Holoviz en mode sans affichage pour éviter cela.
• Le suffixe de balise doit correspondre au GPU/pilote de l’hôte (cuda13 / cuda12-dgpu / cuda12-igpu) — un suffixe incorrect entraîne des échecs d’initialisation de CUDA.

Instructions

• Dépôt de conteneurs : nvcr.io/nvidia/clara-holoscan/holoscan.
• La page de documentation disponible à l’adresse https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html fait autorité — consultez-la en cas de divergence avec les informations ci-dessous.
• Suivez les étapes ci-dessous dans l’ordre : choisissez le tag, vérifiez le passthrough GPU et effectuez un pull, vérifiez à l’aide des six exemples, puis transmettez la commande de lancement.

Étape 1 : Choisissez la balise

Balise = -, par exemple v4.1.0-cuda13. Récupérez la version actuelle du SDK sur 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) :

Le message « Mode de compatibilité ascendante CUDA ACTIVÉ » s'affiche normalement (il ne s'agit pas d'une erreur) lorsque le conteneur utilise une version mineure de CUDA plus récente que celle prise en charge par le pilote hôte. Le shim de compatibilité ascendante permet au runtime CUDA du conteneur de fonctionner avec l'ancien pilote hôte au sein de la même version majeure.

Étape 2 : Vérifiez le passthrough du GPU, puis effectuez un pull

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

Si Docker n’est pas installé → installez-le à partir de https://docs.docker.com/engine/install/. Si le passthrough du GPU échoue → installez le NVIDIA Container Toolkit en suivant les instructions sur https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html, puis réessayez.

Téléchargement (~10–20 Go — avertir l'utilisateur avant de commencer) :

docker pull nvcr.io/nvidia/clara-holoscan/holoscan:

Étape 3 : Vérification à l’aide de six exemples

Les tests couvrent : la liaison Python seule (1a), le runtime C++ seul (1b, 2a), Python + Holoviz/Vulkan (2b, 3a) et C++ + Holoviz/Vulkan (3b). Les exemples Holoviz s’exécutent toujours en mode « headless » (ajoutez « headless: true » dans le fichier YAML) — cela fonctionne qu’un écran soit connecté ou non et évite les défaillances de l’interface graphique via SSH.

IMG=nvcr.io/nvidia/clara-holoscan/holoscan :
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) — attend « Hello World ! »
"${RUN[@]}" "$IMG" bash -c \
  "ulimit -s 32768 && python3 /opt/nvidia/holoscan/examples/hello_world/python/hello_world.py"

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

# 2a. tensor_interop (C++) — résultat attendu : les tenseurs doublent à chaque passage, « Graph execution finished. »
"${RUN[@]}" "$IMG" bash -c \
  "ulimit -s 32768 && /opt/nvidia/holoscan/examples/tensor_interop/cpp/tensor_interop"

# 2b. tensor_interop (Python, 10 images) — Holoviz, en mode headless. Le fichier YAML ne comporte pas
#     de champ « headless » par défaut ; il faut donc en ajouter un sous `holoviz:`. On s'attend à
#     « message reçu (nombre : 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 images) — Holoviz, en mode headless. Ajoutez `headless: true`
#     sous `holoviz:` (au-dessus de `width: 854`). La même commande sed fonctionne pour le fichier YAML C++ de l'exemple 3b —
#     les deux fichiers partagent la même structure de section `holoviz:`.
"${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 images) — même injection sans interface graphique que 3a. Le fichier YAML de C++
#     code en dur `directory: "../data/racerx"`, mais HOLOSCAN_INPUT_PATH
#     le remplace ; nous n’avons donc pas besoin de modifier ce champ.
"${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

• Consultez la page https://catalog.ngc.nvidia.com/orgs/nvidia/teams/clara-holoscan/containers/holoscan.
• Expliquez à l’utilisateur les options Docker ci-dessous.
• Renvoyez l’utilisateur vers ce lien pour connaître d’autres options (par exemple, comment monter des périphériques 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:
# Exemples : /opt/nvidia/holoscan/examples/
# Monter des fichiers : -v /host/path:/container/path
# Exemples d'interface graphique : ajoutez -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY

Suivant :

• Explorer : ls /opt/nvidia/holoscan/examples/
• Suivez le guide pas à pas : /holoscan-explain-example

Dépannage

• docker : Réponse d'erreur du démon : impossible de sélectionner le pilote de périphérique « nvidia ». NVIDIA Container Toolkit est manquant ou n'est pas configuré. Installez-le en suivant le lien de l'étape 2, puis redémarrez Docker.
• Échec de l'initialisation de CUDA à l'intérieur du conteneur. Le suffixe de balise ne correspond pas à celui de l'hôte. Vérifiez à nouveau la version CUDA via nvidia-smi et le tableau de l'étape 1.
• Erreur de segmentation lors du lancement d’un exemple. La commande ` ulimit -s 32768 ` n’a pas été appliquée à l’intérieur du conteneur. Utilisez le modèle `bash -c "ulimit -s 32768 && ..."` indiqué à l’étape 3.
• L'exemple Holoviz se bloque / aucune fenêtre n'apparaît via SSH. Le fichier YAML n'a pas été modifié pour inclure « headless: true ». Utilisez l'injection sed indiquée à l'étape 3.
• video_replayer ne parvient pas à trouver les données. Définissez HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data — cela remplace le chemin d'accès codé en dur dans le fichier YAML.