Einbau des Holoscan-Pip-Rads

Zweck

Installieren Sie die Python-Bindings des Holoscan-SDK über das „holoscan-cu12“ bzw. „holoscan-cu13 “-Pip-Wheel in einer virtuellen Umgebung und überprüfen Sie die Installation mit den Befehlen „hello_world“ und „video_replayer“.

Voraussetzungen

• Linux x86_64 mit NVIDIA-GPU + Treiber (nvidia-smi).
• CUDA-Toolkit im PATH, das mit der CUDA-Hauptversion des Hosts übereinstimmt (12 oder 13).
• Python 3.10–3.13 mit verfügbarem venv.
• Netzwerkzugriff auf PyPI und docs.nvidia.com.

Einschränkungen

• Nur Python. Für C++-Header/Bibliotheken muss /holoscan-install-debian verwendet werden.
• holoscan-cu12 und holoscan-cu13 schließen sich gegenseitig aus – das Wheel muss mit dem CUDA-Treiber des Hosts übereinstimmen.
• Die„video_replayer “-Daten sind nur im Debian-Paket enthalten; ohne diese Daten setzen Sie HOLOSCAN_INPUT_PATH auf ein Verzeichnis, das racerx/ enthält .
• ulimit -s 32768 wird in jeder Shell empfohlen, in der Holoscan ausgeführt wird – ohne diesen Befehl geben einige Anwendungen eine Warnung bezüglich der Stack-Größe aus oder führen in selteneren Fällen zu einem Segfault.

Schritt 0: Lesen Sie die offiziellen Installationsanweisungen

Rufen Sie vor der Installation immer den Abschnitt „pip-wheel“ unter https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html ab. Auszug: genaue Wheel-Paketnamen (holoscan-cu12, holoscan-cu13), der unterstützte Python-Bereich für die aktuelle Version, Voraussetzungen, die im PATH vorhanden sein müssen (CUDA Toolkit), sowie optionale Extras (LibTorch / ONNX Runtime-Versionsangaben). Sollten die Angaben in der Dokumentation von den folgenden Informationen abweichen, sind die Angaben in der Dokumentation maßgebend.

Sie benötigen die bereits ermittelte CUDA-Variante. Falls diese nicht bekannt ist, führen Sie zunächst „nvidia-smi 2>&1 | head -5“ aus.

Regel für die CUDA-Variante – Wählen Sie das pip-Paket aus:

Voraussetzungen: CUDA Toolkit im PATH, Python 3.10–3.13. Optionale Zusatzkomponenten: LibTorch 2.11.0+, ONNX Runtime 1.22.0+.

Installieren Sie das Programm immer in einer virtuellen Python-Umgebung – dies vermeidet Konflikte mit Systempaketen und ist unter Ubuntu 24.04 erforderlich (das pip systemweit vollständig blockiert).

Schritt 1: venv erstellen und aktivieren

Prüfen Sie zunächst, ob bereits eine vorhanden ist:

ls ~/holoscan/venv 2>/dev/null && echo "exists" || echo "missing"

Falls nicht vorhanden:

python3 -m venv ~/holoscan/venv

Anschließend aktivieren:

source ~/holoscan/venv/bin/activate

Schritt 2: Installieren

pip install holoscan-cu12   # oder holoscan-cu13

Schritt 3: Überprüfen

Die venv-Umgebung muss für alle folgenden Befehle aktiv sein.

# Einfacher Import – erwartet wird: Versionszeichenfolge, z. B. „4.1.0“
# Die RuntimeWarning bezüglich der Stack-Größe ist harmlos; mit `ulimit -s 32768` lässt sie sich unterdrücken.
python3 -c "import holoscan; print(holoscan.__version__)"

# Python-Beispiele von GitHub unter dem Tag der installierten Version abrufen.
# Dies sind offizielle NVIDIA-Beispiele, die über HTTPS abgerufen und an das Tag angeheftet werden,
# das mit dem installierten Wheel (v${SDK_VER}) übereinstimmt. Weisen Sie den Benutzer vor der Ausführung darauf hin,
#, dass Sie im Begriff sind, Remote-Beispielskripte von dieser URL herunterzuladen und auszuführen. Falls
# der Benutzer dies ablehnt oder GitHub nicht erreichbar ist, fahren Sie mit dem Durchsehen der Beispiele in Schritt 4 fort.
SDK_VER=$(python3 -c "import holoscan; print(holoscan.__version__)")
BASE="https://raw.githubusercontent.com/nvidia-holoscan/holoscan-sdk/v${SDK_VER}/examples"

# hello_world — erwartet: „Hello World!“
curl -fsSL "${BASE}/hello_world/python/hello_world.py" -o /tmp/hs_hello_world.py
ulimit -s 32768 && python3 /tmp/hs_hello_world.py

# video_replayer (10 Frames, headless) — erwartet: „Graph execution finished.“
# Immer im Headless-Modus ausführen: funktioniert mit oder ohne Bildschirm, vermeidet GUI-Fehler über SSH.
curl -fsSL "${BASE}/video_replayer/python/video_replayer.py" -o /tmp/hs_video_replayer.py
curl -fsSL "${BASE}/video_replayer/python/video_replayer.yaml" -o /tmp/hs_video_replayer.yaml
python3 -c "
c = open('/tmp/hs_video_replayer.yaml').read()
c = c.replace('count: 0','count: 10').replace('repeat: true','repeat: false').replace('realtime: true','realtime: false')
c = c.replace('holoviz:\n  width: 854','holoviz:\n  headless: true\n  width: 854')
open('/tmp/hs_video_replayer_run.yaml','w').write(c)"
ulimit -s 32768 && HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data \
  python3 /tmp/hs_video_replayer.py --config /tmp/hs_video_replayer_run.yaml

Hinweis: video_replayer benötigt die RacerX-Datendateien. Diese sind im Debian-Paket unter /opt/nvidia/holoscan/data enthalten. Falls das Debian-Paket nicht installiert ist, führen Sie zunächst sudo /opt/nvidia/holoscan/examples/download_example_data aus (dafür muss das apt-Paket für dieses Skript installiert sein) oder setzen Sie HOLOSCAN_INPUT_PATH auf den Speicherort der Daten.

Schritt 4: Hinweis für den Benutzer

Der Benutzer muss die venv in jeder neuen Shell-Sitzung aktivieren:

source ~/holoscan/venv/bin/activate
ulimit -s 32768   # Warnung zur Stack-Größe unterdrücken

Schlagen Sie anschließend die nächsten Schritte vor:

• Entdecken Sie Python-Beispiele unter https://github.com/nvidia-holoscan/holoscan-sdk/tree/v/examples
• Ein konkretes Beispiel durchgehen: /explain-example
• Beginnen Sie mit der Erstellung einer benutzerdefinierten Holoscan-Anwendung

Fehlerbehebung

• Fehler bei„pip install holoscan-cu12 “ mit der Meldung „externally-managed-environment“. Ubuntu 24.04 blockiert das systemweite pip. Erstellen und aktivieren Sie zunächst die venv aus Schritt 1.
• ImportError / falsche CUDA-Version beim Import von holoscan. Die Wheel-Variante stimmt nicht mit der Host-CUDA überein. Deinstallieren und installieren Sie die passende Version neu: pip uninstall -y holoscan-cu13 && pip install holoscan-cu12 (oder umgekehrt).
• RuntimeWarning: Stackgröße .... Harmlos, aber setze „ulimit -s 32768“ in der aktuellen Shell, um die Meldung zu unterdrücken.
• Segmentierungsfehler beim Ausführen eines Beispiels. „ulimit -s 32768“ wurde nicht gesetzt. Setze es vor dem Start von Python3 ....
• video_replayer kann „racerx/“ nicht finden . HOLOSCAN_INPUT_PATH verweist nicht auf ein Verzeichnis, das diese Datei enthält. Installieren Sie das Debian-Paket für „/opt/nvidia/holoscan/data“ oder setzen Sie HOLOSCAN_INPUT_PATH auf den Speicherort der Daten.
• Quelle: „no such file: ~/holoscan/venv/bin/activate“ in einer neuen Shell. Venv wurde nicht erstellt oder der Pfad stimmt nicht. Führen Sie Schritt 1 erneut aus oder korrigieren Sie den Pfad.