Docker Model Runner Cheatsheet: Comandos e Exemplos

Referência rápida para comandos do Docker Model Runner

Docker Model Runner (DMR) é a solução oficial do Docker para executar modelos de IA localmente, introduzida em abril de 2025. Este guia rápido fornece uma referência rápida para todos os comandos essenciais, configurações e melhores práticas.

lista de modelos gemma disponíveis no docker model runner

Instalação

Docker Desktop

Ative o Docker Model Runner através da interface gráfica:

  1. Abra o Docker Desktop
  2. Vá para Configurações → Guia AI
  3. Clique em Ativar Docker Model Runner
  4. Reinicie o Docker Desktop

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

Docker Engine (Linux)

Instale o pacote do 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 a instalação:

docker model --help

Suporte NVIDIA RTX para Docker

Para habilitar a execução de LLMs no GPU em vez do CPU, instale o 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

em seguida, você pode executar contêineres com --gpus all

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

verifique se o contêiner pode ver o GPU:

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

Adicionando Suporte NVidia para Docker Model Runner

O Docker Model Runner requer configuração explícita de GPU. Diferente dos comandos padrão docker run, docker model run não suporta --gpus ou -e flags. Em vez disso, você precisa:

  1. Configurar o daemon do Docker para usar o runtime NVIDIA por padrão

Primeiro, verifique onde o nvidia-container-runtime está instalado:

which nvidia-container-runtime

Isso normalmente retornará /usr/bin/nvidia-container-runtime. Use esse caminho na configuração abaixo.

Crie ou atualize /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: Se which nvidia-container-runtime retornar um caminho diferente, atualize o valor de "path" na configuração JSON conforme necessário.

Reinicie o Docker:

sudo systemctl restart docker

Verifique a configuração:

docker info | grep -i runtime

Você deve ver Runtime Padrão: nvidia na saída.

  1. Reinstale o Docker Model Runner com suporte a GPU

O Docker Model Runner deve ser instalado/reinstalado com suporte explícito a GPU:

# Pare o runner atual
docker model stop-runner

# Reinstale com suporte a CUDA
docker model reinstall-runner --gpu cuda

Isso irá puxar a versão habilitada para CUDA (docker/model-runner:latest-cuda) em vez da versão apenas para CPU.

  1. Verifique o acesso à GPU

Verifique se o contêiner Docker Model Runner pode acessar a GPU:

docker exec docker-model-runner nvidia-smi
  1. Teste o modelo com GPU

Execute um modelo e verifique os logs para confirmar o uso da GPU:

docker model run ai/qwen3:14B-Q6_K "quem é você?"

Verifique os logs para confirmação da GPU:

docker model logs | grep -i cuda

Você deve ver mensagens como:

  • usando o dispositivo CUDA0 (NVIDIA GeForce RTX 4080)
  • desembarcado 41/41 camadas para GPU
  • tamanho do buffer da GPU CUDA0 = 10946,13 MiB

Nota: Se você já instalou o Docker Model Runner sem suporte a GPU, você deve reinstalá-lo com a bandeira --gpu cuda. Apenas configurar o daemon do Docker não é suficiente - o próprio contêiner do runner precisa ser a versão habilitada para CUDA.

Backends de GPU disponíveis:

  • cuda - NVIDIA CUDA (mais comum)
  • rocm - AMD ROCm
  • musa - Moore Threads MUSA
  • cann - Huawei CANN
  • auto - Detecção automática (padrão)
  • none - Apenas CPU

Comandos Principais

Puxando Modelos

Puxe modelos pré-embalados do Docker Hub:

# Puxar básico
docker model pull ai/llama2

# Puxar versão específica
docker model pull ai/llama2:7b-q4

# Puxar de registro personalizado
docker model pull myregistry.com/models/mistral:latest

# Liste modelos disponíveis em um namespace
docker search ai/

Executando Modelos

Inicie um modelo com serviço de API automático:

# Execução básica (interativa)
docker model run ai/llama2 "O que é Docker?"

# Execute como serviço (em segundo plano)
docker model run -d

overall não temos muitas opções para executar modelos via CLI:

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

Execute um modelo e interaja com ele usando um prompt submetido ou modo de chat

Opções:
      --color string                  Use saída colorida (auto|yes|no) (padrão "auto")
      --debug                         Ative o log de depuração
  -d, --detach                        Carregue o modelo em segundo plano sem interação
      --ignore-runtime-memory-check   Não bloqueie o pull se a memória estimada de tempo de execução do modelo exceder os recursos do sistema.

Listando Modelos

Visualize modelos baixados e em execução:

# Liste todos os modelos baixados
docker model ls

# Liste modelos em execução
docker model ps

# Liste com informações detalhadas
docker model ls --json

# Liste com informações detalhadas
docker model ls --openai

# Retornará hashes de código
docker model ls -q

Removendo Modelos

Exclua modelos do armazenamento local:

# Remova um modelo específico
docker model rm ai/llama2

# Remova com força (mesmo se estiver em execução)
docker model rm -f ai/llama2

# Remova modelos não utilizados
docker model prune

# Remova todos os modelos
docker model rm $(docker model ls -q)

Configurando Tamanhos de Contexto do Modelo

Não podemos usar o CLI para especificar o tamanho de contexto para uma solicitação específica.

Basicamente, podemos controlar o tamanho de contexto do modelo apenas de três maneiras:

  1. Empacote o modelo por conta própria, especificando o tamanho de contexto hardcoded desejado (Veja mais sobre isso na próxima seção.)

  2. Ao usar o docker model runner configure com o parâmetro –context-size, como:

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

Então você pode chamar curl para ele, mas não pode fazer docker model run... - esse ignorará a configuração.

  1. No arquivo docker-compose.yaml, mas não podemos usar a imagem docker-model-runner dessa forma, porque ela está passando para o modelo um tamanho de contexto hardcoded de 4096
...
models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240
...

Para mais detalhes, consulte o post dedicado sobre isso: Especificando o tamanho do contexto no DMR

Empacotando Modelos Personalizados

Crie um Artefato OCI a partir de GGUF

Empacote seus próprios modelos GGUF:

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

# Empacote com metadados
docker model package \
  --gguf /path/to/model.gguf \
  --label "description=Modelo personalizado Llama" \
  --label "version=1.0" \
  myorg/mymodel:v1.0

# Empacote e envie em um único comando
docker model package --gguf /path/to/model.gguf --push myorg/mymodel:latest

# Empacote com tamanho de contexto personalizado
docker model package \
  --gguf /path/to/model.gguf \
  --context 8192 \
  myorg/mymodel:latest

Publicando Modelos

Envie modelos para repositórios:

# Faça login no Docker Hub
docker login

# Envie para o Docker Hub
docker model push myorg/mymodel:latest

# Envie para repositório privado
docker login myregistry.com
docker model push myregistry.com/models/mymodel:latest

# Etique e envie
docker model tag mymodel:latest myorg/mymodel:v1.0
docker model push myorg/mymodel:v1.0

Uso da API

Pontos de Extremidade Compatíveis com OpenAI

O Docker Model Runner expõe automaticamente pontos de extremidade compatíveis com a API do OpenAI:

# Inicie o modelo com API
docker model run -d -p 8080:8080 --name llm ai/llama2

# Completão de chat
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Olá!"}]
  }'

# Geração de texto
curl http://localhost:8080/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "prompt": "Uma vez, havia um reino...",
    "max_tokens": 100
  }'

# Resposta de streaming
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Me conte uma história"}],
    "stream": true
  }'

# Liste modelos disponíveis via API
curl http://localhost:8080/v1/models

# Informações do modelo
curl http://localhost:8080/v1/models/llama2

Configuração do Docker Compose

Arquivo 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

Configuração de Múltiplos 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 configurações e comandos avançados do Docker Compose, consulte nossa Folha de Dicas do Docker Compose que abrange redes, volumes e padrões de orquestração.

Variáveis de Ambiente

Configure o comportamento do modelo com variáveis de ambiente:

# Temperatura (0.0-1.0)
MODEL_TEMPERATURE=0.7

# Amostragem Top-p
MODEL_TOP_P=0.9

# Amostragem Top-k
MODEL_TOP_K=40

# Máximo de tokens
MODEL_MAX_TOKENS=2048

# Número de camadas de GPU
MODEL_GPU_LAYERS=35

# Tamanho do lote
MODEL_BATCH_SIZE=512

# Contagem de threads (CPU)
MODEL_THREADS=8

# Ative o log detalhado
MODEL_VERBOSE=true

# Chave API para autenticação
MODEL_API_KEY=your-secret-key

Execute com variáveis de ambiente:

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

Configuração de GPU

Detecção Automática de GPU

O DMR detecta automaticamente e usa GPUs disponíveis:

# Use todas as GPUs
docker model run --gpus all ai/llama2

# Use uma GPU específica
docker model run --gpus 0 ai/llama2

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

# GPU com limite de memória
docker model run --gpus all --memory 16g ai/llama2

Modo Apenas CPU

Força a inferência em CPU mesmo quando GPU está disponível:

docker model run --no-gpu ai/llama2

Paralelismo de Tensores em Multi-GPU

Distribua modelos grandes entre GPUs:

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

Inspeção e Depuração

Visualize Detalhes do Modelo

# Inspeção da configuração do modelo
docker model inspect ai/llama2

# Visualize camadas do modelo
docker model history ai/llama2

# Verifique o tamanho do modelo e metadados
docker model inspect --format='{{.Size}}' ai/llama2

Logs e Monitoramento

# Visualize logs do modelo
docker model logs llm

# Siga logs em tempo real
docker model logs -f llm

# Visualize últimas 100 linhas
docker model logs --tail 100 llm

# Visualize logs com timestamps
docker model logs -t llm

Estatísticas de Desempenho

# Uso de recursos
docker model stats

# Estatísticas de modelo específico
docker model stats llm

# Estatísticas no formato JSON
docker model stats --format json

Redes

Expondo APIs

# Porta padrão (8080)
docker model run -p 8080:8080 ai/llama2

# Porta personalizada
docker model run -p 3000:8080 ai/llama2

# Vincule a uma interface específica
docker model run -p 127.0.0.1:8080:8080 ai/llama2

# Múltiplas portas
docker model run -p 8080:8080 -p 9090:9090 ai/llama2

Configuração de Rede

# Crie rede personalizada
docker network create llm-network

# Execute modelo em rede personalizada
docker model run --network llm-network --name llm ai/llama2

# Conecte-se a rede existente
docker model run --network host ai/llama2

Segurança

Controle de Acesso

# Execute com autenticação de chave API
docker model run \
  -e MODEL_API_KEY=my-secret-key \
  ai/llama2

# Use com autenticação
curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer my-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama2", "messages": [...]}'

Autenticação em Registro

# Faça login em registro privado
docker login myregistry.com -u username -p password

# Puxe de registro privado
docker model pull myregistry.com/private/model:latest

# Use helper de credenciais
docker login --password-stdin < token.txt

Boas Práticas

Seleção de Modelo

# Use modelos quantizados para inferência mais rápida
docker model pull ai/llama2:7b-q4     # Quantização de 4 bits
docker model pull ai/llama2:7b-q5     # Quantização de 5 bits
docker model pull ai/llama2:7b-q8     # Quantização de 8 bits

# Verifique variantes do modelo
docker search ai/llama2

Gerenciamento de Recursos

# Defina limites de memória
docker model run --memory 8g --memory-swap 16g ai/llama2

# Defina limites de CPU
docker model run --cpus 4 ai/llama2

# Limite memória de GPU
docker model run --gpus all --gpu-memory 8g ai/llama2

Verificação de Saúde

# Execute com verificação de saúde
docker model run \
  --health-cmd "curl -f http://localhost:8080/health || exit 1" \
  --health-interval 30s \
  --health-timeout 10s \
  --health-retries 3 \
  ai/llama2

Orquestração em Produção

Para implantações em produção com Kubernetes, os contêineres do Docker Model Runner podem ser orquestrados usando manifestos padrão do Kubernetes. Defina implantações com limites de recursos, autoscaling e balanceamento de carga. Para referência completa de comandos do Kubernetes e padrões de implantação, consulte nossa Folha de Dicas do Kubernetes.

# Exemplo: Implante em cluster Kubernetes
kubectl apply -f llm-deployment.yaml

# Escalamento da implantação
kubectl scale deployment llm --replicas=3

# Exponha como serviço
kubectl expose deployment llm --type=LoadBalancer --port=8080

Solução de Problemas

Problemas Comuns

O modelo não inicia:

# Verifique o espaço em disco disponível
df -h

# Visualize logs de erro detalhados
docker model logs --tail 50 llm

# Verifique disponibilidade de GPU
nvidia-smi  # Para GPUs NVIDIA

Erros de memória insuficiente:

# Use um modelo quantizado menor
docker model pull ai/llama2:7b-q4

# Reduza o tamanho do contexto
docker model run -e MODEL_CONTEXT=2048 ai/llama2

# Limite o tamanho do lote
docker model run -e MODEL_BATCH_SIZE=256 ai/llama2

Inferência lenta:

# Verifique o uso da GPU
docker model stats llm

# Certifique-se de que a GPU está sendo usada
docker model logs llm | grep -i gpu

# Aumente o número de camadas da GPU
docker model run -e MODEL_GPU_LAYERS=40 ai/llama2

Comandos de Diagnóstico

# Informações do sistema
docker model system info

# Uso de disco
docker model system df

# Limpe recursos não utilizados
docker model system prune

# Limpeza completa (remova todos os modelos)
docker model system prune -a

Exemplos de Integração

Integração com Python

import openai

# Configure cliente para Docker Model Runner
client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"  # O DMR não requer chave por padrão
)

# Completão de chat
response = client.chat.completions.create(
    model="llama2",
    messages=[
        {"role": "user", "content": "Olá!"}
    ]
)

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

# Streaming
stream = client.chat.completions.create(
    model="llama2",
    messages=[{"role": "user", "content": "Me conte uma história"}],
    stream=True
)

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

Script Bash

#!/bin/bash

# Inicie o modelo se não estiver em execução
if ! docker model ps | grep -q "llm"; then
    docker model run -d --name llm -p 8080:8080 ai/llama2
    echo "Aguardando o modelo iniciar..."
    sleep 10
fi

# Faça uma chamada 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'

Integração com 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('O que é Docker Model Runner?');
console.log(response);

Documentação Oficial

Folhas de Dicas Relacionadas

Artigos de Comparação