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. Esta folha de dicas 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çõesGuia 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

Comandos Principais

Puxar 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

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

Executar Modelos

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

# Executar básico (interativo)
docker model run ai/llama2 "O que é Docker?"

# Executar como serviço (em segundo plano)
docker model run -d --name my-llm ai/llama2

# Executar com porta personalizada
docker model run -p 8080:8080 ai/llama2

# Executar com especificação de GPU
docker model run --gpus 0,1 ai/llama2

# Executar com limite de memória
docker model run --memory 8g ai/llama2

# Executar com variáveis de ambiente
docker model run -e MODEL_CONTEXT=4096 ai/llama2

# Executar com montagem de volume para dados persistentes
docker model run -v model-data:/data ai/llama2

Listar Modelos

Visualize 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 --all --format json

# Filtrar por nome
docker model ls --filter "name=llama"

Parar Modelos

Pare instâncias de modelos em execução:

# Parar modelo específico
docker model stop my-llm

# Parar todos os modelos em execução
docker model stop $(docker model ps -q)

# Parar com timeout
docker model stop --time 30 my-llm

Remover Modelos

Exclua modelos do armazenamento local:

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

# Remover com força (mesmo que esteja 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)

Empacotar Modelos Personalizados

Criar 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

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

# Empacotar e enviar em um único 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

Publicar 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

# Etiquetar e enviar
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 APIs compatíveis com OpenAI:

# Iniciar 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",
    "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
  }'

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

volumes:
  model-data:

Configuração com 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, veja 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:

# Tamanho da janela de contexto
MODEL_CONTEXT=4096

# 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 da GPU
MODEL_GPU_LAYERS=35

# Tamanho do lote
MODEL_BATCH_SIZE=512

# Contagem de threads (CPU)
MODEL_THREADS=8

# Habilitar logs detalhados
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_CONTEXT=8192 \
  -e MODEL_TEMPERATURE=0.8 \
  -e MODEL_API_KEY=secret123 \
  ai/llama2

Configuração da GPU

Detecção Automática da GPU

O DMR detecta automaticamente e usa 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

Forçar inferência em CPU mesmo quando a GPU estiver disponível:

docker model run --no-gpu ai/llama2

Paralelismo de Tensores em Múltiplas GPUs

Distribuir modelos grandes entre GPUs:

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

Inspeção e Depuração

Visualizar Detalhes do Modelo

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

# Visualizar camadas do modelo
docker model history ai/llama2

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

Logs e Monitoramento

# Visualizar logs do modelo
docker model logs llm

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

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

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

Rede

Exposição de 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 por chave 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 no Registro

# Fazer login em registro privado
docker login myregistry.com -u username -p password

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

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

Boas Práticas

Seleção de Modelos

# 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 da GPU
docker model run --gpus all --gpu-memory 8g ai/llama2

Verificação 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 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: Implantar em 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

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

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

Erros de memória insuficiente:

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

# Reduzir tamanho do 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 da GPU
docker model stats llm

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

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

# 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 com Python

import openai

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

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

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