Apostila do Docker Model Runner: 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. Esta lista de comandos essenciais fornece uma referência rápida para todos os comandos, configurações e melhores práticas.

Para uma comparação mais ampla do Docker Model Runner com Ollama, vLLM, LocalAI e provedores de nuvem — incluindo compensações de custos e infraestrutura — veja Hospedagem de LLM: Infraestrutura Local, Autohospedada e em Nuvem Comparadas.

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 Settings → aba AI
  3. Clique em Enable 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 permitir que LLMs rodem na GPU em vez de 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

então você pode executar containers com --gpus all

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

verifique se o container pode ver a 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, o docker model run não suporta as flags --gpus ou -e. Em vez disso, você precisa:

  1. Configurar o daemon 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 este 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 "path" na configuração JSON de acordo.

Reinicie o Docker:

sudo systemctl restart docker

Verifique a configuração:

docker info | grep -i runtime

Você deve ver Default Runtime: 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 GPU CUDA
docker model reinstall-runner --gpu cuda

Isso 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 container 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 "who are you?"

Verifique os logs para confirmação da GPU:

docker model logs | grep -i cuda

Você deve ver mensagens como:

  • using device CUDA0 (NVIDIA GeForce RTX 4080)
  • offloaded 41/41 layers to GPU
  • CUDA0 model buffer size = 10946.13 MiB

Nota: Se você já instalou o Docker Model Runner sem suporte a GPU, deve reinstalá-lo com a flag --gpu cuda. Apenas configurar o daemon Docker não é suficiente — o container do runner em si precisa ser a versão habilitada para CUDA.

Backends de GPU disponíveis:

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

Comandos Principais

Baixando Modelos

Baixe modelos pré-empacotados do Docker Hub:

# Pull básico
docker model pull ai/llama2

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

# Pull de registry personalizado
docker model pull myregistry.com/models/mistral:latest

# Listar 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 "What is Docker?"

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

no geral, não temos muitas opções para executar modelos via CLI:

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

Run a model and interact with it using a submitted prompt or chat mode

Options:
      --color string                  Use colored output (auto|yes|no) (default "auto")
      --debug                         Enable debug logging
  -d, --detach                        Load the model in the background without interaction
      --ignore-runtime-memory-check   Do not block pull if estimated runtime memory for model exceeds system resources.

Listando Modelos

Veja modelos baixados e em execução:

# Listar todos os modelos baixados
docker model ls

# Listar modelos em execução
docker model ps

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

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

# Retornará apenas hashcodes
docker model ls -q

Removendo Modelos

Delete modelos do armazenamento local:

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

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

# Remover modelos não utilizados
docker model prune

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

Configurando Tamanhos de Contexto de Modelo

Não podemos usar a CLI para especificar o tamanho de contexto para uma solicitação particular.

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

  1. Empacotar o modelo nós mesmos, especificando o tamanho de contexto hardcoded desejado (Veja mais sobre isso na próxima seção.)

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

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

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

  1. No arquivo docker-compose.yaml, mas não podemos usar a imagem docker-model-runner dessa maneira, 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, veja o post dedicado sobre isso: Especificando tamanho de contexto no DMR

Empacotando Modelos Personalizados

Criar Artefato OCI de GGUF

Empacote seus próprios modelos GGUF:

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

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

# Empacotar e empurrar em um comando
docker model package --gguf /path/to/model.gguf --push myorg/mymodel:latest

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

Publicando Modelos

Empurre modelos para registries:

# Login no Docker Hub
docker login

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

# Push para registry privado
docker login myregistry.com
docker model push myregistry.com/models/mymodel:latest

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

Uso da API

Endpoints Compatíveis com OpenAI

O Docker Model Runner expõe automaticamente APIs compatíveis com OpenAI:

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

# Chat completion
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

# Geração de texto
curl http://localhost:8080/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "prompt": "Once upon a time",
    "max_tokens": 100
  }'

# Resposta em streaming
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Tell me a story"}],
    "stream": true
  }'

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

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

Configuração 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 Multi-Modelo

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 avançadas do Docker Compose e comandos, veja nosso Colocador de Comandos Docker Compose que cobre rede, 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

# Tokens máximos
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

# Habilitar log detalhado
MODEL_VERBOSE=true

# Chave de 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 e usa automaticamente GPUs disponíveis:

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

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

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

Force inferência via CPU quando GPU estiver disponível:

docker model run --no-gpu ai/llama2

Paralelismo de Tensor Multi-GPU

Distribua modelos grandes entre GPUs:

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

Inspeção e Depuração

Ver Detalhes do Modelo

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

# Ver camadas do modelo
docker model history ai/llama2

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

Logs e Monitoramento

# Ver logs do modelo
docker model logs llm

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

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

# Ver logs com carimbos de tempo
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 em formato JSON
docker model stats --format json

Rede

Expondo APIs

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

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

# Vincular a 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

# Criar rede personalizada
docker network create llm-network

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

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

Segurança

Controle de Acesso

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

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

# Login no registry privado
docker login myregistry.com -u username -p password

# Pull de registry privado
docker model pull myregistry.com/private/model:latest

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

Melhores 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

# Verificar variantes do modelo
docker search ai/llama2

Gerenciamento de Recursos

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

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

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

Verificações de Saúde

# Executar 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 containers do Docker Model Runner podem ser orquestrados usando manifests padrão do Kubernetes. Defina implantações com limites de recursos, autoescalabilidade e balanceamento de carga. Para referência abrangente de comandos Kubernetes e padrões de implantação, verifique nosso Colocador de Comandos Kubernetes.

# Exemplo: Implantar no cluster Kubernetes
kubectl apply -f llm-deployment.yaml

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

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

Solução de Problemas

Problemas Comuns

Modelo não inicia:

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

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

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

Erros de falta de memória:

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

# Reduzir tamanho de contexto
docker model run -e MODEL_CONTEXT=2048 ai/llama2

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

Inferência lenta:

# Verificar uso de GPU
docker model stats llm

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

# Aumentar camadas de 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

# Limpar recursos não utilizados
docker model system prune

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

Exemplos de Integração

Integração Python

import openai

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

# Chat completion
response = client.chat.completions.create(
    model="llama2",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

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

# Streaming
stream = client.chat.completions.create(
    model="llama2",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)

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

Script Bash

#!/bin/bash

# Iniciar modelo se não estiver rodando
if ! docker model ps | grep -q "llm"; then
    docker model run -d --name llm -p 8080:8080 ai/llama2
    echo "Waiting for model to start..."
    sleep 10
fi

# Fazer chamada de 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 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('What is Docker Model Runner?');
console.log(response);

Para ver como o Docker Model Runner se encaixa com Ollama, vLLM, LocalAI e provedores de nuvem, verifique nosso guia Hospedagem de LLM: Infraestrutura Local, Autohospedada e em Nuvem Comparadas.

Documentação Oficial

Artigos Relacionados

Assinar

Receba novos artigos sobre sistemas, infraestrutura e engenharia de IA.