Installation des Holoscan NGC-Containers

Zweck

Laden Sie den offiziellen Holoscan-SDK-Container aus dem NGC (nvcr.io/nvidia/clara-holoscan/holoscan) herunter und überprüfen Sie ihn, indem Sie das richtige CUDA-/Arch-Tag für die Host-GPU auswählen und die Funktion anhand der mitgelieferten Python- und C++-Beispiele validieren.

Voraussetzungen

• Linux-Host mit einer NVIDIA-GPU und einem funktionierenden Treiber (nvidia-smi).
• Docker muss installiert sein und der Benutzer muss zur Gruppe „docker“ gehören (oder über „sudo“-Rechte verfügen).
• Das NVIDIA Container Toolkit muss installiert sein (der Befehl„docker run --gpus all“ muss funktionieren).
• ~10–20 GB freier Speicherplatz für das Herunterladen des Images.
• Netzwerkzugang zu nvcr.io und docs.nvidia.com.

Einschränkungen

• Die Container-Images decken nur die unten stehende Tag-Matrix ab – keine Conda-/pip-Umgebung enthalten.
• GUI-Beispiele erfordern X11-Weiterleitung; dieser Skill führt Holoviz im Headless-Modus aus, um dies zu vermeiden.
• Das Tag-Suffix muss mit der GPU bzw. dem Treiber des Hosts übereinstimmen (cuda13 / cuda12-dgpu / cuda12-igpu) – falsches Suffix → Fehler bei der CUDA-Initialisierung.

Anleitung

• Container-Repo: nvcr.io/nvidia/clara-holoscan/holoscan.
• Die Dokumentationsseite unter https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html ist maßgeblich – greifen Sie darauf zurück, falls die folgenden Angaben davon abweichen.
• Führen Sie die folgenden Schritte der Reihe nach durch: Wählen Sie das Tag aus, überprüfen Sie den GPU-Passthrough und führen Sie einen Pull durch, überprüfen Sie die Funktion anhand der sechs Beispiele und geben Sie anschließend den Startbefehl weiter.

Schritt 1: Wählen Sie das Tag aus

Tag = -, z. B. v4.1.0-cuda13. Rufen Sie die aktuelle SDK-Version von der oben genannten Dokumentationsseite ab; wählen Sie das Suffix aus nvidia-smi (das Feld „CUDA-Version“ oben rechts in der Tabellenkopfzeile):

Die Meldung „CUDA Forward Compatibility mode ENABLED“ ist zu erwarten – und stellt keinen Fehler dar –, wenn der Container eine neuere CUDA-Nebenversion liefert, als der Host-Treiber unterstützt. Der Forward-Compatibility-Shim ermöglicht es der CUDA-Laufzeitumgebung des Containers, mit dem älteren Host-Treiber innerhalb derselben Hauptversion zusammenzuarbeiten.

Schritt 2: GPU-Passthrough überprüfen, dann abrufen

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

Falls Docker fehlt → installieren Sie es unter https://docs.docker.com/engine/install/. Falls der GPU-Passthrough fehlschlägt → das NVIDIA Container Toolkit gemäß https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html installieren, dann erneut versuchen.

Herunterladen (~10–20 GB – den Benutzer vor dem Start warnen):

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

Schritt 3: Überprüfung anhand von sechs Beispielen

Die Tests umfassen: reines Python-Binding (1a), reine C++-Laufzeitumgebung (1b, 2a), Python + Holoviz/Vulkan (2b, 3a) sowie C++ + Holoviz/Vulkan (3b). Holoviz-Beispiele werden immer im Headless-Modus ausgeführt (füge „headless: true“ in die YAML-Datei ein) – dies funktioniert unabhängig davon, ob ein Bildschirm angeschlossen ist oder nicht, und vermeidet GUI-Fehler bei der Verbindung über 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) — erwartet „Hello World!“
"${RUN[@]}" "$IMG" bash -c \
  "ulimit -s 32768 && python3 /opt/nvidia/holoscan/examples/hello_world/python/hello_world.py"

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

# 2a. tensor_interop (C++) — erwartet, dass sich die Tensoren bei jedem Durchlauf verdoppeln, „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. Die YAML-Datei enthält standardmäßig kein
#     „headless“-Feld, füge daher eines unter `holoviz:` ein. Es wird erwartet, dass
#     „message received (count: 10)“ ausgegeben wird.
"${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. Füge `headless: true`
#     unter `holoviz:` (oberhalb von `width: 854`) ein. Derselbe sed-Befehl funktioniert auch für die C++-YAML-Datei in 3b —
#     beide Dateien haben denselben Aufbau des `holoviz:`-Abschnitts.
"${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) – gleiche headless-Einbindung wie bei 3a. Die C++-
#     YAML-Datei enthält die Festkodierung `directory: "../data/racerx"`, aber HOLOSCAN_INPUT_PATH
#     überschreibt es, sodass wir dieses Feld nicht ändern müssen.
"${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
"

Schritt 4: Befehl ausführen

• Lesen Sie „https://catalog.ngc.nvidia.com/orgs/nvidia/teams/clara-holoscan/containers/holoscan“.
• Erläutern Sie dem Benutzer die unten aufgeführten Docker-Flags.
• Verweisen Sie den Benutzer auf diesen Link, um weitere Flags zu erfahren (z. B. wie man V4L2-Videogeräte einbindet).

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:
# Beispiele: /opt/nvidia/holoscan/examples/
# Dateien einbinden: -v /host/Pfad:/container/Pfad
# GUI-Beispiele: add -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY

Weiter:

• Durchsuchen: ls /opt/nvidia/holoscan/examples/
• Ein Beispiel durchgehen: /holoscan-explain-example

Fehlerbehebung

• docker: Fehlermeldung vom Daemon: Gerätetreiber „nvidia“ konnte nicht ausgewählt werden. Das NVIDIA Container Toolkit fehlt oder ist nicht konfiguriert. Führen Sie die Installation gemäß dem Link in Schritt 2 durch und starten Sie Docker neu.
• CUDA-Initialisierungsfehler im Container. Das Tag-Suffix stimmt nicht mit dem Host überein. Überprüfen Sie erneut die CUDA-Version mit `nvidia-smi` und die Tabelle in Schritt 1.
• Segmentierungsfehler beim Starten eines Beispiels. „ulimit -s 32768“ wurde im Container nicht angewendet. Verwenden Sie das in Schritt 3 gezeigte Muster „bash -c ‚ulimit -s 32768 && …‘ “.
• Das Holoviz-Beispiel hängt sich auf / kein Fenster über SSH. Die YAML-Datei wurde nicht auf ` headless: true` angepasst. Verwenden Sie die in Schritt 3 gezeigte `sed` -Eingabe.
• „video_replayer“ kann keine Daten finden. Setzen Sie ` HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data ` – dies überschreibt den fest codierten Pfad in der YAML-Datei.