Guia de início rápido do Docker para Ultralytics#

Este guia é uma introdução abrangente à configuração de um ambiente Docker para os teus projetos Ultralytics. O Docker é uma plataforma para desenvolver, distribuir e executar aplicações em contentores. É particularmente útil para garantir que o software funcione sempre da mesma forma, independentemente de onde seja implementado. Para mais detalhes, visita o repositório Docker da Ultralytics no Docker Hub.

O que vais aprender#

• Configurar o Docker com suporte para NVIDIA
• Instalar imagens Docker da Ultralytics
• Executar a Ultralytics num contentor Docker com suporte para CPU ou GPU
• Usar um servidor de visualização com o Docker para mostrar resultados de deteção da Ultralytics
• Montar diretórios locais no contentor

Pré-requisitos#

• Certifica-te de que o Docker está instalado no teu sistema. Caso contrário, podes transferi-lo e instalá-lo a partir do site do Docker.
• Para aceleração por GPU, certifica-te de que o teu sistema tem uma GPU NVIDIA e os controladores NVIDIA instalados. As imagens para CPU não requerem hardware NVIDIA.
• Se estiveres a usar dispositivos NVIDIA Jetson, certifica-te de que tens instalada a versão adequada do JetPack. Consulta o guia NVIDIA Jetson para mais detalhes.

Configurar o Docker com suporte para NVIDIA (opcional)#

Primeiro, verifica se os controladores NVIDIA estão corretamente instalados executando:

nvidia-smi

Instalar o NVIDIA Container Toolkit#

Agora, vamos instalar o NVIDIA Container Toolkit para ativar o suporte para GPU nos contentores Docker:

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
    | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update

sudo apt-get install -y nvidia-container-toolkit

Verificar dispositivos CDI com o Docker#

Executa nvidia-ctk cdi list para garantir que os dispositivos GPU CDI estão disponíveis (o serviço nvidia-cdi-refresh do toolkit gera e mantém automaticamente a especificação no toolkit >= 1.18):

nvidia-ctk cdi list

Deves ver entradas como nvidia.com/gpu=0 e nvidia.com/gpu=all. Os dispositivos CDI detetados também aparecem em docker info.

Instalar imagens Docker da Ultralytics#

A Ultralytics publica as seguintes imagens no Docker Hub. Cada imagem é criada a partir do Dockerfile associado pelo fluxo de publicação do Docker.

As imagens de GPU AMD64 (latest, latest-export e latest-runner) utilizam o PyTorch 2.14 e o CUDA 13.2. Verifica o suporte ao CUDA do controlador do host com nvidia-smi antes de inicia-las; a instalação de um contentor mais recente não atualiza o controlador do host. O CUDA 13 remove o suporte para GPUs Maxwell, Pascal e Volta, incluindo as Tesla P100 e V100. Vê as notas de lançamento do CUDA da NVIDIA e os requisitos de compatibilidade de controladores.

A imagem NVIDIA ARM64 utiliza o NVIDIA PyTorch 26.08 com o CUDA 13.4 e o TensorRT 11.2. O seu suporte do PyTorch para Thor não se estende ao TensorRT: a NVIDIA não suporta o TensorRT 11.2 no JetPack. Para exportações do Jetson TensorRT, utiliza o tempo de execução do TensorRT 10.x suportado para a tua versão do JetPack. Segue os requisitos da plataforma no guia do Jetson ou no guia do DGX Spark. As imagens do JetPack 4, 5 e 6 retêm as suas pilhas específicas de dispositivos separadas.

O Dockerfile do Conda está disponível para compilações locais; a publicação automatizada de latest-conda está desativada, pelo que essa etiqueta de registo não contém estas atualizações.

Utiliza latest-python-export para exportações do LiteRT. A imagem de GPU latest-export mantém o PyTorch 2.14 e omite o LiteRT porque a sua dependência atual requer um PyTorch inferior a 2.14.

As etiquetas que começam por latest acompanham a compilação mais recentemente publicada do branch principal. As etiquetas com versão substituem o prefixo latest por uma versão da Ultralytics, como VERSION, VERSION-cpu ou VERSION-jetson-jetpack6. Usa uma etiqueta com versão para obter um ambiente reproduzível.

Para obter a imagem mais recente:

# Pull the latest Ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latest

Para criares tu próprio uma imagem, clona o repositório e indica o Dockerfile correspondente da tabela acima, usando a raiz do repositório como contexto de compilação:

# Build the CPU image locally from docker/Dockerfile-cpu
sudo docker build -t ultralytics/ultralytics:latest-cpu -f docker/Dockerfile-cpu .

Executar a Ultralytics num contentor Docker#

Eis como executar o contentor Docker da Ultralytics:

Usar apenas a CPU#

# Run without GPU
sudo docker run -it --ipc=host ultralytics/ultralytics:latest-cpu

Usar GPUs#

# Run with all GPUs
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest

# Run specifying which GPUs to use
sudo docker run -it --ipc=host --device nvidia.com/gpu=2 --device nvidia.com/gpu=3 ultralytics/ultralytics:latest

A opção -it atribui um pseudo-TTY e mantém o stdin aberto, permitindo-te interagir com o contentor. A opção --ipc=host ativa a partilha do espaço de nomes IPC do anfitrião, essencial para partilhar memória entre processos. A opção --device nvidia.com/gpu=... concede ao contentor acesso às GPUs do anfitrião através de CDI.

Nota sobre acessibilidade de ficheiros#

Para trabalhar com ficheiros no teu computador local dentro do contentor, podes usar volumes Docker:

# Mount a local directory into the container
sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latest

Substitui /path/on/host pelo caminho do diretório no teu computador local e /path/in/container pelo caminho pretendido dentro do contentor Docker.

Persistir os resultados do treino#

Por predefinição, os resultados do treino são guardados em /ultralytics/runs/<task>/<name>/ dentro do contentor. Sem montar um diretório do anfitrião, os resultados perdem-se quando o contentor é removido.

Para persistir os resultados do treino:

# Recommended: mount workspace and specify project path
sudo docker run --rm -it -v "$(pwd)":/w -w /w ultralytics/ultralytics:latest \
  yolo train model=yolo26n.pt data=coco8.yaml project=/w/runs

Isto guarda todos os resultados do treino em ./runs no teu computador anfitrião.

Executar aplicações de interface gráfica do utilizador (GUI) num contentor Docker#

O Docker é utilizado principalmente para colocar aplicações em segundo plano e programas CLI em contentores, mas também pode executar programas gráficos. No mundo Linux, dois servidores gráficos principais gerem a apresentação gráfica: X11 (também conhecido como X Window System) e Wayland. Antes de começar, é essencial determinar qual servidor gráfico estás a usar atualmente. Executa este comando para descobri-lo:

env | grep -E -i 'x11|xorg|wayland'

A configuração de um servidor de visualização X11 ou Wayland está fora do âmbito deste guia. Se o comando acima não devolver nada, terás primeiro de configurar um deles para funcionar no teu sistema antes de continuar.

Executar um contentor Docker com uma GUI#

xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v ~/.Xauthority:/root/.Xauthority \
  -it --ipc=host ultralytics/ultralytics:latest

Usar o Docker com uma GUI#

Agora podes apresentar aplicações gráficas dentro do teu contentor Docker. Por exemplo, podes executar o seguinte comando CLI para visualizar as previsões de um modelo YOLO26:

yolo predict model=yolo26n.pt show=True

Quando terminares de usar a GUI do Docker#

xhost -local:docker

Está tudo pronto para usares a Ultralytics com o Docker e tirares partido das suas capacidades. Para alojar autonomamente a aplicação Web da Ultralytics, consulta o guia da Plataforma no local. Para métodos alternativos de instalação do pacote Python, consulta a documentação de início rápido da Ultralytics.

Perguntas frequentes#