Docker Model Runner: executar LLMs com Docker, sem Ollama

#Por que usar o Docker Model Runner?

O Docker Model Runner é a resposta do Docker ao Ollama: uma forma de executar LLMs localmente sem sair do ecossistema Docker. Você não precisa mais gerenciar um daemon separado nem uma pasta de modelos à parte — os modelos são distribuídos como artefatos OCI, baixados de um registro exatamente como imagens de contêineres e controlados por uma nova família de comandos docker model.

Tecnicamente, o motor de inferência do Model Runner é o mesmo do Ollama, do LM Studio ou do Jan: llama.cpp. A diferença, portanto, não está na velocidade bruta, mas na integração. Se você já usa Docker no seu computador ou servidor, o Model Runner evita adicionar mais uma ferramenta e permite que seus contêineres se comuniquem naturalmente com um modelo local.

Modelos no formato OCI

Um LLM pode ser baixado, versionado e enviado como uma imagem Docker. Mesmo registro, mesma autenticação, mesmos hábitos.

API compatível com OpenAI

Endpoints /engines/v1/chat/completions, /completions, /models. Qualquer cliente OpenAI pode se conectar mudando apenas a URL base.

Sem ferramenta adicional

Não é necessário instalar o Ollama separadamente. A CLI docker basta, e a inferência se integra ao Compose.

GPU utilizada diretamente

O motor roda no host (Apple Silicon via Metal, NVIDIA via CUDA) e não em um contêiner, para não perder a aceleração.

#Pré-requisitos

Docker Desktop recente

O Model Runner chegou com o Docker Desktop 4.40 (macOS com Apple Silicon) e depois foi estendido ao Windows com GPU NVIDIA. Atualize para a versão mais recente disponível.

Ou Docker Engine no Linux

Em um servidor Linux sem Docker Desktop, o Model Runner instala-se via o pacote docker-model-plugin (ver abaixo).

VRAM ou memória unificada

Em Q4_K_M, considere aproximadamente 2 GB para um 3B, aproximadamente 5 GB para um 7B, aproximadamente 9 GB para um 14B e aproximadamente 19 GB para um 32B. No Mac, a memória unificada atua como VRAM.

Uma GPU recomendada

RTX 3060 de 12 GB para começar, RTX 4070/4080 na faixa intermediária, RTX 4090 de 24 GB ou um Mac M4 Pro (24–48 GB de memória unificada) para modelos grandes. Usar apenas o CPU funciona, mas é lento.

#1. Ativar o Docker Model Runner

A função não está sempre ativa por padrão. No Docker Desktop, encontra-se nas configurações; na linha de comando, basta uma instrução.

1. 01
   Via Docker Desktop

   Abra Settings → AI (ou « Beta features », conforme a versão), depois marque « Enable Docker Model Runner ». Para chamar a API a partir do host, ative também « Enable host-side TCP support » e anote a porta sugerida (12434 por padrão).
2. 02
   Via CLI

   Um comando ativa o serviço e, opcionalmente, abre a porta TCP no lado do hospedeiro para acessar a API diretamente da sua máquina, sem passar por um contêiner.
3. 03
   Verificar

   docker model status confirme que le runner tourne. docker model version affiche la version du plugin installé.

# Activer Model Runner
docker desktop enable model-runner

# Activer + exposer l'API sur le port hôte 12434
docker desktop enable model-runner --tcp 12434

# Vérifier l'état
docker model status

Em um servidor Linux com Docker Engine (sem Docker Desktop), o Model Runner é adicionado como um plugin. Em uma distribuição Debian/Ubuntu:

sudo apt-get update
sudo apt-get install docker-model-plugin

# Confirmer
docker model version

#2. Baixar um modelo no formato OCI

Docker hospeda uma biblioteca de modelos empacotados no formato OCI no namespace ai/ do Docker Hub. Eles são baixados exatamente como imagens, com o comando docker model pull. As tags codificam o tamanho e a quantização do modelo.

# Un petit modèle pour tester rapidement
docker model pull ai/smollm2

# Un modèle plus capable, tag explicite
docker model pull ai/qwen3.5

# Une variante quantifiée précise (taille + quantization)
docker model pull ai/gemma4:12B-Q4_K_M

# Lister ce qui est stocké localement
docker model ls

ai/smollm2

Modelo muito pequeno, ideal para validar a instalação em poucos segundos mesmo sem GPU.

ai/qwen3.5 · ai/gemma4 · ai/granite4.2

Modelos generalistas sólidos de 2026; escolha o tamanho de acordo com sua VRAM (2B, 4B, 9B, 12B…). O Qwen 3.5 9B (≈6,6 GB em Q4) é uma boa opção padrão para 8 GB, todos sob licença Apache 2.0.

Tags de quantização

Uma tag como 9B-Q4_K_M especifica o tamanho e a compressão. Q4_K_M é o equilíbrio recomendado entre qualidade e memória; Q5_K_M e Q8_0 pesam mais.

O formato OCI significa que esses modelos podem ser armazenados em qualquer registro compatível: Docker Hub, mas também um registro privado da empresa. Você pode, portanto, enviar um modelo interno da mesma forma que envia uma imagem, com a mesma autenticação e as mesmas políticas de acesso.

#3. Conversar com docker model run

Assim como docker run inicia um contêiner, docker model run inicia uma conversa. Sem argumento de mensagem, abre um chat interativo no terminal; com um prompt, responde uma vez e devolve o controle — perfeito para criar scripts.

# Chat interactif
docker model run ai/qwen3.5

# Prompt unique (mode « one-shot », scriptable)
docker model run ai/qwen3.5 "Explique le format OCI en une phrase."

A primeira chamada a um modelo o carrega na memória; as seguintes reutilizam a instância carregada. O motor descarrega automaticamente o modelo após um período de inatividade para liberar a VRAM, sem que você precise gerenciar um daemon.

# Détails d'un modèle (taille, quantization, architecture)
docker model inspect ai/qwen3.5

# Logs du moteur d'inférence
docker model logs

# Supprimer un modèle pour récupérer de l'espace disque
docker model rm ai/smollm2

#4. API compatível com a OpenAI

O verdadeiro diferencial do Docker Model Runner, assim como do Ollama, é sua API compatível com a API da OpenAI. Qualquer ferramenta projetada para a API da OpenAI funciona apenas alterando a URL base. Existem duas URLs, dependendo de onde você faz a chamada.

A partir do host (TCP)

http://localhost:12434/engines/v1/… si vous avez activé le support TCP côté hôte (port 12434 par défaut).

A partir de um contêiner

http://model-runner.docker.internal/engines/v1/… — un nom DNS interne résolu automatiquement dans le réseau Docker.

Chamada direta de chat via curl a partir do host, após ativar a porta TCP:

curl http://localhost:12434/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/qwen3.5",
    "messages": [
      {"role": "system", "content": "Tu réponds en français, de façon concise."},
      {"role": "user", "content": "Qu'\''est-ce qu'\''un artefact OCI ?"}
    ]
  }'

O campo model deve corresponder a um modelo baixado localmente. No SDK Python da OpenAI, basta redirecionar base_url; a chave de API pode ser qualquer string, pois o Model Runner não a exige em execução local.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:12434/engines/v1",
    api_key="docker",  # non vérifiée en local
)

resp = client.chat.completions.create(
    model="ai/qwen3.5",
    messages=[
        {"role": "user", "content": "Donne trois idées de noms pour un projet open source."}
    ],
)
print(resp.choices[0].message.content)

#5. Conectar um contêiner ao modelo

O ponto forte da integração Docker é este: um contêiner da sua aplicação pode chamar o modelo via DNS interno, sem expor portas no host. A partir do código que roda em um contêiner, a URL base torna-se model-runner.docker.internal.

curl http://model-runner.docker.internal/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/qwen3.5",
    "messages": [{"role": "user", "content": "Bonjour"}]
  }'

Na prática, passa-se a URL por variável de ambiente para que o mesmo código funcione localmente (porta 12434) e em container (DNS interno). Um trecho do docker-compose.yml que injeta o endpoint no serviço da aplicação:

services:
  app:
    build: .
    environment:
      OPENAI_BASE_URL: http://model-runner.docker.internal/engines/v1
      OPENAI_API_KEY: docker
      MODEL_NAME: ai/qwen3.5

#Docker Model Runner ou Ollama, conforme seu fluxo de trabalho

Os dois rodam llama.cpp e expõem uma API compatível com OpenAI. A escolha depende do ecossistema em que você trabalha, não da performance bruta.

Escolha o Model Runner

Quando o Docker já é sua base: você quer que seus contêineres se comuniquem com o LLM pela rede Docker, distribuir modelos por meio de um registro OCI privado e evitar mais uma ferramenta para instalar e manter.

Escolha o Model Runner

Para uma stack Compose em que o modelo é um serviço entre outros, versionado e implantado com os mesmos procedimentos usados para suas imagens.

Permaneça com o Ollama

Quando você quer o catálogo de modelos mais amplo e mais atualizado, uma comunidade e documentação abundantes, e uma ferramenta que funciona da mesma forma no Windows, macOS e Linux sem o Docker Desktop.

Permaneça com o Ollama

Para tarefas simples de escritório, fora de qualquer ambiente com contêineres: Ollama na porta 11434 continua sendo a opção mais direta, com um ecossistema de interfaces (Open WebUI, LM Studio) já conectado a ele.

#Solução de problemas

« docker: 'model' is not a docker command »

O plugin não está instalado ou o Model Runner não está ativo. Atualize o Docker Desktop, ative a funcionalidade ou instale o docker-model-plugin no Docker Engine.

A API não responde em localhost:12434

O suporte a TCP no host não está ativado. Execute novamente docker desktop enable model-runner --tcp 12434, ou marque a opção em Settings → AI.

Um contêiner não consegue se conectar ao modelo

A partir de um contêiner, use model-runner.docker.internal, não localhost: localhost aponta para o próprio contêiner, não para o hospedeiro.

Carregamento lento ou 'out of memory'

O modelo excede a capacidade da sua VRAM. Baixe uma variante mais leve (tag Q4_K_M em vez de Q5/Q8) ou um modelo menor e verifique se a GPU está sendo detectada corretamente.

O GPU não é usado (Windows)

O suporte a GPUs NVIDIA no Windows chegou após o lançamento inicial. Certifique-se de estar usando uma versão do Docker Desktop que ofereça esse suporte e de que seus drivers estejam atualizados.

#Para se aprofundar

Você aproveita melhor o Docker Model Runner ao integrá-lo aos outros componentes da IA local já abordados no site:

Instalar o Ollama: Windows, macOS e Linux

Para comparar na prática com a alternativa de referência e sua porta 11434 e decidir qual corresponde ao seu workflow.

Q4, Q5, Q8: qual quantização escolher

Para ler corretamente as tags dos modelos OCI (7B-Q4_K_M, etc.) e ponderar qualidade, velocidade e memória antes de baixar o modelo.

llama-server: uma API OpenAI local com llama.cpp

Para ver o mesmo motor exposto de outra forma, com um controle mais preciso do offloading para a GPU.