Link to this sectionGuia 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.

Link to this sectionO 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

Link to this sectionPré-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.
• Certifique-se de que seu sistema tenha uma GPU NVIDIA e que os drivers NVIDIA estejam instalados.
• Se você estiver usando dispositivos NVIDIA Jetson, certifique-se de ter a versão do JetPack apropriada instalada. Consulte o guia do NVIDIA Jetson para mais detalhes.

Link to this sectionConfigurando o Docker com suporte a NVIDIA#

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

nvidia-smi

Link to this sectionInstalando 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 \
  nvidia-container-toolkit-base libnvidia-container-tools \
  libnvidia-container1

export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.17.8-1
sudo apt-get install -y \
  nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
  libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Link to this sectionVerificar o NVIDIA Runtime com o Docker#

Executa docker info | grep -i runtime para garantir que nvidia aparece na lista de runtimes:

docker info | grep -i runtime

Link to this sectionInstalando imagens Docker do Ultralytics#

O Ultralytics oferece várias imagens Docker otimizadas para diversas plataformas e casos de uso:

• Dockerfile: imagem com GPU, ideal para treinamento.
• Dockerfile-arm64: Para arquitetura ARM64, adequada para dispositivos como Raspberry Pi.
• Dockerfile-cpu: Versão apenas para CPU para inferência e ambientes sem GPU.
• Dockerfile-jetson-jetpack4: Otimizado para dispositivos NVIDIA Jetson executando NVIDIA JetPack 4.
• Dockerfile-jetson-jetpack5: Otimizado para dispositivos NVIDIA Jetson executando NVIDIA JetPack 5.
• Dockerfile-jetson-jetpack6: Otimizado para dispositivos NVIDIA Jetson executando NVIDIA JetPack 6.
• Dockerfile-jupyter: Para desenvolvimento interativo usando JupyterLab no navegador.
• Dockerfile-nvidia-arm64: Para dispositivos NVIDIA ARM64, como Jetson AGX Thor e DGX Spark, com suporte ao JetPack 7.0 e DGX OS.
• Dockerfile-python: Ambiente Python mínimo para aplicativos leves.
• Dockerfile-python-export: Imagem Python mínima estendida com recursos completos de exportação para conversão de modelos YOLO.
• Dockerfile-conda: Inclui Miniconda3 e o pacote Ultralytics instalado via Conda.
• Dockerfile-export: Imagem com GPU com todas as dependências de formato de exportação pré-instaladas para conversão e benchmarking de modelos.

Para baixar a imagem mais recente:

# Set image name as a variable
t=ultralytics/ultralytics:latest

# Pull the latest Ultralytics image from Docker Hub
sudo docker pull $t

Link to this sectionExecutando o Ultralytics em um contêiner Docker#

Veja como executar o contêiner Docker do Ultralytics:

Link to this sectionUsando apenas a CPU#

# Run without GPU
sudo docker run -it --ipc=host $t

Link to this sectionUsando GPUs#

# Run with all GPUs
sudo docker run -it --ipc=host --runtime=nvidia --gpus all $t

# Run specifying which GPUs to use
sudo docker run -it --ipc=host --runtime=nvidia --gpus '"device=2,3"' $t

A flag -it atribui um pseudo-TTY e mantém o stdin aberto, permitindo que você interaja com o contêiner. A flag --ipc=host permite o compartilhamento do namespace IPC do host, essencial para compartilhar memória entre processos. A flag --gpus permite que o contêiner acesse as GPUs do host.

Link to this sectionNota 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 --runtime=nvidia --gpus all -v /path/on/host:/path/in/container $t

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.

Link to this sectionPersistindo 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.

Link to this sectionExecutar 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.

Link to this sectionExecutando 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 $t

Link to this sectionUsando 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

Link to this sectionAo terminar com a GUI do Docker#

xhost -local:docker

Agora você está pronto para usar o Ultralytics com Docker e aproveitar suas capacidades. Para métodos de instalação alternativos, consulte a documentação de início rápido do Ultralytics.

Link to this sectionFAQ#

Link to this sectionComo 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.

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

Usar imagens Docker do 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 vários hardwares e manter a reprodutibilidade. Para treinamento baseado em GPU, o Ultralytics fornece imagens Docker otimizadas, como Dockerfile para uso geral de GPU e Dockerfile-jetson para dispositivos NVIDIA Jetson. Explore o Docker Hub do Ultralytics para mais detalhes.

Link to this sectionComo 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 --runtime=nvidia --gpus 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.

Link to this sectionComo 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.

Link to this sectionPosso 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 --runtime=nvidia --gpus 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.