Guia de início rápido do Docker para a 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 é sempre executado da mesma forma, independentemente do local onde é 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 ecrã com o Docker para apresentar os 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 obter 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 precisam de hardware NVIDIA.
• Se estiveres a usar dispositivos NVIDIA Jetson, certifica-te de que tens instalada a versão adequada do JetPack. Consulta o guia da NVIDIA Jetson para mais detalhes.

Configurar o Docker com suporte para NVIDIA (opcional)#

Primeiro, verifica se os controladores NVIDIA estão instalados corretamente, 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 CDI da GPU estão disponíveis (o serviço nvidia-cdi-refresh do toolkit gera e mantém a especificação automaticamente 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 é compilada a partir do Dockerfile associado pelo fluxo de publicação do Docker.

As imagens de GPU AMD64 (latest, latest-export e latest-runner) usam PyTorch 2.14 e CUDA 13.2. Verifica a compatibilidade do controlador do anfitrião com CUDA através de nvidia-smi antes de as iniciar; instalar um contentor mais recente não atualiza o controlador do anfitrião. O CUDA 13 deixou de ser compatível com as GPU Maxwell, Pascal e Volta, incluindo a Tesla P100 e a V100. Consulta as notas de lançamento do CUDA da NVIDIA e os requisitos de compatibilidade dos controladores.

A imagem NVIDIA ARM64 usa NVIDIA PyTorch 26.08 com CUDA 13.4 e TensorRT 11.2. O 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 TensorRT no Jetson, usa o runtime TensorRT 10.x compatível com 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 mantêm as respetivas pilhas específicas para cada dispositivo.

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

Usa latest-python-export para exportações LiteRT. A imagem de GPU latest-export mantém o PyTorch 2.14 e não inclui LiteRT, porque a dependência atual deste requer uma versão do PyTorch anterior à 2.14.

As imagens Python, CPU, Jupyter e executor de CPU usam Python 3.14. A imagem Python para exportação usa a base latest-python-3.13, criada a partir da mesma Dockerfile-python com --build-arg PYTHON_VERSION=3.13, porque TensorFlow, CoreML e PaddlePaddle ainda não oferecem suporte ao Python 3.14.

As etiquetas que começam por latest acompanham a compilação mais recente publicada a partir do ramo principal. Nas etiquetas com versões, o prefixo latest é substituído 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 transferir a imagem mais recente:

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

Em alternativa, para compilares uma imagem, clona o repositório e indica o Dockerfile correspondente na 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#

Segue estas instruções para executar o contentor Docker da Ultralytics:

Usar apenas a CPU#

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

Usar GPU#

# 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. Para GPU NVIDIA, a opção --device nvidia.com/gpu=... concede acesso através de CDI. Para GPU AMD, as opções --device concedem acesso ao controlador de kernel da GPU (/dev/kfd) e aos nós de renderização do ecrã (/dev/dri).

Nota sobre o acesso a ficheiros#

Para trabalhar com ficheiros do teu computador local dentro do contentor, podes usar volumes do 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.

Manter os resultados do treino#

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

Para manter 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 é usado 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 tratam da apresentação gráfica: X11 (também conhecido como X Window System) e Wayland. Antes de começar, é essencial determinar que servidor gráfico estás a usar. Executa este comando para descobrir:

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

A configuração de um servidor de ecrã X11 ou Wayland está fora do âmbito deste guia. Se o comando acima não devolver nada, terás de começar por 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#

As imagens da Ultralytics incluem OpenCV sem interface gráfica, por isso, primeiro instala a versão do OpenCV com interface gráfica e as bibliotecas do sistema no contentor:

apt-get update && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 libsm6
pip uninstall -y opencv-python-headless && pip install opencv-python

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

Agora já tens tudo preparado para usar a Ultralytics com o Docker e tirar partido das respetivas capacidades. Para alojar a aplicação Web da Ultralytics no teu próprio servidor, consulta o guia da plataforma no local. Para conhecer métodos alternativos de instalação do pacote Python, consulta a documentação de início rápido da Ultralytics.

Perguntas frequentes#