Guia de Início Rápido do Docker para o Ultralytics#

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

O que você aprenderá#

• Configurar o Docker com suporte a NVIDIA
• Instalar imagens Docker do Ultralytics
• Executar o Ultralytics em um contêiner Docker com suporte a CPU ou GPU
• Usar um servidor de exibição com Docker para mostrar resultados de detecção do Ultralytics
• Montar diretórios locais no contêiner

Pré-requisitos#

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

Configurando o Docker com suporte a NVIDIA (Opcional)#

Primeiro, verifique se os drivers NVIDIA estão instalados corretamente executando:

nvidia-smi

Instalando o NVIDIA Container Toolkit#

Agora, vamos instalar o NVIDIA Container Toolkit para ativar o suporte a 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

Verifica os dispositivos CDI com 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 em toolkits >= 1.18):

nvidia-ctk cdi list

Deverás ver entradas como nvidia.com/gpu=0 e nvidia.com/gpu=all. Os dispositivos CDI descobertos também aparecem em docker info.

Instalando imagens Docker do Ultralytics#

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

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

Para baixar a imagem mais recente:

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

Para construir uma imagem por ti próprio em vez disso, clona o repositório e passa o Dockerfile correspondente da tabela acima, utilizando a raiz do repositório como o contexto de construção:

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

Executando o Ultralytics em um contêiner Docker#

Veja como executar o contêiner Docker do Ultralytics:

Usando apenas a CPU#

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

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

Nota sobre acessibilidade de arquivos#

Para trabalhar com arquivos em sua máquina local dentro do contêiner, você pode 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 na tua máquina local e /path/in/container pelo caminho pretendido dentro do contentor Docker.

Persistindo saídas de treinamento#

As saídas de treino são guardadas em /ultralytics/runs/<task>/<name>/ dentro do contentor por predefinição. Sem montar um diretório de anfitrião, as saídas são perdidas quando o contentor é removido.

Para persistir as saídas de treinamento:

# 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 todas as saídas de treino em ./runs na tua máquina anfitriã.

Executar aplicativos de interface gráfica do usuário (GUI) em um contêiner Docker#

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

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

A configuração e a configuração de um servidor de exibição X11 ou Wayland estão fora do escopo deste guia. Se o comando acima não retornar nada, você precisará começar fazendo com que um deles funcione para seu sistema antes de continuar.

Executando um contêiner 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

Usando 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

Ao terminar com a GUI do Docker#

xhost -local:docker

Estás agora preparado para utilizar a Ultralytics com o Docker e pronto para tirar partido das suas capacidades. Para alojar autonomamente a aplicação web da Ultralytics, consulta o guia de plataforma On-Premise. Para métodos alternativos de instalação de pacotes Python, consulta a documentação de início rápido da Ultralytics.

FAQ#