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

Este guia serve como uma introdução abrangente para configurar um ambiente Docker para seus projetos Ultralytics. O Docker é uma plataforma para desenvolver, distribuir e executar aplicativos em contêineres. É particularmente benéfico para garantir que o software sempre seja executado da mesma forma, independentemente de onde seja implantado. Para mais detalhes, visite o repositório Docker do 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#

• Certifique-se de que o Docker esteja instalado em seu sistema. Caso contrário, você pode baixá-lo e instalá-lo no site do Docker.
• Para aceleração por GPU, garanta que seu sistema tenha uma GPU NVIDIA e drivers NVIDIA instalados. Imagens de CPU não requerem hardware NVIDIA.
• Se estiveres a usar dispositivos NVIDIA Jetson, certifica-te de que tens a versão correta do JetPack instalada. Consulta o NVIDIA Jetson guide 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 habilitar o suporte a GPU em contêineres 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

Deves ver entradas como nvidia.com/gpu=0 e nvidia.com/gpu=all. Os dispositivos CDI detetados 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 de seu respectivo Dockerfile pelo fluxo de trabalho de publicação do Docker.

As tags começando com latest acompanham a compilação do branch main publicada mais recentemente. Tags com versão substituem o prefixo latest por um lançamento da Ultralytics, como VERSION, VERSION-cpu ou VERSION-jetson-jetpack6. Use uma tag com versão para obter um ambiente reproduzível.

Para baixar a imagem mais recente:

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

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 que interajas com o contentor. A flag --ipc=host permite a partilha do namespace IPC do host, essencial para partilhar memória entre processos. A flag --device nvidia.com/gpu=... concede ao contentor acesso às GPUs do host através de 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

Substitua /path/on/host pelo caminho do diretório na sua máquina local e /path/in/container pelo caminho desejado dentro do contêiner Docker.

Persistindo saídas de treinamento#

As saídas de treinamento são salvas em /ultralytics/runs/<task>/<name>/ dentro do contêiner por padrão. Sem montar um diretório do host, as saídas são perdidas quando o contêiner é 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

Isso salva todas as saídas de treinamento em ./runs na sua máquina host.

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

O Docker é usado principalmente para conteinerizar aplicativos em segundo plano e programas CLI, mas também pode executar programas gráficos. No mundo Linux, dois servidores gráficos principais lidam com a exibição gráfica: X11 (também conhecido como X Window System) e Wayland. Antes de começar, é essencial determinar qual servidor gráfico você está usando atualmente. Execute 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 você pode exibir aplicativos gráficos dentro do seu contêiner Docker. Por exemplo, você pode 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

Agora você está pronto para usar a Ultralytics com Docker e tirar proveito de suas capacidades. Para auto-hospedar a aplicação web da Ultralytics, consulte o guia de plataforma local (On-Premise). Para métodos alternativos de instalação do pacote Python, consulte a documentação de início rápido da Ultralytics.

FAQ#

Como configuro o Ultralytics com Docker?#

Para configurar o Ultralytics com Docker, primeiro garanta que o Docker esteja instalado em seu sistema. Se você tiver uma GPU NVIDIA, instale o NVIDIA Container Toolkit para habilitar o suporte a GPU. Em seguida, baixe a imagem Docker mais recente do Ultralytics do Docker Hub usando o seguinte comando:

sudo docker pull ultralytics/ultralytics:latest

Para etapas detalhadas, consulte nosso Guia de Início Rápido do Docker.

Quais são os benefícios de usar imagens Docker do Ultralytics para projetos de aprendizado de máquina?#

O uso das imagens Docker da Ultralytics garante um ambiente consistente entre diferentes máquinas, replicando o mesmo software e dependências. Isso é particularmente útil para colaborar entre equipes, executar modelos em diversos hardwares e manter a reprodutibilidade. Use latest para treinamento geral em GPU NVIDIA ou selecione a imagem correspondente à sua versão do JetPack para um dispositivo NVIDIA Jetson. Consulte a tabela completa de imagens ou explore o Docker Hub da Ultralytics.

Como posso executar o Ultralytics YOLO em um contêiner Docker com suporte a GPU?#

Primeiro, garanta que o NVIDIA Container Toolkit esteja instalado e configurado. Em seguida, use o seguinte comando para executar o Ultralytics YOLO com suporte a GPU:

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

Este comando configura um contêiner Docker com acesso a GPU. Para detalhes adicionais, consulte o Guia de Início Rápido do Docker.

Como visualizo os resultados da previsão do YOLO em um contêiner Docker com um servidor de exibição?#

Para visualizar os resultados da previsão do YOLO com uma GUI em um contêiner Docker, você precisa permitir que o Docker acesse seu servidor de exibição. Para sistemas executando X11, o comando é:

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

Para sistemas executando Wayland, use:

xhost +local:docker && docker run -e DISPLAY=$DISPLAY \
  -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/tmp/$WAYLAND_DISPLAY \
  --net=host -it --ipc=host ultralytics/ultralytics:latest

Mais informações podem ser encontradas na seção Executar aplicativos de interface gráfica do usuário (GUI) em um contêiner Docker.

Posso montar diretórios locais no contêiner Docker do Ultralytics?#

Sim, você pode montar diretórios locais no contêiner Docker do Ultralytics usando a flag -v:

sudo docker run -it --ipc=host --device nvidia.com/gpu=all -v /path/on/host:/path/in/container ultralytics/ultralytics:latest

Substitua /path/on/host pelo diretório na sua máquina local e /path/in/container pelo caminho desejado dentro do contêiner. Esta configuração permite que você trabalhe com seus arquivos locais dentro do contêiner. Para mais informações, consulte a seção Nota sobre acessibilidade de arquivos.