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

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

O que você aprenderá

• Configurar o Docker com suporte a NVIDIA
• Instalando imagens Docker da Ultralytics
• Executando Ultralytics em um container Docker com suporte a CPU ou GPU
• Usando um servidor de exibição com Docker para mostrar resultados de detecção da Ultralytics
• Montando diretórios locais no container

Pré-requisitos

• Certifica-te de que o Docker está instalado no teu sistema. Se não, podes transferi-lo e instalá-lo a partir do site do Docker.
• Certifica-te de que o teu sistema possui uma GPU NVIDIA e que os drivers NVIDIA estão instalados.
• Se estiveres a usar dispositivos NVIDIA Jetson, certifica-te de que tens a versão JetPack apropriada instalada. Consulta o guia da NVIDIA Jetson para mais detalhes.

Configurar o Docker com Suporte a NVIDIA

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

nvidia-smi

Instalando o NVIDIA Container Toolkit

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

Verificar o Runtime NVIDIA com o Docker

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

docker info | grep -i runtime

Instalando Imagens Docker da Ultralytics

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

• Dockerfile: Imagem GPU, ideal para treino.
• 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: Otimizada para dispositivos NVIDIA Jetson a executar o NVIDIA JetPack 4.
• Dockerfile-jetson-jetpack5: Otimizada para dispositivos NVIDIA Jetson a executar o NVIDIA JetPack 5.
• Dockerfile-jetson-jetpack6: Otimizada para dispositivos NVIDIA Jetson a executar o NVIDIA JetPack 6.
• Dockerfile-jupyter: Para desenvolvimento interativo usando o JupyterLab no navegador.
• Dockerfile-nvidia-arm64: Para dispositivos NVIDIA ARM64 como Jetson AGX Thor e DGX Spark, suportando JetPack 7.0 e DGX OS.
• Dockerfile-python: Ambiente Python minimalista para aplicações leves.
• Dockerfile-python-export: Imagem Python minimalista estendida com capacidades completas de exportação para conversão de modelos YOLO.
• Dockerfile-conda: Inclui Miniconda3 e o pacote Ultralytics instalado via Conda.
• Dockerfile-export: Imagem GPU com todas as dependências de formatos de exportação pré-instaladas para conversão e benchmarking de modelos.

Para obter 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

Executando Ultralytics em um Container Docker

Eis como executar o container Docker da Ultralytics:

Usando apenas a CPU

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

Usando 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 interajas com o container. A flag --ipc=host permite a partilha do namespace IPC do host, essencial para partilhar memória entre processos. A flag --gpus permite que o container aceda às GPUs do host.

Nota sobre Acessibilidade de Ficheiros

Para trabalhar com ficheiros na tua máquina local dentro do container, podes usar volumes 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

Substitui /path/on/host pelo caminho do diretório na tua máquina local e /path/in/container pelo caminho desejado dentro do container Docker.

Persistir Resultados de Treino

Os resultados do treino são guardados em /ultralytics/runs/<task>/<name>/ dentro do container por padrão. Sem montar um diretório do host, os resultados perdem-se quando o container é removido.

Para persistir os resultados de 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 na tua máquina host.

Executar aplicações de interface gráfica (GUI) num Container Docker

O Docker é usado principalmente para colocar aplicações de segundo plano e programas CLI em containers, 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 estás a usar atualmente. Executa este comando para descobrir:

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

A configuração de um servidor de exibição X11 ou Wayland está fora do escopo deste guia. Se o comando acima não retornar nada, precisarás de começar por fazer com que um deles funcione no teu sistema antes de continuar.

Executando um Container Docker com GUI

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

Usando Docker com GUI

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

yolo predict model=yolo26n.pt show=True

Quando terminar com o GUI do Docker

xhost -local:docker

Estás agora pronto para usar a Ultralytics com Docker e aproveitar as suas capacidades. Para métodos de instalação alternativos, vê a documentação de início rápido da Ultralytics.

FAQ

Como configuro a Ultralytics com Docker?

Para configurar a Ultralytics com Docker, primeiro certifica-te de que o Docker está instalado no teu sistema. Se tiveres uma GPU NVIDIA, instala o NVIDIA Container Toolkit para ativar o suporte a GPU. Depois, obtém a imagem Docker mais recente da Ultralytics no Docker Hub usando o seguinte comando:

sudo docker pull ultralytics/ultralytics:latest

Para passos detalhados, consulta o nosso Guia de Início Rápido do Docker.

Quais são os benefícios de usar imagens Docker da Ultralytics para projetos de machine learning?

Usar imagens Docker da Ultralytics garante um ambiente consistente entre diferentes máquinas, replicando o mesmo software e dependências. Isto é particularmente útil para colaboração entre equipas, execução de modelos em diversos hardwares e manutenção da reprodutibilidade. Para treino baseado em GPU, a Ultralytics fornece imagens Docker otimizadas como Dockerfile para uso geral de GPU e Dockerfile-jetson para dispositivos NVIDIA Jetson. Explora o Docker Hub da Ultralytics para mais detalhes.

Como posso executar a Ultralytics YOLO num container Docker com suporte a GPU?

Primeiro, certifica-te de que o NVIDIA Container Toolkit está instalado e configurado. Depois, usa o seguinte comando para executar a 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 container Docker com acesso a GPU. Para detalhes adicionais, vê o Guia de Início Rápido do Docker.

Como visualizo os resultados de predição YOLO num container Docker com um servidor de exibição?

Para visualizar resultados de predição YOLO com um GUI num container Docker, precisas de permitir que o Docker aceda ao teu servidor de exibição. Para sistemas a executar 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 a executar Wayland, usa:

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 secção Executar aplicações de interface gráfica (GUI) num Container Docker.

Posso montar diretórios locais no container Docker da Ultralytics?

Sim, podes montar diretórios locais no container Docker da 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

Substitui /path/on/host pelo diretório na tua máquina local e /path/in/container pelo caminho desejado dentro do container. Esta configuração permite-te trabalhar com os teus ficheiros locais dentro do container. Para mais informações, consulta a secção Nota sobre Acessibilidade de Ficheiros.