Guía de inicio rápido de Docker para Ultralytics

Esta guía sirve como introducción completa a la configuración de un entorno Docker para tus proyectos de Ultralytics. Docker es una plataforma para desarrollar, distribuir y ejecutar aplicaciones en contenedores. Es especialmente beneficiosa para garantizar que el software se ejecute siempre igual, independientemente de dónde se despliegue. Para más detalles, visita el repositorio de Docker de Ultralytics en Docker Hub.

Lo que aprenderás

• Configuración de Docker con soporte NVIDIA
• Instalación de imágenes Docker de Ultralytics
• Ejecución de Ultralytics en un contenedor Docker con soporte para CPU o GPU
• Uso de un servidor de pantalla con Docker para mostrar los resultados de detección de Ultralytics
• Montaje de directorios locales en el contenedor

Requisitos previos

• Asegúrate de que Docker esté instalado en tu sistema. Si no es así, puedes descargarlo e instalarlo desde el sitio web de Docker.
• Asegúrate de que tu sistema tenga una GPU NVIDIA y que los controladores NVIDIA estén instalados.
• Si utilizas dispositivos NVIDIA Jetson, asegúrate de tener instalada la versión de JetPack adecuada. Consulta la guía de NVIDIA Jetson para más detalles.

Configuración de Docker con soporte NVIDIA

Primero, verifica que los controladores NVIDIA estén instalados correctamente ejecutando:

nvidia-smi

Instalación del NVIDIA Container Toolkit

Ahora, vamos a instalar el NVIDIA Container Toolkit para habilitar el soporte de GPU en los contenedores 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 el tiempo de ejecución NVIDIA con Docker

Ejecuta docker info | grep -i runtime para asegurarte de que nvidia aparece en la lista de tiempos de ejecución:

docker info | grep -i runtime

Instalación de imágenes Docker de Ultralytics

Ultralytics ofrece varias imágenes Docker optimizadas para diversas plataformas y casos de uso:

• Dockerfile: Imagen con GPU, ideal para entrenamiento.
• Dockerfile-arm64: Para arquitectura ARM64, adecuada para dispositivos como Raspberry Pi.
• Dockerfile-cpu: Versión solo para CPU para inferencia y entornos sin GPU.
• Dockerfile-jetson-jetpack4: Optimizado para dispositivos NVIDIA Jetson que ejecutan NVIDIA JetPack 4.
• Dockerfile-jetson-jetpack5: Optimizado para dispositivos NVIDIA Jetson que ejecutan NVIDIA JetPack 5.
• Dockerfile-jetson-jetpack6: Optimizado para dispositivos NVIDIA Jetson que ejecutan NVIDIA JetPack 6.
• Dockerfile-jupyter: Para desarrollo interactivo mediante JupyterLab en el navegador.
• Dockerfile-nvidia-arm64: Para dispositivos NVIDIA ARM64 como Jetson AGX Thor y DGX Spark, compatible con JetPack 7.0 y DGX OS.
• Dockerfile-python: Entorno Python mínimo para aplicaciones ligeras.
• Dockerfile-python-export: Imagen mínima de Python extendida con capacidades completas de exportación para la conversión de modelos YOLO.
• Dockerfile-conda: Incluye Miniconda3 y el paquete Ultralytics instalado a través de Conda.
• Dockerfile-export: Imagen con GPU con todas las dependencias de formatos de exportación preinstaladas para la conversión y evaluación comparativa de modelos.

Para descargar la última imagen:

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

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

Ejecución de Ultralytics en un contenedor Docker

Aquí tienes cómo ejecutar el contenedor Docker de Ultralytics:

Usando solo la 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

La bandera -it asigna un pseudo-TTY y mantiene la entrada estándar abierta, lo que te permite interactuar con el contenedor. La bandera --ipc=host permite compartir el espacio de nombres IPC del host, esencial para compartir memoria entre procesos. La bandera --gpus permite que el contenedor acceda a las GPUs del host.

Nota sobre la accesibilidad de archivos

Para trabajar con archivos de tu máquina local dentro del contenedor, puedes usar volúmenes de 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

Reemplaza /path/on/host con la ruta del directorio en tu máquina local y /path/in/container con la ruta deseada dentro del contenedor Docker.

Persistencia de los resultados del entrenamiento

Los resultados del entrenamiento se guardan de forma predeterminada en /ultralytics/runs/<task>/<name>/ dentro del contenedor. Sin montar un directorio del host, los resultados se pierden cuando se elimina el contenedor.

Para persistir los resultados del entrenamiento:

# 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

Esto guarda todos los resultados del entrenamiento en ./runs en tu máquina host.

Ejecuta aplicaciones de interfaz gráfica de usuario (GUI) en un contenedor Docker

Docker se utiliza principalmente para contenerizar aplicaciones en segundo plano y programas de CLI, pero también puede ejecutar programas gráficos. En el mundo Linux, dos servidores gráficos principales gestionan la visualización gráfica: X11 (también conocido como el X Window System) y Wayland. Antes de empezar, es esencial determinar qué servidor gráfico estás utilizando actualmente. Ejecuta este comando para averiguarlo:

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

La configuración de un servidor de pantalla X11 o Wayland queda fuera del alcance de esta guía. Si el comando anterior no devuelve nada, tendrás que empezar haciendo que uno de los dos funcione en tu sistema antes de continuar.

Ejecución de un contenedor Docker con una GUI

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

Uso de Docker con una GUI

Ahora puedes mostrar aplicaciones gráficas dentro de tu contenedor Docker. Por ejemplo, puedes ejecutar el siguiente comando CLI para visualizar las predicciones de un modelo YOLO26:

yolo predict model=yolo26n.pt show=True

Al terminar con la GUI de Docker

xhost -local:docker

Ahora ya estás configurado para usar Ultralytics con Docker y listo para aprovechar sus capacidades. Para otros métodos de instalación, consulta la documentación de inicio rápido de Ultralytics.

Preguntas frecuentes

¿Cómo configuro Ultralytics con Docker?

Para configurar Ultralytics con Docker, primero asegúrate de que Docker esté instalado en tu sistema. Si tienes una GPU NVIDIA, instala el NVIDIA Container Toolkit para habilitar el soporte de GPU. Luego, descarga la última imagen Docker de Ultralytics desde Docker Hub usando el siguiente comando:

sudo docker pull ultralytics/ultralytics:latest

Para pasos detallados, consulta nuestra Guía de inicio rápido de Docker.

¿Cuáles son los beneficios de usar imágenes Docker de Ultralytics para proyectos de aprendizaje automático?

Usar imágenes Docker de Ultralytics garantiza un entorno coherente en diferentes máquinas, replicando el mismo software y dependencias. Esto es especialmente útil para colaborar entre equipos, ejecutar modelos en varios tipos de hardware y mantener la reproducibilidad. Para el entrenamiento basado en GPU, Ultralytics ofrece imágenes Docker optimizadas como Dockerfile para uso general de GPU y Dockerfile-jetson para dispositivos NVIDIA Jetson. Explora Ultralytics Docker Hub para más detalles.

¿Cómo puedo ejecutar Ultralytics YOLO en un contenedor Docker con soporte para GPU?

Primero, asegúrate de que el NVIDIA Container Toolkit esté instalado y configurado. Luego, usa el siguiente comando para ejecutar Ultralytics YOLO con soporte para GPU:

sudo docker run -it --ipc=host --runtime=nvidia --gpus all ultralytics/ultralytics:latest # all GPUs

Este comando configura un contenedor Docker con acceso a la GPU. Para detalles adicionales, consulta la Guía de inicio rápido de Docker.

¿Cómo visualizo los resultados de las predicciones de YOLO en un contenedor Docker con un servidor de pantalla?

Para visualizar los resultados de las predicciones de YOLO con una GUI en un contenedor Docker, necesitas permitir que Docker acceda a tu servidor de pantalla. Para sistemas que ejecutan X11, el comando es:

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 que ejecutan 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

Puedes encontrar más información en la sección Ejecuta aplicaciones de interfaz gráfica de usuario (GUI) en un contenedor Docker.

¿Puedo montar directorios locales en el contenedor Docker de Ultralytics?

Sí, puedes montar directorios locales en el contenedor Docker de Ultralytics usando la bandera -v:

sudo docker run -it --ipc=host --runtime=nvidia --gpus all -v /path/on/host:/path/in/container ultralytics/ultralytics:latest

Reemplaza /path/on/host con el directorio en tu máquina local y /path/in/container con la ruta deseada dentro del contenedor. Esta configuración te permite trabajar con tus archivos locales dentro del contenedor. Para más información, consulta la sección Nota sobre la accesibilidad de archivos.