Como executar modelos de LLM localmente com Docker

Quando entram em contato com modelos de linguagem de grande escala (LLMs), os desenvolvedores geralmente estão em um contexto bastante associado a modelos fundacionais, como o GPT-4o da OpenAI, o Gemini 2.5 Pro do Google e o Claude Sonnet 4 da Anthropic. No entanto, alguns casos de uso de IA generativa podem ser realizados inteiramente de forma local, na máquina de desenvolvimento.

Neste guia rápido, vou explicar como configurar modelos para rodar localmente no seu laptop (ou fazer inferência, se você tiver GPUs para isso), sem precisar se aprofundar em terminologia de machine learning, ferramentas Python ou outros conhecimentos que podem parecer distantes para você como desenvolvedor de software.

Por que executar modelos de LLM localmente na sua própria máquina?

Seja por causa do custo dos modelos, de preocupações com privacidade e segurança, ou de políticas da empresa e regulamentações externas, alguns casos de uso e requisitos exigem que os modelos sejam executados localmente no seu ambiente (em um data center local) ou diretamente no seu PC ou laptop.

Como executar modelos com Docker

O Docker ficou conhecido por ser uma tecnologia que abstrai muitos dos desafios de empacotar aplicações e permite executá-las sem problemas em diferentes plataformas. Agora, o Docker está fazendo o mesmo com LLMs.

Este tutorial exige:

• Docker Engine ou Docker Desktop, versão 4.41 ou superior. Recomendamos atualizar sua instalação local para acompanhar o tutorial sem problemas.

Para mais detalhes, consulte a documentação do Docker Model Runner.

Etapa 1: habilite o Docker Model Runner

Se você atualizou para a versão mais recente do Docker, provavelmente esse recurso já estará habilitado. Mas também será necessário habilitar o host-side TCP support para que possamos conectar ao modelo a partir do código do programa, como no Vercel AI SDK. Caso contrário, você só poderá interagir com o model runner pela CLI do docker.

Abra Docker Desktop Settings, acesse Beta features, e habilite estas duas opções:

• “Enable Docker Model Runner”

• “Enable host-side TCP support”

Etapa 2: obtenha um modelo de LLM

Em seguida, abra o painel do Docker Desktop e selecione Models no menu da barra lateral esquerda para ver todos os modelos disponíveis:

Você também pode encontrar modelos na web pelo Docker Hub.

Vamos usar o modelo smollm2, que ocupa menos de 300 megabytes de espaço em disco. Para modelos com melhor desempenho, porém, recomendo a família de 3B a 4B, como gemma3, ou o próximo nível, com modelos de 7B a 8B parâmetros. Você também pode experimentar o modelo de 14B parâmetros da Microsoft, o phi4.

O desempenho do modelo depende muito da CPU e da GPU locais, além do mecanismo de inferência disponível localmente para aproveitar esses recursos. O Docker facilita os testes locais, mas a configuração padrão pronta para uso provavelmente não está otimizada para obter o melhor desempenho.

Agora que escolhemos um modelo local para executar, basta rodar este comando no terminal:

docker model run ai/smollm2

Como provavelmente o modelo ainda não está instalado no seu ambiente, o Docker vai baixá-lo do registro e executá-lo:

Agora você pode interagir com o modelo em uma sessão interativa pela CLI.

Etapa 3: use o LLM local com um SDK de IA

O Vercel AI SDK costuma ser usado com endpoints de modelos hospedados, como os da OpenAI ou da Anthropic. No entanto, é fácil adaptá-lo para funcionar com um modelo hospedado por você, como um modelo executado pelo Docker Model Runner.

Em geral, para fazer prompts a LLMs, é preciso criar um fetcher personalizado usando as primitivas createStreamableUI() e streamText() do SDK. Veja abaixo um exemplo de código TypeScript que mostra como configurá-lo como se fosse um endpoint da OpenAI.

Primeiro, verifique se o AI SDK está instalado:

npm install ai

Configure as variáveis de ambiente:

OPENAI_API_KEY=docker
OPENAI_BASE_URL=http://localhost:12434/engines/llama.cpp/v1

Observe que OPENAI_API_KEY está definido como docker; não se trata de um valor genérico de exemplo.

Em seguida, podemos usar uma definição de rota de API como esta:

import { OpenAIStream, StreamingTextResponse } from 'ai';
import OpenAI from 'openai';

// or 'nodejs' depending on your environment
export const runtime = 'edge';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
  baseURL: process.env.OPENAI_BASE_URL!,
});

export async function POST(req: Request) {
  const { messages } = await req.json();

  const response = await openai.chat.completions.create({
    model: 'ai/smollm2',
    messages,
    stream: true,
  });

  const stream = OpenAIStream(response);
  return new StreamingTextResponse(stream);
}

Da mesma forma, você pode usar o SDK oficial da OpenAI e configurá-lo com os valores locais do Docker Model Runner para OPENAI_BASE_URL e OPENAI_API_KEY.

Mais sobre Docker, IA e segurança

Agora que você tem um LLM rodando localmente, pode se interessar por medidas para garantir que os LLMs gerem código seguro, entender os ataques de injeção de prompt e explorar o universo do MCP.

Se quiser saber mais sobre algum desses assuntos, recomendo os seguintes artigos:

• Como você já está usando Docker neste tutorial sobre LLM local, talvez queira explorar como executar servidores MCP com Docker.

• Saiba como a injeção de prompt pode ser explorada por meio de texto invisível em PDFs para enganar a lógica baseada em LLMs.

• Se você está começando agora com MCP, leia um guia para entender visualmente a arquitetura do MCP.

• Para saber mais sobre MCPs, confira alguns servidores MCP populares para desenvolvedores.