Установка контейнера Holoscan NGC

Цель

Загрузите и проверьте официальный контейнер Holoscan SDK из NGC (nvcr.io/nvidia/clara-holoscan/holoscan), выбрав правильный тег CUDA/arch для графического процессора хоста и проверив его работу с помощью прилагаемых примеров на Python и C++.

Необходимые условия

• Хост-компьютер под управлением Linux с графическим процессором NVIDIA и работающим драйвером (nvidia-smi).
• Установлен Docker, и пользователь входит в группу docker (или имеет права sudo).
• Установлен NVIDIA Container Toolkit (командаdocker run --gpus all должна работать).
• Около 10–20 ГБ свободного места на диске для загрузки образа.
• Доступ к сетям nvcr.io и docs.nvidia.com.

Ограничения

• Образы контейнеров охватывают только приведенную ниже матрицу тегов — внутри нет среды Conda/pip.
• Примеры с графическим интерфейсом требуют перенаправления X11; в данном скрипте Holoviz запускается в режиме без графического интерфейса, чтобы этого избежать.
• Суффикс тега должен соответствовать GPU/драйверу хоста (cuda13 / cuda12-dgpu / cuda12-igpu) — неверный суффикс → сбои при инициализации CUDA.

Инструкции

• Репозиторий контейнеров: nvcr.io/nvidia/clara-holoscan/holoscan.
• Страница документации по адресу https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html является канонической — обратитесь к ней, если что-либо из приведенного ниже не соответствует.
• Выполните приведенные ниже шаги по порядку: выберите тег, проверьте пропуск графического процессора и выполните pull, проверьте с помощью шести примеров, а затем передайте команду запуска.

Шаг 1: Выберите тег

Тег = -, например v4.1.0-cuda13. Узнайте текущую версию SDK на странице документации, указанной выше; выберите суффикс из nvidia-smi (поле «CUDA Version», в правом верхнем углу заголовка таблицы):

Появление баннера «Режим перспективной совместимости CUDA ВКЛЮЧЕН» является ожидаемым явлением — это не ошибка — когда контейнер использует более новую второстепенную версию CUDA, чем поддерживает драйвер хоста. Шим перспективной совместимости позволяет среде выполнения CUDA контейнера работать с более старым драйвером хоста в пределах одной и той же основной версии.

Шаг 2: Проверьте пропуск графического процессора, затем выполните pull

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

Если Docker отсутствует → установите его с сайта https://docs.docker.com/engine/install/. Если пропуск GPU не работает → установите NVIDIA Container Toolkit по инструкции https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html, затем повторите попытку.

Загрузите (~10–20 ГБ — предупредите пользователя перед началом):

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

Шаг 3: Проверка с помощью шести примеров

Тесты охватывают: простой Python-баинд (1a), простое C++-среда выполнения (1b, 2a), Python + Holoviz/Vulkan (2b, 3a) и C++ + Holoviz/Vulkan (3b). Примеры Holoviz всегда запускаются в режиме headless (добавьте headless: true в файл YAML) — это работает независимо от того, подключен ли дисплей, и позволяет избежать сбоев графического интерфейса при работе через 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) — ожидаемый результат «Hello World!»
"${RUN[@]}" "$IMG" bash -c \
  "ulimit -s 32768 && python3 /opt/nvidia/holoscan/examples/hello_world/python/hello_world.py"

# 1b. hello_world (C++) — ожидается «Hello World!»
"${RUN[@]}" "$IMG" bash -c \
  "ulimit -s 32768 && /opt/nvidia/holoscan/examples/hello_world/cpp/hello_world"

# 2a. tensor_interop (C++) — ожидается удвоение тензоров при каждом проходе, «Graph execution finished.»
"${RUN[@]}" "$IMG" bash -c \
  "ulimit -s 32768 && /opt/nvidia/holoscan/examples/tensor_interop/cpp/tensor_interop"

# 2b. tensor_interop (Python, 10 кадров) — Holoviz, без интерфейса. В YAML по умолчанию отсутствует
#     поле headless, поэтому добавьте его под `holoviz:`. Ожидается
#     «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 кадров) — Holoviz, в режиме headless. Вставьте `headless: true`
#     под `holoviz:` (над `width: 854`). Та же команда sed работает и для YAML-файла на C++ в пункте 3b —
#     оба файла имеют одинаковую структуру раздела `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 кадров) — та же инъекция без интерфейса, что и в 3a. В файле YAML на C++
#     жестко задано `directory: "../data/racerx"`, но HOLOSCAN_INPUT_PATH
#     переопределяет его, поэтому нам не нужно исправлять это поле.
"${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
"

Шаг 4: Команда запуска

• Ознакомьтесь с документом «https://catalog.ngc.nvidia.com/orgs/nvidia/teams/clara-holoscan/containers/holoscan».
• Объясните пользователю значение приведенных ниже флагов Docker.
• Направьте пользователя по этой ссылке для ознакомления с дополнительными флагами (например, как смонтировать видеоустройства 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:
# Примеры: /opt/nvidia/holoscan/examples/
# Монтирование файлов: -v /host/path:/container/path
# Примеры с графическим интерфейсом: add -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY

Далее:

• Изучение: ls /opt/nvidia/holoscan/examples/
• Пройдите один из примеров: /holoscan-explain-example

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

• docker: Ошибка от демона: не удалось выбрать драйвер устройства «nvidia». Отсутствует или не настроен NVIDIA Container Toolkit. Установите по ссылке в шаге 2 и перезапустите Docker.
• Сбой инициализации CUDA внутри контейнера. Суффикс тега не совпадает с хостом. Проверьте версию CUDA с помощью nvidia-smi и таблицу в шаге 1.
• Ошибка сегментации при запуске примера. Указание `ulimit -s 32768 ` не было применено внутри контейнера. Используйте шаблон ` bash -c "ulimit -s 32768 && ..."`, показанный в шаге 3.
• Пример Holoviz зависает / окно не отображается через SSH. В YAML не был внесен патч с параметром headless: true. Используйте вставку с помощью sed, показанную в шаге 3.
• video_replayer не может найти данные. Установите HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data — это переопределит жестко заданный путь в файле YAML.