Como Usar LLMs Locais como APIs: Guia Completo

Seu laptop pode servir um modelo de 70 bilhões de parâmetros atrás do mesmo endpoint no formato OpenAI que você usa em produção. Troque uma URL base e seu código continua funcionando. Essa única alteração desbloqueia o desenvolvimento offline, custo zero por token e um caminho privado para dados regulados, razão pela qual o Hacker News impulsionou “A IA Local precisa ser a norma” de 633 para 1.760 pontos em um dia. O texto abaixo mostra como escolher um runtime, expor o endpoint, apontar seu cliente para ele e testar todo o fluxo com Apidog antes de promover qualquer alteração para um modelo hospedado.

TL;DR

Você pode executar uma API LLM local em seu laptop com Ollama, vLLM ou llama.cpp, e cada um deles expõe um endpoint REST compatível com OpenAI. Altere base_url para http://localhost:11434/v1 em seu cliente OpenAI existente e o mesmo código rodará contra Llama 3.3, DeepSeek V4 ou Qwen 3.6 sem reescrita. Conduza todo o fluxo a partir do Apidog para que seus testes de cenário permaneçam idênticos em ambientes locais e hospedados.

Introdução

A pilha da API LLM local passou de um brinquedo de pesquisa para um driver diário em dezoito meses. A Apple lançou 128 GB de memória unificada no M3 Max. O Ollama atingiu um milhão de downloads semanais. O vLLM ultrapassou a marca de 30.000 estrelas no GitHub. A maior mudança, porém, foi social. Todo runtime principal agora "fala" o formato /v1/chat/completions do OpenAI. Você não precisa mais manter dois caminhos de cliente. A mesma chamada de SDK atinge o localhost ou api.openai.com com base em uma única variável de ambiente.

Isso é importante para desenvolvedores de API porque suas ferramentas existentes continuam funcionando. Seus modelos de solicitação no Apidog apontam para https://api.openai.com/v1/chat/completions. Troque a variável de URL base, clique em Enviar, e você receberá o mesmo JSON de volta de um modelo rodando em sua própria GPU. Nenhum novo esquema. Nenhum novo fluxo de autenticação. Se você já rastreia gastos com API por recurso, você pode fazer um teste A/B entre um modelo local e um hospedado e observar a linha de custo cair enquanto a latência aumenta.

Este guia aborda a escolha do runtime, configuração do servidor, conexão do cliente, testes de cenário, trade-offs de quantização e uma tabela de custo vs. latência para quatro modelos atuais. As amostras de código são testadas contra Ollama 0.6 e vLLM 0.7 no macOS 15.4 e Ubuntu 24.04. Para o panorama mais amplo de opções, consulte Melhores LLMs locais 2026. As referências externas para cada afirmação estão na parte inferior.

Por que LLMs locais fazem sentido para desenvolvedores de API

Você entrega código que chama uma LLM. Você também depura esse código no avião, em conferências com Wi-Fi ruim e dentro de redes de clientes que bloqueiam a saída para *.openai.com. Uma API LLM local oferece um ambiente de desenvolvimento que espelha a produção sem a dependência de rede.

A questão da privacidade é a mais destacada. HIPAA, GDPR e o Ato de IA da UE tratam prompts como dados de usuário no momento em que incluem notas de pacientes, contratos ou identificadores biométricos. Enviar essa carga útil para um endpoint hospedado cria uma relação de processador de dados que você precisa documentar, auditar e renovar. Um modelo que nunca sai do seu hardware pula essa burocracia inteiramente. A orientação de 2024 do Comitê Europeu para a Proteção de Dados sobre o processamento de IA observa que a inferência no dispositivo remove a maioria das obrigações de transferência transfronteiriça sob o Artigo 44.

O custo se acumula na outra direção. Uma equipe que executa 50 milhões de tokens de prompt por dia através do GPT-5.5 Instant paga aproximadamente US$ 250 por dia a US$ 5 por milhão de tokens. O mesmo volume em um estúdio M3 Max de US$ 4.500 se amortiza para zero após dezoito dias de utilização total, ignorando a eletricidade. Você pode ler uma análise desses números em Como usar o GPT-5.5 Instant e aplicar a mesma aritmética à sua própria carga de trabalho.

A terceira razão é o determinismo. Modelos hospedados mudam pesos sem o seu conhecimento. A página de depreciação de modelos do OpenAI lista onze aposentadorias de snapshots nos últimos doze meses. Um modelo local é um arquivo em disco. Ele produz os mesmos logits hoje e daqui a três anos. Essa estabilidade importa quando sua suíte de regressão depende da saída da LLM. O endpoint compatível com OpenAI mudou o jogo porque você não paga mais um imposto de integração por essa estabilidade. O SDK que você já usa funciona.

Três runtimes que entregam endpoints compatíveis com OpenAI

Quatro runtimes dominam o espaço da API LLM local em 2026. Três entregam um servidor REST compatível com OpenAI de imediato. O quarto, llama.cpp, entrega um como parte de seu binário llama-server. Escolha pela carga de trabalho, não pela popularidade.

Ollama

Ollama é o ponto de partida mais fácil. Um binário, uma CLI, um servidor HTTP na porta 11434. Ele é voltado para desenvolvedores que executam um único modelo em uma única máquina e cuida dos downloads de modelos, quantização GGUF e templating de prompts para você.

## install on macOS
brew install ollama
ollama serve &
ollama pull llama3.3:70b-instruct-q4_K_M
ollama run llama3.3:70b-instruct-q4_K_M

Uma vez que ollama serve esteja ativo, o endpoint compatível com OpenAI reside em http://localhost:11434/v1. Ele suporta chat, embeddings e streaming. O limite de throughput em um M3 Max com um modelo de 70B Q4_K_M é de cerca de 12 tokens por segundo. Modelos menores atingem de 80 a 120 tokens por segundo. Ollama é a escolha certa para desenvolvimento de usuário único, demonstrações e runners de CI.

vLLM

vLLM é a opção de nível de produção. Ele usa PagedAttention e batching contínuo para impulsionar o throughput duas a quatro vezes mais alto do que runners ingênuos. Ele serve na porta 8000 por padrão e expõe uma API compatível com OpenAI em /v1. Você pode ler os detalhes da arquitetura no artigo do vLLM na referência de Kwon et al. SOSP 2023 abaixo.

pip install vllm
vllm serve meta-llama/Llama-3.3-70B-Instruct \
  --port 8000 \
  --gpu-memory-utilization 0.9 \
  --max-model-len 8192

Em uma única H100, o vLLM serve o Llama 3.3 70B a aproximadamente 2.400 tokens por segundo em requisições concorrentes. Ele precisa de uma GPU CUDA ou uma placa AMD ROCm recente e não roda em Apple Silicon, o que o torna a escolha errada para laptops e a escolha certa para clusters de desenvolvimento compartilhados.

llama.cpp

llama.cpp é o runtime C++ que iniciou o ecossistema GGUF. Ele roda em qualquer lugar, desde Raspberry Pi 5 até rigs dual-RTX-5090. Seu binário llama-server "fala" o formato OpenAI em /v1/chat/completions.

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp && make -j LLAMA_METAL=1
./llama-server -m models/llama-3.3-70b-q4_k_m.gguf \
  --port 8080 --host 0.0.0.0 -c 8192 -ngl 99

A flag -ngl 99 descarrega todas as camadas para a GPU. llama.cpp oferece o maior controle sobre quantização, batching e mapeamento de memória. É a escolha certa quando você precisa encaixar um modelo em 16 GB de VRAM ou testar hardware exótico.

LM Studio e Jan envolvem o llama.cpp em uma GUI e também expõem um endpoint OpenAI em uma porta configurável. Eles são úteis para usuários não técnicos em sua equipe que precisam testar prompts sem tocar em um terminal.

Uma verificação Python simples para garantir que o endpoint funciona:

from openai import OpenAI
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
resp = client.chat.completions.create(
    model="llama3.3:70b-instruct-q4_K_M",
    messages=[{"role": "user", "content": "Reply with the word OK only."}],
)
print(resp.choices[0].message.content)

Se você vir OK, o runtime, a porta e o contrato do SDK correspondem. Você está pronto para conectar o endpoint às suas ferramentas.

Teste sua LLM local com Apidog

Uma API LLM local é útil apenas se sua suíte de testes puder acessá-la da mesma forma que acessa a produção. O Apidog lida com isso usando variáveis de ambiente no modelo de requisição, o que significa que um projeto cobre ambos os alvos.

O fluxo possui cinco etapas.

1. Abra seu projeto Apidog e crie um novo ambiente chamado Local. Adicione uma variável BASE_URL com o valor http://localhost:11434/v1. Adicione API_KEY com o valor ollama. Salve.
2. Clone seu ambiente OpenAI existente, renomeie-o para Production, mantenha BASE_URL como https://api.openai.com/v1 e API_KEY como sua chave hospedada.
3. Em qualquer requisição que chame um endpoint de chat, substitua o host hardcoded por {{BASE_URL}} e o cabeçalho de autenticação por Bearer {{API_KEY}}. A URL da requisição se tornará {{BASE_URL}}/chat/completions.
4. Crie um teste de cenário que dispara a requisição, afirma que choices[0].message.role == "assistant", afirma que choices[0].message.content não está vazio e afirma que usage.total_tokens > 0. Salve o cenário.
5. Execute o cenário contra Local. Mude o seletor de ambiente para Production. Execute novamente. As afirmações devem passar para ambos.

O mesmo cenário funciona como um teste de fumaça para atualizações de runtime. Após um ollama pull em uma nova tag, reexecute o cenário Local. Se o formato da resposta mudar, você o detecta antes que qualquer código de aplicação toque nos novos pesos. O padrão se estende a testar agentes de IA que chamam APIs multi-etapas.

Para uso programático, o SDK Python do OpenAI alterna os alvos com um único argumento de palavra-chave:

import os
from openai import OpenAI

def get_client():
    if os.getenv("ENV") == "local":
        return OpenAI(
            base_url="http://localhost:11434/v1",
            api_key="ollama",
        )
    return OpenAI(api_key=os.environ["OPENAI_API_KEY"])

client = get_client()
response = client.chat.completions.create(
    model=os.getenv("MODEL", "llama3.3:70b-instruct-q4_K_M"),
    messages=[
        {"role": "system", "content": "You are a JSON-only assistant."},
        {"role": "user", "content": "Return {\"status\": \"ok\"}."},
    ],
    response_format={"type": "json_object"},
)
print(response.choices[0].message.content)

O formato JavaScript reflete isso:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.ENV === "local"
    ? "http://localhost:11434/v1"
    : "https://api.openai.com/v1",
  apiKey: process.env.ENV === "local" ? "ollama" : process.env.OPENAI_API_KEY,
});

const resp = await client.chat.completions.create({
  model: process.env.MODEL || "llama3.3:70b-instruct-q4_K_M",
  messages: [{ role: "user", content: "Say hi." }],
});
console.log(resp.choices[0].message.content);

Conecte o executor de cenários do Apidog ao seu CI exportando o projeto como uma coleção apidog-cli e chamando apidog run no GitHub Actions. O executor retorna uma saída diferente de zero em caso de falha de asserção, o que falha a compilação no momento em que um contrato local ou hospedado se desvia. Engenheiros de QA podem integrar o mesmo fluxo em pipelines de teste de API existentes.

Técnicas avançadas e dicas profissionais

Quantização é a alavanca que decide se um modelo de 70B cabe no seu laptop. O formato GGUF armazena pesos em 8, 6, 5, 4, 3 ou 2 bits por parâmetro. Q4_K_M é o padrão por uma razão. Ele perde 0,6 pontos percentuais no benchmark MMLU versus FP16 e encolhe um modelo de 70B de 140 GB para 40 GB. Q8 o mantém dentro de 0,1 pontos do FP16, mas dobra o espaço em disco e a pegada de RAM. Q2_K economiza espaço, mas o impacto na perplexidade é visível em qualquer tarefa com contexto longo. Escolha Q4_K_M para chat, Q8 para geração de código e Q5_K_M quando você tem RAM e quer uma margem de segurança.

O descarregamento para GPU via a flag -ngl no llama.cpp ou a opção num_gpu no Ollama controla quantas camadas de transformadores residem na GPU. Defina-o o mais alto que sua VRAM permitir. Cada camada que retorna para a CPU diminui o throughput em aproximadamente 30 por cento. Em uma placa de 24 GB, um modelo de 70B Q4 cabe em 40 das 80 camadas. Em 48 GB, você pode encaixar toda a pilha.

O mapeamento de memória (mmap) está ativado por padrão no llama.cpp e no Ollama. Ele permite que o sistema operacional faça a paginação dos pesos sob demanda, em vez de alocar o modelo completo na inicialização. Mantenha-o ativado, a menos que você esteja executando em um contêiner com limites de memória rigorosos. Com mmap desativado, a latência do primeiro token diminui em cerca de 200 ms, mas o uso de RAM dobra.

Batching é o superpoder do vLLM. Envie 32 requisições concorrentes e o vLLM as agrupa em uma única passagem de GPU. O throughput escala quase linearmente até o limite de computação da GPU. Defina --max-num-seqs 64 para laptops com memória de CPU compartilhada e --max-num-seqs 256 para hardware de classe H100.

Respostas em streaming reduzem a latência percebida pela metade. Defina stream=True no SDK OpenAI e o servidor libera os tokens à medida que são gerados. O primeiro byte chega em 200 a 500 ms, em vez de esperar pela conclusão total. Todos os runtimes neste guia o suportam.

O Modelfile do Ollama permite que você incorpore um prompt de sistema, temperatura e sequências de parada em um modelo nomeado, para que o código da sua aplicação permaneça limpo. Execute ollama create my-assistant -f Modelfile uma vez e seu cliente apontará para my-assistant em vez de repetir o prompt do sistema em cada requisição.

Erros comuns

• Hardcodificar http://localhost:11434 no código de produção. Use uma variável de ambiente.
• Esquecer que modelos locais não impõem max_tokens. Eles gerarão alegremente 4.096 tokens desnecessários. Defina uma sequência de parada.
• Executar Ollama e outro runtime na mesma porta. Ambos têm portas padrão limpas, mas portas personalizadas colidem silenciosamente.
• Ignorar o cabeçalho Authorization. Ollama o ignora, mas vLLM com --api-key rejeitará requisições não autenticadas com um 401.
• Carregar um modelo Q4 e esperar a qualidade do GPT-5.5 em matemática. A quantização corrói o raciocínio mais rapidamente.

Local vs. hospedado: matemática de custo e latência

Os números abaixo assumem um M3 Max com 128 GB de memória unificada para uso local, e preços públicos atuais para endpoints hospedados. O Tempo para o Primeiro Token (TTFT) é medido a frio, sem batching, em um prompt de 1.024 tokens.

A coluna hospedada sempre vence em latência. A coluna local vence em custo no momento em que você ultrapassa aproximadamente 10 milhões de tokens por dia, e vence em privacidade desde a primeira requisição. Para desenvolvimento, você quase sempre vai querer o local. Para produção voltada para o usuário, você quase sempre vai querer o hospedado, a menos que sua classificação de dados o proíba.

Um padrão prático: execute localmente durante o ciclo de desenvolvimento interno, mude para hospedado no staging, mantenha ambos os alvos verdes no CI. Os testes de cenário Apidog da seção acima suportam esse padrão com uma única alternância de ambiente. Para benchmarks mais aprofundados em modelos individuais, consulte Como executar o DeepSeek V4 localmente e o guia de uso original do DeepSeek V4.

Casos de uso no mundo real

Uma equipe de conformidade de fintech em Singapura usa Ollama em laptops de engenheiros para redigir relatórios de atividades suspeitas. Os prompts contêm números de conta e padrões de transação que não podem sair do país sob as regras da MAS. O endpoint hospedado que eles usam em produção recebe uma versão redigida do mesmo prompt. Os cenários do Apidog garantem que o redator é executado em cada requisição antes de sair do localhost.

Um estúdio de jogos em Estocolmo treina estagiários de design em engenharia de prompt com uma instância local do Qwen 3.6. Grátis, offline e impossível de vazar a história do próximo jogo para terceiros. O mesmo projeto é implantado contra o Gemini 3 Flash em produção com uma única alteração de variável de ambiente. Eles reutilizam o guia da API Gemini 3 Flash para a conexão de produção.

Uma startup de saúde executa vLLM em uma A100 alugada dentro da rede hospitalar do cliente. O endpoint nunca vê DNS público. Seus testes de integração são executados a partir de um agente Jenkins na mesma VLAN contra o mesmo SDK OpenAI que eles usam localmente. Mesmo código, três alvos de implantação, uma suíte de cenários.

Conclusão

A pilha da API LLM local amadureceu rapidamente. Você pode mover seus prompts de um endpoint hospedado sem reescrever seu cliente, seus testes ou seu CI. Os cinco passos que tornam isso real:

• Escolha Ollama para laptops, vLLM para clusters de desenvolvimento compartilhados, llama.cpp para orçamentos de memória restritos.
• Exponha o endpoint compatível com OpenAI e verifique com um curl de uma linha.
• Mova base_url e api_key para variáveis de ambiente para que o mesmo código atinja ambientes locais e hospedados.
• Crie testes de cenário no Apidog que rodam identicamente em ambos os ambientes.
• Observe a tabela de custo vs. latência e escolha o alvo certo por carga de trabalho.

O sinal do HN que impulsionou “A IA Local precisa ser a norma” para mais de 1.700 pontos é um resultado dessa maturidade. Uma vez que a superfície da API se estabilizou, todas as ferramentas de desenvolvimento se adaptaram a ela. Baixe o Apidog e aponte um ambiente para http://localhost:11434/v1 para ver quão rápido o ciclo se fecha. Se você ainda não escolheu um modelo, comece com Melhores LLMs locais 2026, e se quiser um aprofundamento sobre como testar fluxos agentic sobre qualquer um desses endpoints, leia Como testar a API de agentes de IA.