Pular para o conteúdo principal
PromptQuorumFeito para humanos. Estruturado para IA.
Início/LLMs locais avançados
Overview & Reference

Docker Model Runner: Análise de LLMs Locais via CLI do Docker

·11 min de leituraPor Hans Kuepper · Fundador do PromptQuorum · Mecanismo de descoberta de IA de pesos abertos e código aberto

O Docker Model Runner é um recurso do Docker Desktop e do Docker Engine, não um aplicativo separado para baixar, que permite baixar e executar modelos de linguagem grandes com comandos de CLI docker model. A inferência local roda via llama.cpp (CPU e Apple Silicon) ou vLLM (GPU NVIDIA, para servir com maior throughput) — e, o detalhe que a maioria das análises deixa passar, esse mecanismo de inferência roda como um processo nativo do host, não dentro de um container, o que permite acesso direto ao hardware da GPU em vez de passar pelo isolamento de containers. O Docker Model Runner expõe uma API compatível com OpenAI e vem incluído gratuitamente no Docker Desktop; se o próprio Docker Desktop é gratuito depende do tamanho da sua organização (veja Preços abaixo).

Principais conclusões

  • Integrado ao Docker Desktop (macOS, Windows) e ao Docker Engine (Linux) — não é um download separado
  • O mecanismo de inferência local é o llama.cpp para CPU/Apple Silicon ou o vLLM para servir com GPU NVIDIA
  • Roda como processo nativo do host fora do runtime de containers, para acesso direto à GPU
  • CLI: docker model pull <modelo>, docker model run <modelo>, docker model list
  • API compatível com OpenAI em http://localhost:12434/engines/v1 a partir do host, ou http://model-runner.docker.internal/engines/v1 a partir de outro container
  • Os modelos vêm do catálogo de modelos de IA do Docker Hub, outros registries compatíveis com OCI, ou Hugging Face
  • Sem custo adicional — o recurso vem com o Docker Desktop; se o Docker Desktop em si precisa de uma assinatura paga depende do porte da empresa

📍 Em uma frase

O Docker Model Runner é um recurso integrado ao Docker Desktop e ao Docker Engine que executa LLMs localmente via comandos de CLI docker model, com llama.cpp ou vLLM como mecanismo de inferência rodando como processo nativo do host, e expõe uma API compatível com OpenAI.

💬 Em termos simples

Se você já usa Docker para rodar containers, o Docker Model Runner permite baixar e executar um modelo de IA da mesma forma — docker model pull e docker model run — sem instalar um aplicativo de chat separado, e sem que o modelo realmente rode dentro de um container.

Ler em:
🇺🇸en🇩🇪de🇫🇷fr🇯🇵ja🇨🇳zh🇪🇸es🇧🇷pt🇸🇦ar🇰🇷ko

O Docker Model Runner é um recurso integrado ao Docker Desktop e ao Docker Engine que executa modelos de linguagem grandes localmente usando comandos de CLI docker model, apoiado em llama.cpp ou vLLM, e exposto por uma API compatível com OpenAI. Não é um aplicativo independente — é um recurso adicionado ao Docker Desktop, e por isso vem gratuito junto com o mesmo Docker Desktop que a maioria dos desenvolvedores já tem instalado. Esta análise cobre o que o Docker Model Runner realmente faz, como ele executa modelos sem colocar a inferência dentro de um container, como instalar e usar, e onde ele se encaixa perto de outras ferramentas de runtime local como Ollama e llama.cpp.

Docker Model Runner: Análise de LLMs Locais via CLI do Docker

O que é o Docker Model Runner?

O Docker Model Runner é um recurso do Docker Desktop e do Docker Engine para baixar e executar modelos de linguagem grandes localmente, usando a mesma CLI docker que os desenvolvedores já usam para containers. Segundo a própria página oficial do produto Docker, ele oferece inferência local-first com uma API compatível com OpenAI, baixando modelos do Docker Hub, de outros registries compatíveis com OCI, ou do Hugging Face. Não é um aplicativo de chat com janela gráfica — é um recurso de CLI mais um servidor de inferência local, pensado para ser usado a partir de um terminal, do Docker Compose, ou de código que chama sua API.

  • Vem no Docker Desktop (macOS, Windows) e como pacote docker-model-plugin para o Docker Engine no Linux — não é um instalador separado
  • Mecanismos de inferência local: llama.cpp para CPU e Apple Silicon, vLLM para servir com GPU NVIDIA, segundo a documentação do Docker
  • Fontes de modelos: o catálogo curado de IA do Docker Hub, qualquer registry compatível com OCI, ou Hugging Face
  • Integra-se com ferramentas que os desenvolvedores já usam em torno do Docker: Docker Compose, Testcontainers, e frameworks como LangChain, Spring AI e Open WebUI via a API compatível com OpenAI
  • Desenvolvedor: Docker, Inc.

Instalação e primeiros passos

O Docker Model Runner é um recurso de CLI integrado ao Docker Desktop e ao Docker Engine, não um aplicativo independente para baixar — por isso não existe um instalador separado nem um botão de download. Você instala o Docker Desktop (ou, no Linux, o Docker Engine mais o plugin model-runner), e os comandos docker model ficam disponíveis.

  1. 1
    Instale o Docker Desktop para macOS ou Windows, ou instale no Linux o Docker Engine mais o plugin model-runner (sudo apt-get install docker-model-plugin no Debian/Ubuntu, ou sudo dnf install docker-model-plugin no Fedora/RHEL).
  2. 2
    Ative o Model Runner se ainda não estiver ativo: docker desktop enable model-runner (Docker Desktop), ou confirme que o plugin está ativo no Docker Engine.
  3. 3
    Baixe um modelo do catálogo de IA do Docker Hub: docker model pull ai/smollm2:360M-Q4_K_M.
  4. 4
    Execute-o diretamente pela linha de comando: docker model run ai/smollm2:360M-Q4_K_M "Give me a fact about whales."
  5. 5
    Liste a qualquer momento os modelos já baixados localmente com docker model list.
  6. 6
    Para acessar o modelo via HTTP em vez da CLI, use a API compatível com OpenAI — veja A API compatível com OpenAI abaixo para o endpoint exato.

Por que ele roda como processo do host, e não em um container

Apesar do prefixo de comando docker, o Docker Model Runner não executa a inferência do modelo dentro de um container. O post oficial do blog do Docker que apresenta o recurso é explícito sobre isso: executar docker model run "não sobe nenhum tipo de container". Em vez disso, ele chama uma API de servidor de inferência hospedada pelo Model Runner via Docker Desktop, e esse servidor de inferência executa seu mecanismo (llama.cpp ou vLLM) como um processo nativo do host — um processo comum rodando diretamente no seu sistema operacional, assim como qualquer outro programa instalado localmente.

  • O motivo declarado é o acesso à GPU: um processo nativo do host pode usar a GPU da sua máquina (a GPU integrada do Apple Silicon, ou uma GPU NVIDIA) diretamente, sem a indireção extra de passar a GPU do container para o host
  • É uma escolha de arquitetura deliberada por desempenho, não uma limitação do runtime de containers do Docker — o Docker Model Runner usa containers em outras partes do seu fluxo de trabalho (por exemplo, parte do empacotamento de modelos é baseada em OCI), mas não para o processo de inferência em si
  • Na prática, isso significa que um modelo em execução se comporta mais como um serviço em segundo plano na sua máquina do que como um container que você poderia inspecionar com docker ps
  • Os modelos permanecem carregados na memória até que outro modelo seja solicitado ou um período de inatividade passe, então a primeira requisição após a inicialização é mais lenta que as seguintes

llama.cpp vs. vLLM: qual mecanismo executa seu modelo

O Docker Model Runner não implementa seu próprio mecanismo de inferência — ele encapsula dois mecanismos open source existentes e escolhe entre eles com base no seu hardware e no formato do modelo, segundo a documentação do Docker.

llama.cpp

Uso:
Desenvolvimento local, inferência econômica em recursos
Formato do modelo:
GGUF (quantizado)
Plataformas:
CPU e Apple Silicon; também backends de GPU para Windows/Linux
Artigos sobre llama.cpp (10)

+172 mais não exibidos

vLLM

Uso:
Serviço orientado a produção, maior throughput
Formato do modelo:
Safetensors
Plataformas:
Linux e Windows (WSL2) com GPU NVIDIA
Artigos sobre vLLM (10)

+89 mais não exibidos

É o mesmo mecanismo llama.cpp coberto em profundidade no explicador de llama.cpp deste site, e o mesmo mecanismo vLLM coberto no explicador de vLLM — o Docker Model Runner é uma camada de empacotamento e CLI sobre esses mecanismos, não uma alternativa construída do zero a nenhum dos dois. O Docker também documenta suporte experimental ao Diffusers para modelos de geração de imagens (Stable Diffusion) no Linux com GPUs NVIDIA, o que está fora do escopo desta análise focada em LLMs.

A API compatível com OpenAI

O Docker Model Runner expõe uma API HTTP compatível com OpenAI para que código cliente de OpenAI já existente possa apontar para um modelo local em vez de um endpoint na nuvem, segundo o post de blog do Docker sobre o recurso.

  • A partir da máquina host: http://localhost:12434/engines/v1 (o acesso TCP precisa ser ativado uma vez com docker desktop enable model-runner --tcp 12434)
  • A partir de outro container na mesma rede Docker: http://model-runner.docker.internal/engines/v1
  • Compatível com ferramentas e frameworks já construídos para o formato da API OpenAI, incluindo LangChain, Spring AI e Open WebUI, segundo os próprios exemplos de integração do Docker
  • Os modelos carregam sob demanda quando chega uma requisição e permanecem residentes na memória até que outro modelo seja solicitado ou um tempo de inatividade seja atingido

Plataformas compatíveis

O suporte de hardware do Docker Model Runner varia conforme o sistema operacional e o mecanismo de inferência em uso, segundo a documentação do Docker.

macOS

Detalhes:
Apple Silicon, via llama.cpp com aceleração de GPU nativa

Windows

Detalhes:
AMD64 com GPU NVIDIA (driver 576.57 ou mais recente) via llama.cpp ou vLLM (WSL2); ARM64 com GPUs Qualcomm Adreno série 6xx via llama.cpp

Linux

Detalhes:
Somente CPU, backends NVIDIA CUDA, AMD ROCm ou Vulkan via llama.cpp; GPU NVIDIA via vLLM (driver 575.57.08 ou mais recente)

As versões mínimas exatas de driver e as famílias de GPU compatíveis mudam conforme o Docker atualiza o recurso — verifique os requisitos atuais em docs.docker.com/ai/model-runner antes de planejar uma implantação em torno de uma GPU específica.

Preços do Docker Model Runner

O Docker Model Runner em si não adiciona nenhum custo separado — é um recurso incluído no Docker Desktop e no Docker Engine. Se você deve algo depende inteiramente de se o seu uso do Docker Desktop se qualifica como gratuito, segundo o próprio Contrato de Serviço de Assinatura do Docker.

Personal (gratuito)

Para quem é:
Pessoas físicas, educação, projetos open source não comerciais, e empresas com menos de 250 funcionários e menos de US$ 10 milhões em receita anual
Inclui o Docker Model Runner?:
Sim

Pro / Team / Business (pagos)

Para quem é:
Empresas maiores, ou qualquer organização que precise de recursos de equipe além do escopo do plano gratuito
Inclui o Docker Model Runner?:
Sim

Os modelos de IA curados pelo Docker Hub podem ser baixados gratuitamente independentemente do nível de assinatura. Os planos pagos do Docker (Pro, Team, Business) adicionam recursos sem relação com o Model Runner em si, como assentos de equipe e gestão centralizada — confira docker.com/pricing para os preços atuais, já que eles mudam de forma independente do recurso Model Runner.

Quem deveria usar o Docker Model Runner?

O Docker Model Runner se encaixa em um fluxo de trabalho específico: desenvolvedores que já vivem no Docker e querem adicionar inferência de LLM local sem incluir uma segunda ferramenta na sua stack.

Use o Docker Model Runner se

  • Você já usa Docker Desktop ou Docker Engine diariamente e quer adicionar inferência de LLM local à mesma CLI, sem instalar um aplicativo separado
  • Sua aplicação ou serviço já é construído em torno do Docker Compose ou de containers, e você quer que o endpoint do modelo seja acessível a partir de outros containers via model-runner.docker.internal
  • Você quer a opção de migrar do desenvolvimento em CPU/Apple Silicon (llama.cpp) para o serviço de produção em GPU NVIDIA (vLLM) sem trocar de ferramentas
  • Você se sente confortável trabalhando a partir de um terminal e uma API HTTP em vez de uma janela de chat gráfica

Espere, ou procure outra opção, se

  • Você quer uma interface de chat gráfica de apontar-e-clicar como sua forma principal de conversar com um modelo — o Docker Model Runner não tem janela de chat integrada; combine-o com um front-end como o Open WebUI se quiser uma
  • Você ainda não usa Docker e não quer instalar o Docker Desktop só para rodar modelos locais — um aplicativo dedicado como o Jan ou o GPT4All tem uma pegada menor para esse caso
  • Você precisa que o processo de inferência rode estritamente dentro de um container por motivos de isolamento — o Docker Model Runner executa deliberadamente seu mecanismo como processo do host, não como container, por desempenho de GPU (veja Por que ele roda como processo do host acima)
  • Sua organização está acima do limite de uso gratuito de 250 funcionários / US$ 10 milhões em receita e ainda não orçou uma assinatura paga do Docker — confirme primeiro seu status de licenciamento do Docker

Concorrentes e alternativas

O Docker Model Runner se posiciona no segmento de runtimes de inferência local, ao lado de mecanismos CLI-first e aplicativos de desktop que envolvem os mesmos mecanismos subjacentes. Veja o Diretório de Software de LLM Local para o catálogo completo.

  • llama.cpp — o mecanismo de inferência que o próprio Docker Model Runner usa para CPU/Apple Silicon; executá-lo diretamente dá controle sobre flags de build e quantização que o wrapper do Docker não expõe.
  • vLLM — o mesmo mecanismo de serviço em GPU que o Docker Model Runner usa para cargas de trabalho de produção; executá-lo diretamente é melhor se você precisa de toda a superfície de configuração do vLLM em vez da CLI simplificada do Docker por cima dele.
  • Ollama — a comparação de "um só comando" mais próxima: como o Docker Model Runner, o Ollama envolve o llama.cpp atrás de uma CLI simples de puxar-e-executar e uma API compatível com OpenAI, mas como ferramenta independente em vez de recurso do Docker Desktop — melhor opção se você ainda não usa Docker.
  • Jan — um aplicativo de desktop gratuito e open source com uma janela de chat gráfica, construído sobre o mesmo mecanismo llama.cpp, para desenvolvedores que querem uma interface de apontar-e-clicar em vez de um fluxo de CLI e API.
  • GPT4All — outro aplicativo de chat local open source baseado em llama.cpp, para o mesmo caso de uso de "quero uma janela, não um terminal" que o Jan.

Comparar no diretório

Erros comuns

A maior parte da confusão sobre o Docker Model Runner vem de assumir que ele se comporta como uma carga de trabalho Docker comum, ou de não perceber que é um recurso do Docker Desktop, e não um produto separado para instalar.

Erro 1: assumir que o modelo roda dentro de um container

Como o comando é docker model run, é fácil assumir que a inferência acontece dentro de um container que você poderia inspecionar com docker ps. Não é o caso — a própria documentação do Docker confirma que o mecanismo de inferência roda como um processo nativo do host para acesso direto à GPU, e não dentro de um container.

Erro 2: procurar um instalador ou uma página de download separados

O Docker Model Runner não tem um instalador independente. É um recurso do Docker Desktop (macOS, Windows) e do Docker Engine mais o plugin model-runner (Linux) — você instala o Docker em si, não o "Docker Model Runner" como um produto à parte.

Erro 3: assumir que o Docker Model Runner cobra taxas próprias e separadas

O Model Runner em si não tem nenhum custo adicional. A única questão de custo é se o seu uso existente do Docker Desktop se encaixa no plano Personal gratuito (menos de 250 funcionários e menos de US$ 10 milhões em receita anual, segundo o Contrato de Serviço de Assinatura do Docker) ou exige um plano Pro/Team/Business pago — uma questão de licenciamento sobre o Docker Desktop em geral, não sobre esse recurso especificamente.

Erro 4: esperar que um único mecanismo cubra todas as plataformas e GPUs

O llama.cpp e o vLLM cobrem hardware diferente: o llama.cpp cuida de CPU e Apple Silicon (além de alguns backends de GPU para Windows/Linux), enquanto o vLLM se limita a GPUs NVIDIA no Linux e no Windows WSL2. Confira a tabela Plataformas compatíveis acima antes de assumir que uma combinação específica de modelo/mecanismo vai funcionar na sua máquina.

Perguntas frequentes

O que é o Docker Model Runner?

O Docker Model Runner é um recurso integrado ao Docker Desktop e ao Docker Engine que executa modelos de linguagem grandes localmente via comandos de CLI docker model, usando llama.cpp ou vLLM como mecanismo de inferência e expondo uma API compatível com OpenAI.

O Docker Model Runner é gratuito?

O recurso em si não adiciona nenhum custo separado — faz parte do Docker Desktop e do Docker Engine. Se você precisa de uma assinatura paga do Docker depende do porte da sua organização: o Docker Desktop é gratuito para pessoas físicas, projetos open source não comerciais, e empresas com menos de 250 funcionários e menos de US$ 10 milhões em receita anual, segundo o Contrato de Serviço de Assinatura do Docker.

O Docker Model Runner executa os modelos dentro de um container?

Não. Apesar do prefixo de comando docker model, o mecanismo de inferência (llama.cpp ou vLLM) roda como um processo nativo do host fora do runtime de containers, segundo o próprio post de blog do Docker que apresenta o recurso — isso dá acesso direto ao hardware da GPU em vez de passar pelo isolamento de containers.

Quais comandos de CLI o Docker Model Runner usa?

Os comandos principais são docker model pull <modelo> para baixar um modelo, docker model run <modelo> para executar inferência pela linha de comando, e docker model list para ver os modelos já baixados localmente.

Qual é o endpoint de API do Docker Model Runner?

Uma API compatível com OpenAI é exposta em http://localhost:12434/engines/v1 a partir da máquina host (depois de ativar o acesso TCP), ou em http://model-runner.docker.internal/engines/v1 a partir de outro container na mesma rede Docker.

O Docker Model Runner usa llama.cpp ou vLLM?

Ambos, dependendo da situação. O llama.cpp cuida da inferência em CPU e Apple Silicon para desenvolvimento local; o vLLM cuida do serviço com GPU NVIDIA no Linux e no Windows WSL2, voltado a um uso de produção com maior throughput.

Quais plataformas o Docker Model Runner suporta?

macOS em Apple Silicon; Windows em AMD64 com GPU NVIDIA ou ARM64 com uma GPU Qualcomm Adreno série 6xx; e Linux com backends somente CPU, NVIDIA CUDA, AMD ROCm ou Vulkan. Veja a seção Plataformas compatíveis acima para mais detalhes.

Em que o Docker Model Runner se diferencia do Ollama?

Ambos envolvem o llama.cpp atrás de uma CLI simples de puxar-e-executar e uma API compatível com OpenAI. A principal diferença está no empacotamento: o Ollama é uma ferramenta independente que você instala separadamente, enquanto o Docker Model Runner é um recurso do Docker Desktop/Engine — melhor opção se você já usa Docker diariamente, já que não adiciona uma segunda ferramenta ao seu fluxo de trabalho.

De onde vêm os modelos do Docker Model Runner?

Os modelos podem ser baixados do catálogo curado de modelos de IA do Docker Hub, de qualquer outro registry compatível com OCI, ou do Hugging Face, segundo a página do produto do Docker.

Fontes

← Voltar para LLMs locais avançados

MCP