Docker Model Runner Guía Rápida: Comandos y Ejemplos

Referencia rápida para comandos de Docker Model Runner

Docker Model Runner (DMR) es la solución oficial de Docker para ejecutar modelos de IA localmente, introducida en abril de 2025. Esta guía rápida proporciona una referencia rápida para todos los comandos esenciales, configuraciones y mejores prácticas.

lista de modelos gemma disponibles en docker model runner

Instalación

Docker Desktop

Habilite Docker Model Runner a través de la interfaz gráfica:

  1. Abra Docker Desktop
  2. Vaya a Configuración → pestaña AI
  3. Haga clic en Habilitar Docker Model Runner
  4. Reinicie Docker Desktop

/home/rg/prj/hugo-pers/content/post/2025/10/docker-model-runner-cheatsheet/docker-model-runner_w678.jpg ventanas de docker model runner

Docker Engine (Linux)

Instale el paquete del plugin:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install docker-model-plugin

# Fedora/RHEL
sudo dnf install docker-model-plugin

# Arch Linux
sudo pacman -S docker-model-plugin

Verifique la instalación:

docker model --help

Soporte NVIDIA RTX para Docker

Para habilitar la ejecución de LLM en GPU en lugar de CPU, instale nvidia-container-toolkit:

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
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
sudo systemctl restart docker

luego puede ejecutar contenedores con --gpus all

docker run --rm --gpus all <image> <command>

verifique que el contenedor pueda ver la GPU:

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

Agregar soporte NVidia para Docker Model Runner

Docker Model Runner requiere una configuración explícita de GPU. A diferencia de los comandos estándar docker run, docker model run no admite las banderas --gpus o -e. En su lugar, debe:

  1. Configurar el demonio de Docker para usar el runtime de NVIDIA por defecto

Primero, verifique dónde se instaló nvidia-container-runtime:

which nvidia-container-runtime

Esto generalmente devolverá /usr/bin/nvidia-container-runtime. Use esta ruta en la configuración a continuación.

Cree o actualice /etc/docker/daemon.json:

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

Nota: Si which nvidia-container-runtime devuelve una ruta diferente, actualice el valor de "path" en la configuración JSON según corresponda.

Reinicie Docker:

sudo systemctl restart docker

Verifique la configuración:

docker info | grep -i runtime

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

  1. Reinstale Docker Model Runner con soporte de GPU

Docker Model Runner debe instalarse/reinstalarse con soporte de GPU explícito:

# Detenga el runner actual
docker model stop-runner

# Reinstale con soporte de CUDA
docker model reinstall-runner --gpu cuda

Esto hará que se descargue la versión habilitada para CUDA (docker/model-runner:latest-cuda) en lugar de la versión solo para CPU.

  1. Verifique el acceso a la GPU

Verifique que el contenedor de Docker Model Runner pueda acceder a la GPU:

docker exec docker-model-runner nvidia-smi
  1. Pruebe un modelo con GPU

Ejecute un modelo y revise los registros para confirmar el uso de la GPU:

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

Revise los registros para confirmar el uso de la GPU:

docker model logs | grep -i cuda

Debería ver mensajes como:

  • usando dispositivo CUDA0 (NVIDIA GeForce RTX 4080)
  • descargado 41/41 capas a la GPU
  • tamaño del búfer de la GPU CUDA0 = 10946,13 MiB

Nota: Si ya instaló Docker Model Runner sin soporte de GPU, debe 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:

  • cuda - NVIDIA CUDA (más común)
  • rocm - AMD ROCm
  • musa - Moore Threads MUSA
  • cann - Huawei CANN
  • auto - Detección automática (por defecto)
  • none - Solo CPU

Comandos principales

Descargar modelos

Descargue modelos preempaquetados desde Docker Hub:

# Descarga básica
docker model pull ai/llama2

# Descarga una versión específica
docker model pull ai/llama2:7b-q4

# Descarga desde un registro personalizado
docker model pull myregistry.com/models/mistral:latest

# Liste los modelos disponibles en un espacio de nombres
docker search ai/

Ejecutar modelos

Inicie un modelo con servicio de API automático:

# Ejecución básica (interactiva)
docker model run ai/llama2 "¿qué es Docker?"

# Ejecutar como servicio (en segundo plano)
docker model run -d

en general, no tenemos muchas opciones para ejecutar modelos a través de CLI:

docker model run --help
Uso:  docker model run MODEL [PROMPT]

Ejecute un modelo e interactúe con él usando un prompt presentado o modo de chat

Opciones:
      --color string                  Usar salida con colores (auto|yes|no) (por defecto "auto")
      --debug                         Habilitar registro de depuración
  -d, --detach                        Cargue el modelo en segundo plano sin interacción
      --ignore-runtime-memory-check   No bloquee la descarga si la memoria estimada del modelo excede los recursos del sistema.

Listar modelos

Ver modelos descargados y en ejecución:

# Liste todos los modelos descargados
docker model ls

# Liste modelos en ejecución
docker model ps

# Liste con información detallada
docker model ls --json

# Liste con información detallada
docker model ls --openai

# Devolverá hashes
docker model ls -q

Eliminar modelos

Elimine modelos del almacenamiento local:

# Elimine un modelo específico
docker model rm ai/llama2

# Elimine con fuerza (incluso si está en ejecución)
docker model rm -f ai/llama2

# Elimine modelos no utilizados
docker model prune

# Elimine todos los modelos
docker model rm $(docker model ls -q)

Configuración de tamaños de contexto del modelo

No podemos usar la CLI para especificar el tamaño de contexto para una solicitud específica.

Básicamente, solo podemos controlar el tamaño de contexto del modelo de tres maneras:

  1. Empaquetar el modelo nosotros mismos, especificando el tamaño de contexto codificado en el modelo (ver más sobre esto en la siguiente sección.)

  2. Cuando use el comando de configuración de Docker Model Runner, configure el parámetro --context-size como:

docker model configure --context-size=10000 ai/gemma3-qat:4B

Luego puede llamar a curl a él, pero no puede hacer docker model run... - este ignorará la configuración.

  1. En el archivo docker-compose.yaml, pero no podemos usar la imagen docker-model-runner de esta manera, porque pasa al modelo un tamaño de contexto codificado en el modelo de 4096
...
models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240
...

Para más detalles, consulte el post dedicado sobre esto: Especificar el tamaño de contexto en DMR

Empaquetar modelos personalizados

Crear un artefacto OCI desde GGUF

Empaquete sus propios modelos GGUF:

# Empaquetado básico
docker model package --gguf /path/to/model.gguf myorg/mymodel:latest

# Empaquetar con metadatos
docker model package \
  --gguf /path/to/model.gguf \
  --label "description=Modelo personalizado de Llama" \
  --label "version=1.0" \
  myorg/mymodel:v1.0

# Empaquetar y subir en un solo comando
docker model package --gguf /path/to/model.gguf --push myorg/mymodel:latest

# Empaquetar con tamaño de contexto personalizado
docker model package \
  --gguf /path/to/model.gguf \
  --context 8192 \
  myorg/mymodel:latest

Publicar modelos

Suba modelos a registros:

# Iniciar sesión en Docker Hub
docker login

# Subir a Docker Hub
docker model push myorg/mymodel:latest

# Subir a registro privado
docker login myregistry.com
docker model push myregistry.com/models/mymodel:latest

# Etiquetar y subir
docker model tag mymodel:latest myorg/mymodel:v1.0
docker model push myorg/mymodel:v1.0

Uso de API

Puntos finales compatibles con OpenAI

Docker Model Runner expone automáticamente puntos finales compatibles con OpenAI:

# Iniciar modelo con API
docker model run -d -p 8080:8080 --name llm ai/llama2

# Completión de chat
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "¡Hola!"}]
  }'

# Generación de texto
curl http://localhost:8080/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "prompt": "Había una vez",
    "max_tokens": 100
  }'

# Respuesta en streaming
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Cuéntame una historia"}],
    "stream": true
  }'

# Listar modelos disponibles a través de API
curl http://localhost:8080/v1/models

# Información del modelo
curl http://localhost:8080/v1/models/llama2

Configuración de Docker Compose

Archivo Compose básico

version: '3.8'

services:
  llm:
    image: docker-model-runner
    model: ai/llama2:7b-q4
    ports:
      - "8080:8080"
    environment:
      - MODEL_TEMPERATURE=0.7
    volumes:
      - docker-model-runner-models:/models
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  docker-model-runner-models:
    external: true

Configuración de múltiples modelos

version: '3.8'

services:
  llama:
    image: docker-model-runner
    model: ai/llama2
    ports:
      - "8080:8080"
    
  mistral:
    image: docker-model-runner
    model: ai/mistral
    ports:
      - "8081:8080"
    
  embedding:
    image: docker-model-runner
    model: ai/nomic-embed-text
    ports:
      - "8082:8080"

Para configuraciones y comandos avanzados de Docker Compose, consulte nuestra Guía rápida de Docker Compose que cubre redes, volúmenes y patrones de orquestación.

Variables de entorno

Configure el comportamiento del modelo con variables de entorno:

# Temperatura (0.0-1.0)
MODEL_TEMPERATURE=0.7

# Muestreo top-p
MODEL_TOP_P=0.9

# Muestreo top-k
MODEL_TOP_K=40

# Máximo de tokens
MODEL_MAX_TOKENS=2048

# Número de capas de GPU
MODEL_GPU_LAYERS=35

# Tamaño de lote
MODEL_BATCH_SIZE=512

# Cantidad de hilos (CPU)
MODEL_THREADS=8

# Habilitar registro detallado
MODEL_VERBOSE=true

# Clave API para autenticación
MODEL_API_KEY=your-secret-key

Ejecute con variables de entorno:

docker model run \
  -e MODEL_TEMPERATURE=0.8 \
  -e MODEL_API_KEY=secret123 \
  ai/llama2

Configuración de GPU

Detección automática de GPU

DMR detecta automáticamente y usa las GPUs disponibles:

# Usar todas las GPUs
docker model run --gpus all ai/llama2

# Usar una GPU específica
docker model run --gpus 0 ai/llama2

# Usar múltiples GPUs específicas
docker model run --gpus 0,1,2 ai/llama2

# GPU con límite de memoria
docker model run --gpus all --memory 16g ai/llama2

Modo solo CPU

Forzar la inferencia en CPU cuando la GPU está disponible:

docker model run --no-gpu ai/llama2

Paralelismo de tensores en múltiples GPUs

Distribuir modelos grandes entre GPUs:

docker model run \
  --gpus all \
  --tensor-parallel 2 \
  ai/llama2-70b

Inspección y depuración

Ver detalles del modelo

# Inspeccionar configuración del modelo
docker model inspect ai/llama2

# Ver capas del modelo
docker model history ai/llama2

# Ver tamaño del modelo y metadatos
docker model inspect --format='{{.Size}}' ai/llama2

Registros y monitoreo

# Ver registros del modelo
docker model logs llm

# Seguir registros en tiempo real
docker model logs -f llm

# Ver últimas 100 líneas
docker model logs --tail 100 llm

# Ver registros con marcas de tiempo
docker model logs -t llm

Estadísticas de rendimiento

# Uso de recursos
docker model stats

# Estadísticas de un modelo específico
docker model stats llm

# Estadísticas en formato JSON
docker model stats --format json

Redes

Exponer APIs

# Puerto por defecto (8080)
docker model run -p 8080:8080 ai/llama2

# Puerto personalizado
docker model run -p 3000:8080 ai/llama2

# Vincular a una interfaz específica
docker model run -p 127.0.0.1:8080:8080 ai/llama2

# Múltiples puertos
docker model run -p 8080:8080 -p 9090:9090 ai/llama2

Configuración de red

# Crear red personalizada
docker network create llm-network

# Ejecutar modelo en red personalizada
docker model run --network llm-network --name llm ai/llama2

# Conectar a red existente
docker model run --network host ai/llama2

Seguridad

Control de acceso

# Ejecutar con autenticación de clave API
docker model run \
  -e MODEL_API_KEY=my-secret-key \
  ai/llama2

# Usar con autenticación
curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer my-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama2", "messages": [...]}'

Autenticación en registros

# Iniciar sesión en registro privado
docker login myregistry.com -u username -p password

# Descargar desde registro privado
docker model pull myregistry.com/private/model:latest

# Usar helper de credenciales
docker login --password-stdin < token.txt

Mejores prácticas

Selección de modelos

# Usar modelos cuantizados para inferencia más rápida
docker model pull ai/llama2:7b-q4     # cuantización de 4 bits
docker model pull ai/llama2:7b-q5     # cuantización de 5 bits
docker model pull ai/llama2:7b-q8     # cuantización de 8 bits

# Ver variantes del modelo
docker search ai/llama2

Gestión de recursos

# Establecer límites de memoria
docker model run --memory 8g --memory-swap 16g ai/llama2

# Establecer límites de CPU
docker model run --cpus 4 ai/llama2

# Limitar memoria de GPU
docker model run --gpus all --gpu-memory 8g ai/llama2

Verificaciones de salud

# Ejecutar con verificación de salud
docker model run \
  --health-cmd "curl -f http://localhost:8080/health || exit 1" \
  --health-interval 30s \
  --health-timeout 10s \
  --health-retries 3 \
  ai/llama2

Orquestación en producción

Para despliegues en producción con Kubernetes, los contenedores de Docker Model Runner pueden orquestarse usando manifiestos estándar de Kubernetes. Defina despliegues con límites de recursos, autoscaling y balanceo de carga. Para una referencia completa de comandos de Kubernetes y patrones de despliegue, consulte nuestra Guía rápida de Kubernetes.

# Ejemplo: Desplegar en clúster de Kubernetes
kubectl apply -f llm-deployment.yaml

# Escalar despliegue
kubectl scale deployment llm --replicas=3

# Exponer como servicio
kubectl expose deployment llm --type=LoadBalancer --port=8080

Solución de problemas

Problemas comunes

El modelo no inicia:

# Verificar espacio en disco disponible
df -h

# Ver registros de error detallados
docker model logs --tail 50 llm

# Verificar disponibilidad de GPU
nvidia-smi  # Para GPUs NVIDIA

Errores de memoria insuficiente:

# Usar un modelo cuantizado más pequeño
docker model pull ai/llama2:7b-q4

# Reducir tamaño de contexto
docker model run -e MODEL_CONTEXT=2048 ai/llama2

# Limitar tamaño de lote
docker model run -e MODEL_BATCH_SIZE=256 ai/llama2

Inferencia lenta:

# Ver uso de GPU
docker model stats llm

# Asegurarse de que se esté usando la GPU
docker model logs llm | grep -i gpu

# Aumentar capas de GPU
docker model run -e MODEL_GPU_LAYERS=40 ai/llama2

Comandos de diagnóstico

# Información del sistema
docker model system info

# Uso de disco
docker model system df

# Limpiar recursos no utilizados
docker model system prune

# Limpieza completa (eliminar todos los modelos)
docker model system prune -a

Ejemplos de integración

Integración con Python

import openai

# Configurar cliente para Docker Model Runner
client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"  # DMR no requiere clave por defecto
)

# Completión de chat
response = client.chat.completions.create(
    model="llama2",
    messages=[
        {"role": "user", "content": "¡Hola!"}
    ]
)

print(response.choices[0].message.content)

# Streaming
stream = client.chat.completions.create(
    model="llama2",
    messages=[{"role": "user", "content": "Cuéntame una historia"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Script de Bash

#!/bin/bash

# Iniciar modelo si no está en ejecución
if ! docker model ps | grep -q "llm"; then
    docker model run -d --name llm -p 8080:8080 ai/llama2
    echo "Esperando a que el modelo inicie..."
    sleep 10
fi

# Hacer una llamada API
curl -s http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "'"$1"'"}]
  }' | jq -r '.choices[0].message.content'

Integración con Node.js

import OpenAI from 'openai';

const client = new OpenAI({
    baseURL: 'http://localhost:8080/v1',
    apiKey: 'not-needed'
});

async function chat(message) {
    const completion = await client.chat.completions.create({
        model: 'llama2',
        messages: [{ role: 'user', content: message }]
    });
    
    return completion.choices[0].message.content;
}

// Uso
const response = await chat('¿Qué es Docker Model Runner?');
console.log(response);

Enlaces útiles

Documentación oficial

Guías rápidas relacionadas

Artículos de comparación