Soporte de GPU en Docker: NVIDIA Container Toolkit

Qué cubre este artículo

• Cómo instalar NVIDIA Container Toolkit y configurar Docker para acceso a GPU
• Cómo pasar la GPU a un contenedor con --gpus all
• Cómo activar soporte de GPU en docker-compose mediante deploy.resources
• Cómo iniciar Ollama con aceleración GPU en Docker
• Qué obstáculos encontrarás con drivers, runtime y archivos de composición

Introducción: Docker GPU explicado

Docker aísla aplicaciones en contenedores. Por defecto, un contenedor no tiene acceso a la tarjeta gráfica de tu sistema anfitrión. Para cargas de trabajo exclusivamente CPU esto no es un problema. Pero cuando necesitas ejecutar modelos de IA, codificación de video o cálculos basados en CUDA dentro de un contenedor, requieres la GPU. Aquí es donde entra en juego NVIDIA Container Toolkit.

El toolkit es una extensión para Docker que expone el driver NVIDIA del sistema anfitrión dentro de los contenedores. Lo instalas una única vez, configuras la runtime de Docker y luego puedes pasar la GPU a cualquier contenedor mediante el parámetro --gpus all. En el contenedor tendrás disponible nvidia-smi y las aplicaciones CUDA ejecutarán con aceleración GPU completa.

Este artículo te guía paso a paso a través de la instalación en Ubuntu, la prueba de la GPU en un contenedor y la configuración de Ollama con soporte de GPU. Si aún no estás familiarizado con Docker, consulta primero los Fundamentos de Docker. Una visión general sobre Self-Hosting la encuentras en Self-Hosting.

Por qué necesito GPU en Docker

Imagina que ejecutas Ollama en un contenedor Docker en tu servidor. Sin soporte de GPU, el modelo corre en la CPU. Un modelo de 7B como Llama 3 necesita cerca de 30 a 60 segundos en una CPU moderna para generar los primeros tokens y luego algunos tokens por segundo. Una conversación sería prácticamente inutilizable.

Con GPU la situación cambia radicalmente. Una GPU NVIDIA con 8 GB de VRAM genera 30 a 60 tokens por segundo con el mismo modelo, y los primeros tokens aparecen en menos de un segundo. La diferencia es enorme. Encontrarás más comparaciones en el artículo CPU vs. GPU y en GPU-Offloading.

Para que Ollama en Docker pueda usar la GPU, debes pasar la tarjeta gráfica al contenedor. Esto se llama GPU Passthrough. Para hacerlo necesitas NVIDIA Container Toolkit, que actúa como puente entre el driver del anfitrión y el contenedor. Sin este toolkit, el contenedor no verá ninguna GPU, sin importar qué parámetros envíes.

Docker GPU en pocas palabras

Instalas NVIDIA Container Toolkit, configuras la runtime de Docker con nvidia-ctk runtime configure --runtime=docker y reinicia Docker. Después pasas el parámetro --gpus all a cada contenedor que necesite acceso a GPU. En docker-compose usas el bloque deploy.resources.reservations.devices con el driver nvidia. Dentro del contenedor verificas con nvidia-smi si la GPU se reconoce.

Para quién es este artículo

Este artículo está dirigido a cualquiera que quiera ejecutar cargas de trabajo aceleradas por GPU en contenedores Docker. Esto incluye self-hosters que operan Ollama u otras herramientas de IA en un servidor con GPU NVIDIA. Desarrolladores que necesitan probar e implementar aplicaciones CUDA en contenedores. Y administradores que desean gestionar múltiples servicios de GPU en una máquina de forma aislada.

Si nunca has usado Docker, comienza con los Fundamentos de Docker. Si no conoces Ollama, lee primero la Descripción general de Ollama.

Términos importantes

Término	Significado
NVIDIA Container Toolkit	Paquete de software que pone GPUs NVIDIA disponibles en contenedores Docker
nvidia-smi	Herramienta de línea de comandos que muestra estado de GPU, VRAM y procesos
CUDA	Plataforma NVIDIA para computación paralela en GPU
Docker Runtime	Componente que inicia y gestiona contenedores, extensible con soporte de GPU
—gpus	Parámetro de Docker que pasa una o varias GPUs a un contenedor
GPU Passthrough	Exposición de la GPU física a un contenedor o máquina virtual
Container	Entorno de ejecución aislado que ejecuta una imagen con todas sus dependencias
VRAM	Memoria de video de la GPU donde residen modelos y resultados intermedios
Driver	Driver NVIDIA en el sistema anfitrión, requisito previo para acceso a GPU
Runtime	Entorno de ejecución, configurable en Docker a través de nvidia-ctk

Requisitos previos

Antes de comenzar, necesitas dos cosas en tu sistema anfitrión:

1. Un driver NVIDIA funcional. Verifica con nvidia-smi en el anfitrión si se reconoce la GPU:

nvidia-smi

Si ves una tabla con el nombre de la GPU, versión del driver y VRAM, el driver está correctamente instalado. Si falta el comando o aparece un error, instala primero el driver NVIDIA. En Ubuntu lo haces con:

sudo ubuntu-drivers autoinstall
sudo reboot

2. Docker instalado. Verifica la versión de Docker:

docker --version

Si Docker no está disponible, instálalo a través del instalador oficial. Una guía la encuentras en los Fundamentos de Docker y en el artículo sobre Ubuntu.

Instalar NVIDIA Container Toolkit

La instalación en Ubuntu se realiza en unos pocos pasos. Agregando el repositorio NVIDIA, instalas el paquete y configuras la runtime de Docker.

Paso 1: Agregar la clave del repositorio

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

Paso 2: Registrar el repositorio

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

Paso 3: Instalar el paquete

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

Paso 4: Configurar la runtime de Docker

sudo nvidia-ctk runtime configure --runtime=docker

Este comando añade la runtime NVIDIA a la configuración de Docker. Puedes verificarlo:

cat /etc/docker/daemon.json

El archivo debe contener una entrada para nvidia como runtime predeterminada o como runtime nombrada.

Paso 5: Reiniciar Docker

sudo systemctl restart docker

De esta forma Docker aplica la nueva configuración. A partir de ahora puedes pasar la GPU a los contenedores.

Probar Docker con GPU

Después de la instalación, verifica que la GPU sea accesible dentro de un contenedor. Para ello usas la imagen oficial de CUDA de NVIDIA:

docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

Si en la salida ves la tabla de GPU, todo está configurado correctamente. El contenedor tiene acceso a la tarjeta gráfica.

También puedes pasar una GPU específica si tienes varias:

docker run --rm --gpus '"device=0"' nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

El parámetro '"device=0"' selecciona la primera GPU. Con '"device=0,1"' pasas dos GPUs.

Ollama con GPU en Docker

Ollama aprovecha enormemente la aceleración por GPU. Con el toolkit instalado, puedes iniciar Ollama con soporte de GPU:

docker run -d --gpus all --name ollama-gpu -p 11434:11434 -v ollama-data:/root/.ollama ollama/ollama

Los parámetros individuales significan:

• -d: Inicia el contenedor en segundo plano
• --gpus all: Pasa todas las GPUs al contenedor
• --name ollama-gpu: Nombre del contenedor para una referencia sencilla
• -p 11434:11434: Mapeo de puertos para la API de Ollama
• -v ollama-data:/root/.ollama: Volumen para la persistencia de modelos

Verifica que la GPU se reconozca dentro del contenedor:

docker exec -it ollama-gpu nvidia-smi

Si aparece la tabla de GPU, Ollama está utilizando la tarjeta gráfica. Puedes encontrar más información sobre Ollama con Docker en el artículo Ollama con Docker.

docker-compose con GPU

Para configuraciones reproducibles, usa docker-compose. La configuración de GPU se realiza a través del bloque deploy.resources.

Crea un archivo docker-compose.yml:

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama-gpu
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  ollama-data:

Inicia el contenedor:

docker compose up -d

El bloque deploy.resources.reservations.devices le indica a Docker que el contenedor necesita una GPU NVIDIA. La entrada count: all pasa todas las GPUs. Con count: 1 pasas exactamente una. El campo capabilities: [gpu] marca el tipo de dispositivo.

En versiones antiguas de Docker se utilizaba runtime: nvidia. Esto ya no funciona de manera confiable en versiones actuales. En su lugar, utiliza el bloque deploy.

Ejemplo: Ollama GPU en Docker

Aquí tienes un ejemplo completo desde la instalación hasta que el modelo esté funcionando.

Paso 1: Instalar el toolkit (como se describió arriba)

Paso 2: Crear docker-compose.yml

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama-gpu
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  ollama-data:

Paso 3: Iniciar el contenedor

docker compose up -d

Paso 4: Verificar la GPU dentro del contenedor

docker exec -it ollama-gpu nvidia-smi

Paso 5: Descargar el modelo

docker exec -it ollama-gpu ollama pull llama3

Paso 6: Ejecutar el modelo

docker exec -it ollama-gpu ollama run llama3

El chat se abre en la terminal. La aceleración por GPU proporciona respuestas rápidas. Termina la sesión con /bye.

Problemas comunes

La GPU no se reconoce en el contenedor. Generalmente falta la configuración de runtime o Docker no fue reiniciado. Verifica con nvidia-smi en el host y con docker exec -it ollama-gpu nvidia-smi en el contenedor. Si funciona en el host pero no en el contenedor, te falta nvidia-ctk runtime configure --runtime=docker o necesitas reiniciar Docker.

Driver NVIDIA desactualizado. El toolkit requiere un driver compatible. Si tu driver es demasiado antiguo, la instalación fallará o nvidia-smi no funcionará en el contenedor. Actualiza el driver y reinicia.

--gpus no se reconoce. Este parámetro existe solo a partir de Docker 19.03. Si usas una versión más antigua, actualiza Docker. Verifica con docker --version.

docker-compose ignora la configuración de GPU. En versiones actuales de Docker, runtime: nvidia ya no funciona. Usa el bloque deploy.resources.reservations.devices. Asegúrate de utilizar docker-compose v2, no la versión antigua de Python.

El contenedor se ejecuta pero la aplicación CUDA se bloquea. A veces faltan las bibliotecas CUDA en el contenedor. Usa una imagen que ya contenga CUDA, por ejemplo nvidia/cuda:12.4.0-base-ubuntu22.04, o instala CUDA en el Dockerfile.

VRAM insuficiente. Los modelos grandes requieren mucha VRAM. Si la GPU no tiene suficiente memoria de video, la aplicación se interrumpe o retrocede al modo CPU. Verifica el consumo de VRAM con nvidia-smi mientras el modelo se ejecuta. Más información en GPU-Offloading.

Múltiples contenedores comparten una GPU. Si varios contenedores con GPU se ejecutan simultáneamente, comparten la VRAM. Esto puede provocar errores de OOM. Monitorea la VRAM con nvidia-smi y distribuye las cargas entre varias GPUs o inicia los contenedores secuencialmente.

Hardware, costos y seguridad

Hardware: Necesitas una GPU NVIDIA con suficiente VRAM. Para modelos de 7B son suficientes 8 GB de VRAM, para modelos de 13B necesitas 12 a 16 GB, para modelos de 70B mucho más. El host debe tener suficiente RAM y CPU para mantener el contenedor y el sistema operativo. Más información sobre decisiones de hardware en CPU vs. GPU.

Costos: El NVIDIA Container Toolkit es gratuito y de código abierto. Docker también es gratuito. Los costos surgen únicamente del hardware, es decir, GPU, servidor y electricidad. No hay cuotas de licencia.

Seguridad: El paso de GPU al contenedor le da acceso completo a la GPU. Esto no es un riesgo de seguridad para el host siempre que uses imágenes de confianza. Asegúrate de usar solo imágenes oficiales de Docker Hub o de fuentes confiables. Si tienes varios usuarios en un servidor, los contenedores con GPU no deben ser accesibles sin protección en la red. Utiliza reglas de firewall y, si es posible, una VPN como Tailscale para el acceso remoto.

Enlaces relacionados

• Self-Hosting para una descripción general del tema
• Docker Grundlagen para comenzar con Docker
• Ollama con Docker para la configuración específica de Docker en Ollama
• Ollama Übersicht para una introducción general
• CPU vs. GPU para comparar la ejecución en CPU y GPU
• GPU-Offloading para detalles sobre el uso de GPU
• Ubuntu para conceptos básicos del sistema operativo

Preguntas frecuentes: soporte de GPU en Docker

¿Necesito el NVIDIA Container Toolkit para GPUs de AMD?

No. El toolkit es específico para NVIDIA. Para GPUs de AMD, usa el stack ROCm y pasa la GPU a través de --device /dev/kfd y --device /dev/dri. La configuración es muy diferente a la de NVIDIA.

¿Funciona el soporte de GPU sin el driver NVIDIA en el host?

No. El toolkit pasa el driver del host al contenedor. Sin un driver NVIDIA funcional en el host, no hay GPU en el contenedor. Instala primero el driver y verifica con nvidia-smi en el host.

¿Puedo dividir varias GPUs en diferentes contenedores?

Sí. Con --gpus '"device=0"' pasas solo la primera GPU, con '"device=1"' la segunda. En docker-compose, usa count: 1 y añade device_ids: [0] en el bloque de dispositivos.

¿Qué significa capabilities: [gpu] en docker-compose?

La entrada marca el tipo de dispositivo que el contenedor necesita. gpu es el estándar para el acceso a GPU. También puedes especificar compute, utility, graphics o video si necesitas funciones CUDA específicas.

¿Funciona el soporte de GPU en Windows con Docker Desktop?

Sí, con el backend WSL2 y los drivers NVIDIA correspondientes para WSL. El parámetro --gpus all funciona como en Linux. En macOS con Apple Silicon, la GPU se proporciona a través de Metal, el toolkit no es necesario allí.

¿Cómo veo cuánta VRAM está usando mi contenedor?

Ejecuta nvidia-smi en el host mientras el contenedor se está ejecutando. La tabla muestra todos los procesos que utilizan recursos de GPU, junto con su consumo de VRAM. Alternativamente, usa docker exec -it ollama-gpu nvidia-smi en el contenedor.

¿Debo reiniciar Docker si actualizo el driver NVIDIA?

Sí. Después de actualizar el driver, reinicia el host o al menos el servicio Docker con sudo systemctl restart docker. De lo contrario, el contenedor podría acceder a una versión antigua del driver.

¿Puedo activar el soporte de GPU después sin recrear el contenedor?

No. El parámetro --gpus se establece cuando inicia un contenedor. Debes detener el contenedor, eliminarlo e iniciarlo nuevamente con --gpus all. El volumen protege tus datos.

¿Cuál es la diferencia entre --gpus all y runtime: nvidia?

--gpus all es el estándar actual desde Docker 19.03. runtime: nvidia era el método anterior y se considera obsoleto. En docker-compose, usa el bloque deploy.resources, no la línea de runtime.

¿Necesito CUDA en el contenedor si he instalado el toolkit?

Depende de tu aplicación. El toolkit pasa el driver, pero las bibliotecas CUDA deben estar presentes en la imagen. En Ollama, están incluidas en la imagen. En tus propias aplicaciones, usa una imagen CUDA o instala CUDA en el Dockerfile.

¿Puedo ejecutar Ollama con GPU en Docker en un NAS?

Sí, si el NAS tiene una GPU NVIDIA y está basado en Linux, por ejemplo un dispositivo Ugreen o Asrock. Los NAS de Synology suelen tener Intel o AMD y no soportan directamente el NVIDIA Container Toolkit. Verifica la compatibilidad de hardware de tu NAS.

Fuentes

• NVIDIA Container Toolkit Dokumentation: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/
• Docker GPU-Dokumentation: https://docs.docker.com/config/containers/resource_constraints/#gpu
• NVIDIA CUDA Docker Images: https://hub.docker.com/r/nvidia/cuda
• Ollama Docker Image: https://hub.docker.com/r/ollama/ollama