Docker Model Runner: IA Local sem dor de cabeça

Já imaginou poder rodar aqueles modelos de IA gigantes no seu computador tão facilmente quanto pedir um delivery de comida? Pois é isso que o Docker Model Runner faz! É como se fosse um Uber para modelos de IA: você "chama" o modelo, ele vem rapidinho, faz o trabalho e depois vai embora sem ocupar espaço quando você não precisa mais.

Lançado como beta no Docker Desktop 4.40, o Docker Model Runner é aquela novidade que faz você pensar: "Como vivíamos sem isso antes?". Se você já passou horas configurando ambientes para rodar IA localmente (aquele inferno de dependências que nunca termina), vai entender o porquê.

---

Conhecendo a ferramenta

Se você está começando agora e mal sabe a diferença entre um container e uma tupperware, relaxa! Vou explicar como se estivéssemos em um churrasco 🍗:

O Docker Model Runner é como um churrasqueiro profissional que você contrata para sua festa. Ele:

1. Traz sua própria churrasqueira (servidor de inferência)
2. Sabe exatamente como preparar cada tipo de carne (modelos de IA)
3. Limpa tudo quando termina (gerencia recursos)
4. E o melhor: você não precisa aprender a fazer churrasco para desfrutar dele!

Para quem já manja dos paranauês, o Docker Model Runner é um servidor de inferência baseado em llama.cpp que roda diretamente no host (não em containers) e expõe uma API compatível com OpenAI. Os modelos são distribuídos como artefatos OCI via Docker Hub e são carregados dinamicamente na memória apenas quando solicitados.

Pense no Docker Model Runner como um "docker-compose up" para sua IA local. Sem ficar se batendo com drivers, ambientes Python e bibliotecas incompatíveis.

A arquitetura é elegante: em vez de virtualizar o ambiente inteiro, o Model Runner aproveita os recursos nativos do host, incluindo aceleração de GPU, eliminando o overhead de containerização para tarefas de inferência intensivas.

A mágica por trás das cortinas

Quando você digita docker model run ai/llama3.2:1B-Q8_0 "Explique contêineres", o que acontece? É bem simples:

1. O Docker não inicia um container tradicional (surpresa!)
2. Em vez disso, faz uma chamada à API do servidor de inferência embutido no Docker Desktop
3. O servidor carrega o modelo em memória (se já não estiver carregado)
4. Executa a inferência usando recursos nativos do host
5. O modelo fica "de plantão" por 5 minutos e, se não receber novas solicitações, é descarregado.

Comandos básicos

Tá querendo experimentar? Aqui vai um guia rápido do tipo "Receitinha simples pro almoço":

# Verificando se está tudo funcionando
docker model status
# Deve responder algo tipo: "Docker Model Runner is running" (tudo certo!)

# Vendo quais modelos você já tem baixados
docker model list
# No início provavelmente vai estar vazio, tipo geladeira de estudante

# Baixando um modelo pequeno para teste
docker model pull ai/smollm2
# Esse modelo é pequeno, tipo um pãozinho de queijo - rápido e satisfatório!

# Executando o modelo com uma pergunta
docker model run ai/smollm2 "Explique o que é Docker como se eu tivesse 5 anos"
# Agora o modelo vai responder, provavelmente com algo sobre caixinhas mágicas...

# Quando não precisar mais, remova para liberar espaço
docker model rm ai/smollm2
# Tchau, modelo! Foi bom enquanto durou!

E agora você deve estar se perguntando: "Rafa, como eu consigo saber quais modelos estão disponíveis?"
Todos os modelos disponíveis estão no Docker Hub com o namespace ai: https://hub.docker.com/u/ai

Exemplos do mundo Real (nada de "Hello World" aqui!)

Agora vamos para a parte mais legal: chega de falação e vamos ver como isso é utilizado na vida real. Vou utilizar Go para criar os exemplos, mas você pode adaptar para qualquer linguagem.

Antes de começar (TL;DR)

Se você é do tipo que pula a introdução dos livros e vai direto para a ação, aqui está o guia estilo "miojo de 3 minutos":

1. Atualize o Docker Desktop para 4.40+
2. Abra as Configurações (aquele ícone de engrenagem)
3. Navegue até "Features in development" > aba "Beta" (onde as coisas legais ficam)
4. Ative "Enable Docker Model Runner" (clique no checkbox)
5. Bônus: Ative "Enable host-side TCP support" (para acessar via localhost, a porta padrão é 12434)
6. Clique em "Apply & Restart" (e vá pegar um café enquanto reinicia)
7. Teste com: docker model status (deve dizer que está rodando)

Como Escolher o Modelo Certo?

Escolher um modelo é como escolher um carro: depende do seu destino e do tamanho da sua garagem (ou, neste caso, da sua RAM).

1. Para iniciantes ou hardware limitado: Comece com modelos pequenos como ai/smollm2:360M-Q4_K_M ou ai/llama3.2:1B-Q8_0. São como carros compactos - cabem em qualquer garagem e consomem pouca gasolina.
2. Para equilíbrio entre qualidade e velocidade: Experimente modelos de tamanho médio como ai/llama3.2:8B-Q4_K_M. São como sedans de médio porte - bons para a maioria das situações do dia a dia.
3. Para tarefas complexas: Se você tem uma GPU poderosa, experimente modelos grandes como ai/llama3.2:70B-Q4_0. São como SUVs de luxo - mais lentos para estacionar, mas confortáveis para longas viagens.

O truque está no nome: o número antes do hífen é o tamanho (em bilhões de parâmetros) e o código após o Q indica o nível de quantização (Q8 é melhor qualidade que Q4, mas ocupa mais espaço).

Dica: Experimente antes de comprar

Não sabe qual modelo escolher? Faça como nas cafeterias chiques: peça uma amostra!

Caso 1: O atendente virtual

Cenário: Você trabalha em uma empresa que fabrica eletrodomésticos e precisa criar um atendente virtual que entenda os manuais dos produtos.

Problema da Vida Real: APIs externas são caras, serviços de nuvem expõem dados sensíveis e sua chefe está de olho no orçamento como um falcão.

Lembre-se: dependendo do volume de tráfego e de onde estiver rodando este modelo, as repostas podem ser lentas. Para ver o código completo do projeto, é só acessar o link do meu github.

Solução com Docker Model Runner:

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "log"
    "net/http"
)

// Request structures
type Message struct {
    Role    string `json:"role"`
    Content string `json:"content"`
}

type ModelRequest struct {
    Model    string    `json:"model"`
    Messages []Message `json:"messages"`
}

// Model response structures
type Choice struct {
    Message Message `json:"message"`
}

type ModelResponse struct {
    Choices []Choice `json:"choices"`
}

// API structures
type HelpRequest struct {
    Question string `json:"question"`
    Model    string `json:"model"`
}

type HelpResponse struct {
    Answer string `json:"answer"`
}

func main() {
    http.HandleFunc("/help", handleHelp)
    fmt.Println("Virtual assistant running on port 3000!")
    log.Fatal(http.ListenAndServe(":3000", nil))
}

func handleHelp(w http.ResponseWriter, r *http.Request) {
    // Check HTTP method
    if r.Method != http.MethodPost {
        http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
        return
    }

    // Decode request body
    var reqBody HelpRequest
    if err := json.NewDecoder(r.Body).Decode(&reqBody); err != nil {
        http.Error(w, "Error processing request", http.StatusBadRequest)
        return
    }

    // Use default model if not specified
    model := reqBody.Model
    if model == "" {
        model = "ai/llama3.2:1B-Q8_0"
    }

    // Prepare request for Docker Model Runner
    modelReq := ModelRequest{
        Model: model,
        Messages: []Message{
            {
                Role:    "system",
                Content: "You are an assistant specialized in LG brand appliances.",
            },
            {
                Role:    "user",
                Content: reqBody.Question,
            },
        },
    }

    // Convert to JSON
    reqJSON, err := json.Marshal(modelReq)
    if err != nil {
        http.Error(w, "Error preparing request", http.StatusInternalServerError)
        return
    }

    // Send request to Docker Model Runner
    resp, err := http.Post(
        "http://localhost:12434/engines/llama.cpp/v1/chat/completions",
        "application/json",
        bytes.NewBuffer(reqJSON),
    )
    if err != nil {
        http.Error(w, "Error querying the model", http.StatusInternalServerError)
        return
    }
    defer resp.Body.Close()

    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        http.Error(w, "Error reading model response", http.StatusInternalServerError)
        return
    }

    var modelResp ModelResponse
    if err := json.Unmarshal(body, &modelResp); err != nil {
        http.Error(w, "Error processing model response", http.StatusInternalServerError)
        return
    }

    if len(modelResp.Choices) == 0 {
        http.Error(w, "Model returned no response", http.StatusInternalServerError)
        return
    }

    response := HelpResponse{
        Answer: modelResp.Choices[0].Message.Content,
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(response)
}

Aqui criamos nosso servidor do assistente. Basicamente ele vai:

1. Receber uma requisição no endpoint /help
2. Usar o modelo que foi passado na requisição
3. Responder a pergunta que foi enviada pelo usuário

Este é um exemplo de requisição:

curl -X POST \
  http://localhost:3000/help \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Como eu reseto o Wi-Fi da minha televisão?",
    "model": "ai/llama3.2:1B-Q8_0"
  }'

E após nosso servidor processar a resposta, ele deve retornar algo assim:

{
  "answer": "**Resetação do Wi-Fi na Televisão LG**\n\n"+
    "Olá! Eu sou aqui para ajudá-lo a resolver qualquer problema que você "+
    "possa estar enfrentando com sua televisão LG.\n\n"+
    "Aqui estão os passos para resetar o Wi-Fi na sua televisão LG:\n\n"+

    "**Requisitos:**\n\n"+
    "- A televisão LG deve estar conectada à internet.\n"+
    "- Você deve ter acesso ao painel de controle da televisão ou à tela do aplicativo LG.\n\n"+

    "**Passos para resetar o Wi-Fi:**\n\n"+
    "1. **Localize o botão de reset**: Procure por um botão de reset na parte de trás da televisão. "+
       "Ele geralmente é um pequeno botão que se assemelha a um botão de \"reset\".\n"+
    "2. **Pressione o botão de reset**: Pressione o botão de reset várias vezes até que ele fique selado.\n"+
    "3. **Aguarde alguns segundos**: Aguarde alguns segundos até que a tela fique normal novamente.\n"+
    "4. **Conecte-se à internet**: Conecte-se à internet novamente.\n"+
    "5. **Ative o Wi-Fi**: Ative o Wi-Fi na televisão LG e faça login com seu nome de usuário e senha.\n\n"+

    "**Dicas adicionais:**\n\n"+
    "- Se você não conseguir encontrar o botão de reset, verifique se ele está localizado na "+
      "parte superior ou inferior da televisão.\n"+
    "- Se a televisão LG tiver um painel de controle, você pode verificar se a opção de reset está disponível.\n"+
    "- Se você estiver usando um aplicativo LG, verifique se a opção de reset está disponível no aplicativo.\n\n"+

    "**Dúvidas?**\n\n"+
    "Se você tiver alguma dúvida ou precisar de mais ajuda, não hesite em perguntar. "+
    "Estou aqui para ajudá-lo!\n\n"+
    "Espero que essas instruções tenham sido úteis. Se tiver mais alguma dúvida, "+
    "por favor, não hesite em perguntar."
}

Resultado: Um atendente virtual que roda 100% local, não expõe dados sensíveis, não depende da internet, e sua chefe adora porque não tem fatura mensal de API!

Conclusão

Limitações (Ninguém é Perfeito)

Como tudo na vida, o Docker Model Runner tem seus "poréns":

• Não tem salvaguardas contra modelos gigantes - seu computador pode virar uma panela de pressão se você tentar rodar um modelo que não cabe na RAM.
• É beta - então espere alguns bugs do tipo "funcionava ontem, hoje não".
• Não roda em containers - ao contrário do Docker tradicional, roda diretamente no host.

O Futuro é Logo Ali

O Docker não está parado no tempo. Logo mais, o Model Runner vai ganhar:

• Capacidade de personalizar e publicar seus próprios modelos (para os chefs de IA)
• Integração com Docker Compose (para quem gosta de orquestrar seus serviços)
• Parcerias com gigantes como Google e HuggingFace (mais modelos para brincar)

É como esperar a próxima temporada da sua série favorita - você sabe que vem coisa boa por aí!

Mais tempo codando, menos tempo configurando

O Docker Model Runner é como aquele amigo que aparece para ajudar na mudança com uma van, ferramentas e ainda traz pizza: resolve seu problema e ainda torna o processo agradável!

Para desenvolvedores brasileiros que sempre tiveram que se virar com criatividade (o famoso "jeitinho" no bom sentido), o Docker Model Runner é uma ferramenta que finalmente nos coloca no mesmo patamar dos grandes centros de tecnologia - podemos desenvolver aplicações de IA de ponta sem depender de APIs caras ou infraestrutura complexa.

Seja você um desenvolvedor querendo experimentar IA sem gastar uma fortuna em GPUs, ou um CTO procurando soluções para manter dados sensíveis dentro da empresa, o Docker Model Runner é aquele "pulo do gato" que faltava no seu arsenal técnico.

É isso meu povo e minha pova, deixem nos comentários se tiverem duvidas ou qualquer questão que eu possa ajudar 🥰

Comments

[Jhonny Freire]

Excelente post, parabéns.

[Rafael Pazini]

Valeu @jhonnyfreire <3