Docker Model Runner Cheatsheet: 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.

Para una comparación más amplia de Docker Model Runner con Ollama, vLLM, LocalAI y proveedores en la nube, incluyendo análisis de costos y trade-offs de infraestructura, vea Almacenamiento de LLM: Comparación entre infraestructura local, autoalojada y en la nube.

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 de IA
  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 LLMs 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 de 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 donde 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 en consecuencia.

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 obtendrá la versión habilitada para CUDA (docker/model-runner:latest-cuda) en lugar de la versión solo 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 GPU:

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

Revise los registros para confirmar el uso de GPU:

docker model logs | grep -i cuda

Debería ver mensajes como:

  • usando dispositivo CUDA0 (NVIDIA GeForce RTX 4080)
  • desplazado 41/41 capas a GPU
  • tamaño del búfer de modelo 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 (predeterminado)
  • none - Solo CPU

Comandos principales

Descargar modelos

Descargue modelos preempaquetados desde Docker Hub:

# Descarga básica
docker model pull ai/llama2

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

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

# Listar 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 al ejecutar modelos desde la 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 para el modelo excede los recursos del sistema.

Listar modelos

Ver modelos descargados y en ejecución:

# Listar todos los modelos descargados
docker model ls

# Listar modelos en ejecución
docker model ps

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

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

# Devolverá hashes
docker model ls -q

Eliminar modelos

Eliminar modelos del almacenamiento local:

# Eliminar modelo específico
docker model rm ai/llama2

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

# Eliminar modelos no utilizados
docker model prune

# Eliminar 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 formas:

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

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

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

Luego puede llamar a curl, 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 se le pasa al modelo un tamaño de contexto codificado de forma rígida de 4096
...
models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240
...

Para más detalles, vea 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

Subir 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

# Completació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 mediante 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 con 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 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 está disponible GPU:

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 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 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 API key
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 falta de memoria:

# Usar 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

# Asegurar que se esté usando 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
)

# Completació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 llamada a 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);

Para ver cómo se ajusta Docker Model Runner con Ollama, vLLM, LocalAI y proveedores en la nube, consulte nuestra Almacenamiento de LLM: Comparación entre infraestructura local, autoalojada y en la nube guía.

Enlaces útiles

Documentación oficial

Artículos relacionados