Установка колеса Holoscan pip

Цель

Установите Python-библиотеки Holoscan SDK с помощью пакета pip wheel holoscan-cu12 / holoscan-cu13 в виртуальную среду и проверьте их работу с помощью программ hello_world и video_replayer.

Требования

• Linux x86_64 с графическим процессором NVIDIA + драйвер (nvidia-smi).
• Набор инструментов CUDA в PATH, соответствующий основной версии CUDA хоста (12 или 13).
• Python 3.10–3.13 с доступным venv.
• Доступ к PyPI и docs.nvidia.com через сеть.

Ограничения

• Только Python. Для заголовок/библиотек C++ используйте в паре с /holoscan-install-debian.
• holoscan-cu12 и holoscan-cu13 взаимоисключают друг друга — файл wheel должен соответствовать версии драйвера CUDA хоста.
• Данныеvideo_replayer поставляются только с пакетом Debian; если их нет, установите HOLOSCAN_INPUT_PATH в каталог, содержащий racerx/.
• Рекомендуется установитьulimit -s 32768 во всех оболочках, в которых запускается Holoscan — без этого некоторые приложения выдают предупреждение о размере стека или, в более редких случаях, терпят сбой сегментации.

Шаг 0: Ознакомьтесь с официальной инструкцией по установке

Перед установкой всегда загружайте раздел pip-wheel с сайта https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html. Извлеките: точные названия пакетов wheel (holoscan-cu12, holoscan-cu13), поддерживаемый диапазон версий Python для текущего релиза, предварительные условия, которые должны находиться в PATH (CUDA Toolkit), и любые дополнительные компоненты (версии LibTorch / ONNX Runtime). Если в документации указано иное, чем в приведённой ниже информации, то приоритет имеет документация.

Вам необходимо заранее определить вариант CUDA. Если он неизвестен, сначала выполните команду nvidia-smi 2>&1 | head -5.

Правило выбора варианта CUDA — выберите пакет pip:

Необходимые условия: CUDA Toolkit в PATH, Python 3.10–3.13. Дополнительные компоненты (необязательно): LibTorch 2.11.0+, ONNX Runtime 1.22.0+.

Всегда устанавливайте в виртуальную среду Python — это позволяет избежать конфликтов с системными пакетами и является обязательным требованием в Ubuntu 24.04 (где pip полностью заблокирован на системном уровне).

Шаг 1: Создание и активация venv

Сначала проверьте, существует ли она:

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

Если отсутствует:

python3 -m venv ~/holoscan/venv

Затем активируйте:

source ~/holoscan/venv/bin/activate

Шаг 2: Установка

pip install holoscan-cu12   # или holoscan-cu13

Шаг 3: Проверка

Для выполнения всех приведенных ниже команд среда venv должна быть активной.

# Базовый импорт — ожидаемый результат: строка версии, например «4.1.0»
# Предупреждение RuntimeWarning о размере стека не представляет опасности; его можно подавить с помощью ulimit -s 32768.
python3 -c "import holoscan; print(holoscan.__version__)"

# Загрузите примеры на Python с GitHub по тегу установленной версии.
# Это официальные примеры NVIDIA, загружаемые по HTTPS и привязанные к тегу,
# соответствующему установленному модулю wheel (v${SDK_VER}). Перед их запуском сообщите пользователю,
# о том, что вы собираетесь загрузить и запустить удалённые скрипты-примеры с этого URL. Если
# пользователь откажется или GitHub недоступен, перейдите к просмотру примеров в шаге 4.
SDK_VER=$(python3 -c "import holoscan; print(holoscan.__version__)")
BASE="https://raw.githubusercontent.com/nvidia-holoscan/holoscan-sdk/v${SDK_VER}/examples"

# hello_world — ожидаемый результат: "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 кадров, в режиме без интерфейса) — ожидаемый результат: "Graph execution finished."
# Всегда запускать в режиме без интерфейса: работает как с дисплеем, так и без него, позволяет избежать сбоев графического интерфейса при работе через 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

Примечание: для работы video_replayer требуются файлы данных racerx. Они поставляются в составе пакета Debian в каталоге /opt/nvidia/holoscan/data. Если пакет Debian не установлен, сначала запустите команду sudo /opt/nvidia/holoscan/examples/download_example_data (для работы этого скрипта требуется установка пакета apt) или задайте переменную HOLOSCAN_INPUT_PATH, указав путь к месту хранения данных.

Шаг 4: Напомните пользователю

Пользователь должен активировать venv при каждом новом запуске терминала:

source ~/holoscan/venv/bin/activate
ulimit -s 32768   # подавление предупреждения о размере стека

Затем предложите следующие шаги:

• Ознакомьтесь с примерами на Python по адресу https://github.com/nvidia-holoscan/holoscan-sdk/tree/v/examples
• Пройдите по конкретному примеру: /explain-example
• Начните создавать собственное приложение Holoscan

Устранение неполадок

• Ошибкипри установке pip holoscan-cu12 с сообщением «externally-managed-environment». Ubuntu 24.04 блокирует системный pip. Сначала создайте и активируйте venv из шага 1.
• ImportError / неверная версия CUDA при импорте holoscan. Версия в пакете wheel не совпадает с версией CUDA на хосте. Удалите и переустановите подходящую версию: pip uninstall -y holoscan-cu13 && pip install holoscan-cu12 (или наоборот).
• RuntimeWarning: размер стека .... Это не опасно, но чтобы скрыть это предупреждение, установите ulimit -s 32768 в текущем терминале.
• Ошибка сегментации при запуске примера. Не был установлен параметр ulimit -s 32768. Установите его перед запуском python3 ....
• video_replayer не может найти папку racerx/. Переменная HOLOSCAN_INPUT_PATH не указывает на каталог, содержащий эту папку. Установите пакет Debian для /opt/nvidia/holoscan/data или задайте HOLOSCAN_INPUT_PATH на путь к месту хранения данных.
• source: no such file: ~/holoscan/venv/bin/activate в новой оболочке. Venv не был создан или путь указан неверно. Повторите шаг 1 или исправьте путь.