Instalación del contenedor Holoscan NGC

Objetivo

Descargar y verificar el contenedor oficial del SDK de Holoscan desde NGC (nvcr.io/nvidia/clara-holoscan/holoscan), seleccionando la etiqueta CUDA/arch adecuada para la GPU del host y comprobando su funcionamiento con los ejemplos de Python y C++ incluidos.

Requisitos previos

• Ordenador host con Linux, una GPU NVIDIA y un controlador operativo (nvidia-smi).
• Docker instalado y el usuario en el grupo docker (o con permisos sudo).
• NVIDIA Container Toolkit instalado (el comando«docker run --gpus all» funciona).
• Entre 10 y 20 GB de espacio libre en disco para descargar la imagen.
• Acceso a la red para nvcr.io y docs.nvidia.com.

Limitaciones

• Las imágenes de contenedor solo cubren la matriz de etiquetas que se muestra a continuación; no incluyen un entorno Conda/pip en su interior.
• Los ejemplos de la interfaz gráfica de usuario (GUI) requieren el reenvío de X11; esta función ejecuta Holoviz en modo sin interfaz gráfica para evitarlo.
• El sufijo de la etiqueta debe coincidir con la GPU o el controlador del host (cuda13 / cuda12-dgpu / cuda12-igpu); un sufijo incorrecto provocará errores en la inicialización de CUDA.

Instrucciones

• Repositorio de contenedores: nvcr.io/nvidia/clara-holoscan/holoscan.
• La página de documentación en https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html es la de referencia; consúltala si algo de lo que aparece a continuación no coincide.
• Sigue los pasos que se indican a continuación en el orden indicado: elige la etiqueta, comprueba el paso de la GPU y realiza un «pull», comprueba con los seis ejemplos y, a continuación, ejecuta el comando de inicio.

Paso 1: Elige la etiqueta

Etiqueta = -, p. ej., v4.1.0-cuda13. Consulta la versión actual del SDK en la página de documentación anterior; elige el sufijo en nvidia-smi (el campo «CUDA Version», en la esquina superior derecha del encabezado de la tabla):

Es normal que aparezca el mensaje «Modo de compatibilidad con versiones posteriores de CUDA ACTIVADO» —no es un error— cuando el contenedor incluye una versión menor de CUDA más reciente que la que admite el controlador del host. El shim de compatibilidad con versiones posteriores permite que el tiempo de ejecución de CUDA del contenedor funcione con el controlador del host más antiguo dentro de la misma versión principal.

Paso 2: Comprueba el paso de la GPU y, a continuación, ejecuta

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

Si no tienes Docker → instálalo desde https://docs.docker.com/engine/install/. Si falla el paso de la GPU → instala el NVIDIA Container Toolkit según https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html y, a continuación, vuelve a intentarlo.

Descargar (~10–20 GB — avisar al usuario antes de empezar):

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

Paso 3: Verificar con seis ejemplos

Las pruebas abarcan: enlace básico de Python (1a), tiempo de ejecución básico de C++ (1b, 2a), Python + Holoviz/Vulkan (2b, 3a) y C++ + Holoviz/Vulkan (3b). Los ejemplos de Holoviz siempre se ejecutan en modo sin pantalla (añade «headless: true» al archivo YAML); esto funciona tanto si hay una pantalla conectada como si no, y evita los fallos de la interfaz gráfica de usuario a través de 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) — espera «Hello World!»
"${RUN[@]}" "$IMG" bash -c \
  "ulimit -s 32768 && python3 /opt/nvidia/holoscan/examples/hello_world/python/hello_world.py"

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

# 2a. tensor_interop (C++) — se espera que los tensores se dupliquen en cada pasada y que aparezca «Graph execution finished.»
"${RUN[@]}" "$IMG" bash -c \
  "ulimit -s 32768 && /opt/nvidia/holoscan/examples/tensor_interop/cpp/tensor_interop"

# 2b. tensor_interop (Python, 10 fotogramas) — Holoviz, sin interfaz gráfica. El archivo YAML no tiene
#     el campo «headless» por defecto, así que añádelo bajo `holoviz:`. Se espera
#     «mensaje recibido (recuento: 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 fotogramas) — Holoviz, sin interfaz gráfica. Añade `headless: true`
#     debajo de `holoviz:` (por encima de `width: 854`). El mismo comando sed funciona para el YAML de C++ en 3b —
#     ambos archivos comparten la misma estructura de la sección `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 fotogramas): misma inyección sin interfaz gráfica que en 3a. El archivo YAML de C++
#     tiene codificado de forma fija `directory: "../data/racerx"`, pero HOLOSCAN_INPUT_PATH
#     lo anula, por lo que no es necesario modificar ese campo.
"${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
"

Paso 4: Comando de ejecución

• Lee https://catalog.ngc.nvidia.com/orgs/nvidia/teams/clara-holoscan/containers/holoscan.
• Explica al usuario los parámetros de Docker que se indican a continuación.
• Remita al usuario a ese enlace para conocer otras opciones (por ejemplo, cómo montar dispositivos de vídeo 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:
# Ejemplos: /opt/nvidia/holoscan/examples/
# Montar archivos: -v /host/path:/container/path
# Ejemplos de interfaz gráfica: añade -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY

Siguiente:

• Explorar: ls /opt/nvidia/holoscan/examples/
• Sigue paso a paso uno de ellos: /holoscan-explain-example

Solución de problemas

• docker: Respuesta de error del daemon: no se ha podido seleccionar el controlador de dispositivo «nvidia». Falta NVIDIA Container Toolkit o no está configurado. Instálalo siguiendo el enlace del paso 2 y reinicia Docker.
• Error de inicialización de CUDA dentro del contenedor. El sufijo de la etiqueta no coincide con el del host. Vuelve a comprobar la versión de CUDA con nvidia-smi y la tabla del paso 1.
• Fallo de segmentación al ejecutar un ejemplo. No se ha aplicado «ulimit -s 32768» dentro del contenedor. Utiliza el patrón «bash -c "ulimit -s 32768 && ..."» que se muestra en el paso 3.
• El ejemplo de Holoviz se cuelga o no aparece ninguna ventana a través de SSH. El archivo YAML no se ha modificado para establecer «headless: true». Utiliza la inyección con sed que se muestra en el paso 3.
• video_replayer no encuentra los datos. Establece HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data: esto anula la ruta codificada en el YAML.