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

Esta guía sirve como una 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 de la misma manera, independientemente de dónde se implemente. Para obtener más detalles, visita el repositorio de Ultralytics Docker en Docker Hub.

Lo que aprenderás#

• Configuración de Docker con soporte para NVIDIA
• Instalación de imágenes de 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.
• Para la aceleración por GPU, asegúrate de que tu sistema tenga una GPU NVIDIA y los controladores de NVIDIA instalados. Las imágenes de CPU no requieren hardware de NVIDIA.
• Si utilizas dispositivos NVIDIA Jetson, asegúrate de tener instalada la versión de JetPack adecuada. Consulta la guía de NVIDIA Jetson para obtener más detalles.

Configurar Docker con soporte para NVIDIA (opcional)#

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

nvidia-smi

Instalación de NVIDIA Container Toolkit#

Ahora, instalemos 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

Verifica los dispositivos CDI con Docker#

Ejecuta nvidia-ctk cdi list para asegurarte de que los dispositivos CDI de la GPU estén disponibles (el servicio nvidia-cdi-refresh del kit de herramientas genera y mantiene la especificación automáticamente en versiones del kit de herramientas >= 1.18):

nvidia-ctk cdi list

Deberías ver entradas como nvidia.com/gpu=0 y nvidia.com/gpu=all. Los dispositivos CDI descubiertos también aparecen en docker info.

Instalación de imágenes de Docker de Ultralytics#

Ultralytics publica las siguientes imágenes en Docker Hub. Cada imagen se compila a partir de su archivo Dockerfile vinculado mediante el flujo de trabajo de publicación en Docker.

Las etiquetas que comienzan con latest rastrean la compilación de la rama principal publicada más recientemente. Las etiquetas con versión reemplazan el prefijo latest con una versión de Ultralytics, como VERSION, VERSION-cpu o VERSION-jetson-jetpack6. Utiliza una etiqueta con versión para obtener un entorno reproducible.

Para descargar la última imagen:

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

Para construir una imagen tú mismo en su lugar, clona el repositorio y pasa el Dockerfile correspondiente de la tabla anterior, utilizando la raíz del repositorio como contexto de compilación:

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

Ejecución de Ultralytics en un contenedor Docker#

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

Uso exclusivo de la CPU#

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

Uso de 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

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, algo esencial para compartir memoria entre procesos. La bandera --device nvidia.com/gpu=... otorga al contenedor acceso a las GPU del host a través de CDI.

Nota sobre la accesibilidad de archivos#

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

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 las salidas de entrenamiento#

Los resultados del entrenamiento se guardan por defecto en /ultralytics/runs/<task>/<name>/ dentro del contenedor. Si no montas un directorio del host, los resultados se perderán cuando se elimine el contenedor.

Para persistir las salidas de 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.

Ejecución de aplicaciones con 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 de Linux, dos servidores gráficos principales gestionan la visualización gráfica: X11 (también conocido como X Window System) y Wayland. Antes de empezar, es fundamental 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, deberás empezar por hacer 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 ultralytics/ultralytics:latest

Uso de Docker con una GUI#

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

yolo predict model=yolo26n.pt show=True

Cuando termines con la GUI de Docker#

xhost -local:docker

Ahora ya tienes todo configurado para usar Ultralytics con Docker y estás listo para aprovechar al máximo sus capacidades. Para alojar por ti mismo la aplicación web de Ultralytics, consulta la guía de plataforma local (On-Premise). Para conocer métodos alternativos de instalación de paquetes de Python, consulta la documentación de inicio rápido de Ultralytics.

FAQ#