Añadir soporte para GPU de NVIDIA al ejecutor de modelos de Docker

Habilite la aceleración de GPU para Docker Model Runner con soporte de NVIDIA CUDA

Docker Model Runner es la herramienta oficial de Docker para ejecutar modelos de IA localmente, pero habilitar la aceleración de GPU de NVidia en Docker Model Runner requiere una configuración específica.

A diferencia de los comandos estándar docker run, docker model run no admite las banderas --gpus o -e, por lo que el soporte de GPU debe configurarse a nivel del demonio de Docker y durante la instalación del runner.

Si estás buscando una solución alternativa de alojamiento de LLM con una configuración de GPU más sencilla, considera Ollama, que tiene soporte integrado de GPU y una instalación más sencilla. Sin embargo, Docker Model Runner ofrece una mejor integración con el ecosistema de Docker y la distribución de artefactos OCI.

Docker Model Runner con soporte de GPU de NVIDIA Esta imagen agradable fue generada por modelo AI Flux 1 dev.

Requisitos previos

Antes de configurar el soporte de GPU, asegúrate de tener:

Verifica que tu GPU esté accesible:

nvidia-smi

Prueba el acceso a GPU de Docker:

docker run --rm --gpus all nvidia/cuda:12.2.2-base-ubi8 nvidia-smi

Para más comandos de Docker y opciones de configuración, consulta nuestra Guía de atajos de Docker.

Paso 1: Configurar el demonio de Docker para el runtime de NVIDIA

Docker Model Runner requiere que el runtime de NVIDIA se establezca como el runtime predeterminado en la configuración del demonio de Docker.

Encontrar la ruta del runtime de NVIDIA Container

Primero, localiza donde se instaló nvidia-container-runtime:

which nvidia-container-runtime

Esto normalmente devuelve /usr/bin/nvidia-container-runtime. Anota esta ruta para el siguiente paso.

Configurar el demonio de Docker

Crea o actualiza /etc/docker/daemon.json para establecer NVIDIA como el runtime predeterminado:

sudo tee /etc/docker/daemon.json > /dev/null << 'EOF'
{
  "default-runtime": "nvidia",
  "runtimes": {
    "nvidia": {
      "path": "/usr/bin/nvidia-container-runtime",
      "runtimeArgs": []
    }
  }
}
EOF

Importante: Si which nvidia-container-runtime devolvió una ruta diferente, actualiza el valor de "path" en la configuración JSON en consecuencia.

Reiniciar el servicio de Docker

Aplica la configuración reiniciando Docker:

sudo systemctl restart docker

Verificar la configuración

Confirma que el runtime de NVIDIA esté configurado:

docker info | grep -i runtime

Deberías ver Default Runtime: nvidia en la salida.

Paso 2: Instalar Docker Model Runner con soporte de GPU

Docker Model Runner debe instalarse o reinstalarse con soporte de GPU explícito. El contenedor del runner en sí mismo debe ser la versión habilitada para CUDA.

Detener el runner actual (si está en ejecución)

Si Docker Model Runner ya está instalado, deténlo primero:

docker model stop-runner

Instalar/Reinstalar con soporte de CUDA

Instala o reinstala Docker Model Runner con soporte de GPU de CUDA:

docker model reinstall-runner --gpu cuda

Este comando:

  • Descarga la versión habilitada para CUDA (docker/model-runner:latest-cuda) en lugar de la versión solo para CPU
  • Configura el contenedor del runner para usar el runtime de NVIDIA
  • Habilita la aceleración de GPU para todos los modelos

Nota: Si ya has instalado Docker Model Runner sin soporte de GPU, debes reinstalarlo con la bandera --gpu cuda. Solo configurar el demonio de Docker no es suficiente — el contenedor del runner en sí mismo debe ser la versión habilitada para CUDA.

Backends de GPU disponibles

Docker Model Runner admite varios backends de GPU:

  • cuda - NVIDIA CUDA (más común para GPUs de NVIDIA)
  • rocm - AMD ROCm (para GPUs de AMD)
  • musa - Moore Threads MUSA
  • cann - Huawei CANN
  • auto - Detección automática (predeterminado, puede no funcionar correctamente)
  • none - Solo CPU

Para GPUs de NVIDIA, siempre usa explícitamente --gpu cuda.

Paso 3: Verificar el acceso a GPU

Después de la instalación, verifica que Docker Model Runner pueda acceder a tu GPU.

Verificar el acceso a GPU desde el contenedor del runner

Prueba el acceso a GPU desde dentro del contenedor de Docker Model Runner:

docker exec docker-model-runner nvidia-smi

Esto debería mostrar información de tu GPU, confirmando que el contenedor tiene acceso a GPU.

Verificar el estado del runner

Verifica que Docker Model Runner esté en ejecución:

docker model status

Deberías ver que el runner está activo con soporte de llama.cpp.

Paso 4: Probar un modelo con GPU

Ejecuta un modelo y verifica que esté usando la GPU.

Ejecutar un modelo

Inicia una inferencia de modelo:

docker model run ai/qwen3:14B-Q6_K "¿quién eres?"

Verificar el uso de GPU en los registros

Verifica los registros de Docker Model Runner para confirmar el uso de GPU:

docker model logs | grep -i cuda

Deberías ver mensajes indicando el uso de GPU:

  • using device CUDA0 (NVIDIA GeForce RTX 4080) - dispositivo de GPU detectado
  • offloaded 41/41 layers to GPU - capas del modelo cargadas en GPU
  • CUDA0 model buffer size = 10946.13 MiB - asignación de memoria en GPU
  • CUDA0 KV buffer size = 640.00 MiB - caché de clave-valor en GPU
  • CUDA0 compute buffer size = 306.75 MiB - búfer de cálculo en GPU

Monitorear el uso de GPU

En otro terminal, monitorea el uso de GPU en tiempo real:

nvidia-smi -l 1

Deberías ver un aumento en el uso de memoria y la utilización de GPU cuando el modelo esté en ejecución.

Para más opciones avanzadas de monitoreo de GPU y herramientas, consulta nuestra guía sobre aplicaciones de monitoreo de GPU en Linux / Ubuntu.

Solución de problemas

El modelo aún está usando CPU

Si el modelo aún está ejecutándose en CPU:

  1. Verificar la configuración del demonio de Docker:

    docker info | grep -i runtime

    Debería mostrar Default Runtime: nvidia

  2. Verificar el runtime del contenedor del runner:

    docker inspect docker-model-runner | grep -A 2 '"Runtime"'

    Debería mostrar "Runtime": "nvidia"

  3. Reinstalar el runner con soporte de GPU:

    docker model reinstall-runner --gpu cuda

  4. Verificar los registros para errores:

    docker model logs | tail -50

GPU no detectada

Si la GPU no se detecta:

  1. Verificar que el NVIDIA Container Toolkit esté instalado:

    dpkg -l | grep nvidia-container-toolkit

  2. Probar el acceso a GPU con Docker estándar:

    docker run --rm --gpus all nvidia/cuda:12.2.2-base-ubi8 nvidia-smi

    Para solucionar problemas con Docker, consulta nuestra Guía de atajos de Docker.

  3. Verificar los controladores de NVIDIA:

    nvidia-smi

Problemas de rendimiento

Si el rendimiento de la GPU es pobre:

  1. Verificar la utilización de GPU:

    nvidia-smi

    Busca un alto porcentaje de utilización de GPU

  2. Verificar que las capas del modelo estén en GPU:

    docker model logs | grep "offloaded.*layers to GPU"

    Todas las capas deben transferirse a GPU

  3. Verificar problemas de memoria:

    nvidia-smi

    Asegúrate de que la memoria de GPU no esté agotada

Buenas prácticas

  1. Siempre especifique explícitamente el backend de GPU: Use --gpu cuda en lugar de --gpu auto para GPUs de NVIDIA para asegurar la configuración correcta.

  2. Verificar la configuración después de los cambios: Siempre revise docker info | grep -i runtime después de modificar la configuración del demonio de Docker.

  3. Monitorear el uso de GPU: Use nvidia-smi para monitorear la memoria y la utilización de GPU durante la inferencia del modelo. Para herramientas de monitoreo avanzadas, consulte nuestra guía sobre aplicaciones de monitoreo de GPU en Linux / Ubuntu.

  4. Revisar los registros regularmente: Revisa docker model logs para asegurarte de que los modelos estén usando la aceleración de GPU.

  5. Usar tamaños de modelos adecuados: Asegúrate de que tu GPU tenga suficiente memoria para el modelo. Usa modelos cuantizados (Q4, Q5, Q6, Q8) para una mayor eficiencia de memoria en GPU. Para ayuda al elegir la GPU adecuada para tus cargas de trabajo de IA, consulta nuestra guía sobre Comparación de especificaciones de GPU de NVidia para IA.

Enlaces útiles