Instalação do contêiner Holoscan NGC

Objetivo

Baixe e verifique o contêiner oficial do SDK do Holoscan do NGC (nvcr.io/nvidia/clara-holoscan/holoscan), selecionando a tag CUDA/arquitetura correta para a GPU do host e validando com os exemplos em Python e C++ incluídos no pacote.

Pré-requisitos

• Host Linux com uma GPU NVIDIA e um driver em funcionamento (nvidia-smi).
• Docker instalado e o usuário no grupo docker (ou com permissão para usar o `sudo`).
• NVIDIA Container Toolkit instalado (o comando `docker run --gpus all ` funciona).
• Aproximadamente 10–20 GB de espaço livre em disco para o download da imagem.
• Acesso à rede para nvcr.io e docs.nvidia.com.

Limitações

• As imagens de contêiner abrangem apenas a matriz de tags abaixo — sem ambiente Conda/pip no interior.
• Os exemplos de GUI exigem encaminhamento de X11; esta habilidade executa o Holoviz sem interface gráfica para evitar isso.
• O sufixo da tag deve corresponder à GPU/driver do host (cuda13 / cuda12-dgpu / cuda12-igpu) — sufixo incorreto → falhas na inicialização do CUDA.

Instruções

• Repositório de contêineres: nvcr.io/nvidia/clara-holoscan/holoscan.
• A página de documentação em https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html é a oficial — consulte-a caso haja alguma discrepância com as informações abaixo.
• Siga as etapas abaixo na ordem: escolha a tag, verifique o passthrough da GPU e faça o pull, verifique com os seis exemplos e, por fim, execute o comando de inicialização.

Etapa 1: Escolha a tag

Tag = -, por exemplo, v4.1.0-cuda13. Obtenha a versão atual do SDK na página de documentação acima; escolha o sufixo no nvidia-smi (o campo “CUDA Version”, no canto superior direito do cabeçalho da tabela):

A mensagem “Modo de compatibilidade com versões futuras do CUDA ATIVADO” é esperada — não se trata de um erro — quando o contêiner utiliza uma versão secundária do CUDA mais recente do que a suportada pelo driver do host. O shim de compatibilidade com versões futuras permite que o runtime do CUDA do contêiner funcione com o driver do host mais antigo dentro da mesma versão principal.

Passo 2: Verifique o passthrough da GPU e, em seguida, faça o pull

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

Se o Docker não estiver instalado → instale a partir de https://docs.docker.com/engine/install/. Se o passthrough da GPU falhar → instale o NVIDIA Container Toolkit conforme https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html e tente novamente.

Baixar (~10–20 GB — avise o usuário antes de iniciar):

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

Etapa 3: Verifique com seis exemplos

Os testes abrangem: ligação Python básica (1a), tempo de execução C++ básico (1b, 2a), Python + Holoviz/Vulkan (2b, 3a) e C++ + Holoviz/Vulkan (3b). Os exemplos do Holoviz sempre são executados no modo headless (insira headless: true no YAML) — isso funciona independentemente de haver ou não um monitor conectado e evita falhas na interface gráfica via 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-se “Hello World!”
"${RUN[@]}" "$IMG" bash -c \
  "ulimit -s 32768 && python3 /opt/nvidia/holoscan/examples/hello_world/python/hello_world.py"

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

# 2a. tensor_interop (C++) — espera que os tensores dobrem a cada passagem, “Execução do gráfico concluída.”
"${RUN[@]}" "$IMG" bash -c \
  "ulimit -s 32768 && /opt/nvidia/holoscan/examples/tensor_interop/cpp/tensor_interop"

# 2b. tensor_interop (Python, 10 quadros) — Holoviz, sem interface gráfica. O YAML não possui
#     o campo “headless” por padrão, portanto, insira-o sob `holoviz:`. Espere
#     “mensagem recebida (contagem: 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 quadros) — Holoviz, sem interface gráfica. Insira `headless: true`
#     abaixo de `holoviz:` (acima de `width: 854`). O mesmo comando `sed` funciona para o YAML em C++ na seção 3b —
#     ambos os arquivos compartilham a mesma estrutura da seção `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 quadros) — mesma injeção sem interface gráfica que em 3a. O arquivo YAML do C++
#     codifica fixamente `directory: "../data/racerx"`, mas HOLOSCAN_INPUT_PATH
#     o substitui, portanto não precisamos corrigir esse 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
"

Etapa 4: Comando de execução

• Leia https://catalog.ngc.nvidia.com/orgs/nvidia/teams/clara-holoscan/containers/holoscan.
• Explique ao usuário os parâmetros do Docker abaixo.
• Indique ao usuário esse link para opções adicionais (por exemplo, como 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:
# Exemplos: /opt/nvidia/holoscan/examples/
# Montar arquivos: -v /host/path:/container/path
# Exemplos de GUI: adicione -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY

Próximo:

• Explorar: ls /opt/nvidia/holoscan/examples/
• Siga passo a passo: /holoscan-explain-example

Solução de problemas

• docker: Resposta de erro do daemon: não foi possível selecionar o driver de dispositivo “nvidia”. O NVIDIA Container Toolkit está ausente ou não está configurado. Instale conforme o link na Etapa 2 e reinicie o Docker.
• Falha na inicialização do CUDA dentro do contêiner. O sufixo da tag não corresponde ao do host. Verifique novamente a versão do CUDA no `nvidia-smi` e a tabela na Etapa 1.
• Falha de segmentação ao iniciar um exemplo. O comando ` ulimit -s 32768 ` não foi aplicado dentro do contêiner. Use o padrão `bash -c "ulimit -s 32768 && ..."` mostrado na Etapa 3.
• O exemplo do Holoviz trava / não exibe janela via SSH. O YAML não foi corrigido para headless: true. Use a injeção com sed mostrada na Etapa 3.
• O `video_replayer` não consegue encontrar os dados. Defina ` HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data ` — isso substitui o caminho codificado no YAML.