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 → AI (tabulación)
  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

Comandos Principales

Descargar Modelos

Descargue modelos preempaquetados desde Docker Hub:

# Descarga básica
docker model pull ai/llama2

# Descarga de 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

# Lista de 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 --name my-llm ai/llama2

# Ejecutar con puerto personalizado
docker model run -p 8080:8080 ai/llama2

# Ejecutar con especificación de GPU
docker model run --gpus 0,1 ai/llama2

# Ejecutar con límite de memoria
docker model run --memory 8g ai/llama2

# Ejecutar con variables de entorno
docker model run -e MODEL_CONTEXT=4096 ai/llama2

# Ejecutar con montaje de volumen para datos persistentes
docker model run -v model-data:/data ai/llama2

Listar Modelos

Ver los modelos descargados y en ejecución:

# Lista de todos los modelos descargados
docker model ls

# Lista de modelos en ejecución
docker model ps

# Lista con información detallada
docker model ls --all --format json

# Filtro por nombre
docker model ls --filter "name=llama"

Detener Modelos

Detenga instancias de modelos en ejecución:

# Detener un modelo específico
docker model stop my-llm

# Detener todos los modelos en ejecución
docker model stop $(docker model ps -q)

# Detener con tiempo de espera
docker model stop --time 30 my-llm

Eliminar Modelos

Elimine modelos del almacenamiento local:

# Eliminar un 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)

Empaquetar Modelos Personalizados

Crear un Artefacto OCI desde GGUF

Empaque sus propios modelos GGUF:

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

# Empaquetado 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 un 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 APIs 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
  }'

# Lista de 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_CONTEXT=4096
      - MODEL_TEMPERATURE=0.7
    volumes:
      - model-data:/root/.cache
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  model-data:

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:

# Tamaño de la ventana de contexto
MODEL_CONTEXT=4096

# 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_CONTEXT=8192 \
  -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 utiliza 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

Distribuya 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 mediante 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 un registro privado
docker login myregistry.com -u username -p password

# Descargar desde un 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 ser orquestados usando manifiestos estándar de Kubernetes. Defina despliegues con límites de recursos, escalado automático 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 un clúster de Kubernetes
kubectl apply -f llm-deployment.yaml

# Escalar el 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 el tamaño de contexto
docker model run -e MODEL_CONTEXT=2048 ai/llama2

# Limitar el tamaño del 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 el número de 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 una llamada a la 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