CH 16 · Deploy Local e Liberdade de Token

Número de palavras~3.650 palavrasTempo~25 minPré-requisitoCH 06 (Custom Provider)NívelReproduzível

Objetivo do capítulo

Em todos os capítulos anteriores, você estava chamando a API oficial da DeepSeek — útil, mas cobrada por token, e sessões de Agent em particular comem muitos tokens (todo resultado de ferramenta precisa ser devolvido ao contexto). E isso não é só um problema da DeepSeek: contanto que você passe por uma API na nuvem, seja oficial ou de terceiros, você não escapa da cobrança por token.

Este capítulo te dá um caminho completamente diferente: deploy local. Baixe um modelo open-source para o seu próprio computador e rode; toda a inferência não passa por nenhum servidor de terceiros — sem fatura de token, verdadeira "Liberdade de Token".

O método que você já aprendeu no CH 06: o dsh só reconhece "endpoints compatíveis com OpenAI", e o modelo é uma configuração, não um vínculo. Este capítulo aplica essa capacidade a um cenário real — deixe o dsh rodar no seu próprio modelo.

Como deploy local difere da nuvem

Primeiro esclareça "por que deploy local é grátis". Quando você usa a API oficial da DeepSeek, prompts, resultados de ferramentas e conteúdo de arquivos são todos enviados para o servidor dela, que usa a própria GPU para inferência, e depois cobra por token. Toda API na nuvem é assim: o compute pertence a outra pessoa, e a fatura segue os tokens.

Deploy local é o oposto: o modelo é baixado para o seu computador, a inferência roda na sua própria GPU/CPU, nenhum servidor de terceiros está envolvido. O compute é seu, a eletricidade é sua, então naturalmente não há cobrança por token — é isso que "Liberdade de Token" realmente significa.

Dimensão	API na nuvem (ex. DeepSeek oficial)	Deploy local (LM Studio rodando modelo open-source)
Cobrança	Por token	Grátis (só custo de eletricidade)
Rede	Precisa conectar à internet	Pode ser totalmente offline
Dados	Enviados para o servidor do provedor	Ficam na sua máquina
Capacidade	Modelo flagship, mais forte	Depende de quão grande um modelo sua GPU consegue rodar
Custo de entrada	Zero, registre-se e você tem uma Key	Instalar software, baixar modelo (vários GB)

A marca do deploy local em uma frase: grátis, offline, privado, mas a capacidade é limitada pelo seu hardware — quanto mais forte sua GPU, maior o modelo que você consegue rodar, melhor o resultado.

Princípio: modelo é configuração

Por que o dsh consegue trocar de modelos à vontade é o plugin de roteamento de modelo llm-pi-ai: ele trata o "provedor de modelo" como uma configuração YAML; qualquer endpoint que exponha o protocolo OpenAI Chat Completions (ou seja, /v1/chat/completions) pode ser conectado como um provider. Trocar de modelo = trocar uma configuração, sem precisar mudar o dsh em si.

Então deploy local e conexão com a API oficial, o método é o mesmo do CH 06, apenas com um endereço de endpoint diferente:

Direção	Base URL	Key	Modelo típico
DeepSeek oficial (nuvem)	https://api.deepseek.com	Key oficial	deepseek-v4-flash etc.
LM Studio local	http://localhost:1234/v1	Qualquer coisa (local ignora)	Qwen3 8B etc.

Conecte um modelo local: onboarding com LM Studio

Passo 1: instale o LM Studio, baixe um modelo

Runners de modelo local não são apenas um: se você é familiar com Ollama, também pode usar Ollama direto (onboarding por linha de comando, o método de configuração é idêntico ao abaixo). Este capítulo usa LM Studio uniformemente para a demo — com interface gráfica, o mais amigável para iniciantes.

O LM Studio suporta Windows / macOS / Linux; vá ao site do LM Studio para baixar o instalador. Depois de instalar, não tente adivinhar qual modelo baixar, deixe isso para o dsh — ele vai checar o ambiente do seu computador e então recomendar para você. Mande isso na caixa de entrada da Web UI:

Cheque a GPU e VRAM do meu computador, estime em quantização Q4 qual o tamanho de modelo local que dá para rodar confortavelmente; recomende 2~3 modelos adequados para Agent local (precisa suportar tool calling), dê nomes de modelos que podem ser pesquisados diretamente na caixa de busca do LM Studio, cada um com uma frase de razão. Apenas consultar e recomendar, nenhuma outra operação.

O dsh vai ler a sua GPU e listar alguns nomes específicos de modelos. Pegue os nomes e pesquise no LM Studio.

Abra o LM Studio: Settings canto inferior esquerdo → Explorer, na caixa de busca pesquise pelo nome do modelo que o dsh recomendou. Marcado com label verde (indicando compatível com seu hardware, offload total de GPU) nos resultados da busca é o que sua máquina consegue rodar, basta clicar para baixar.

Um lembrete imutável: para modelos locais rodando um Agent, a capacidade de tool calling é mais importante que pontuações de benchmark — o modelo precisa ser capaz de seguir instruções para chamar ferramentas, senão o Agent não consegue girar.

Passo 2: abra o Local Server, confirme que o endpoint está vivo

Depois que o modelo for baixado, no LM Studio Settings canto inferior esquerdo → Local Models → Local Model API (Local Server), ative o switch Local API server. Por padrão ele escuta em http://localhost:1234, e o endpoint compatível com OpenAI está em /v1 — a página mostrará diretamente a base URL http://localhost:1234/v1; quando vir "running" o servidor está no ar.

Abra no navegador:

http://localhost:1234/v1/models

Se vir um JSON listando seu modelo baixado, o endpoint está ok. Esta etapa também deixa você ver o ID exato de cada modelo (use o que foi retornado aqui; por exemplo, o Gemma 4 E2B que baixei aparece como gemma-4-e2b-it-qat), que você precisará preencher na configuração depois.

Parâmetros do modelo na Resource Library

Quer ver com quais parâmetros o modelo roda? Settings canto inferior esquerdo → Local Models → Resource Library, encontre seu modelo, clique no botão Settings ao lado direito, e a página "Model Default Settings" vai abrir:

É dividido em três seções: Prompt, Context & Performance, Generation. Automatic Optimize Based on Hardware (RECOMMENDED) está ligado por padrão; comprimento de contexto, GPU offload etc. estão todos AUTO — o LM Studio vai ajustá-los baseado no seu computador. A demo deste capítulo usa todos os defaults, não precisa mudar nenhum; volte aqui depois se quiser ajustar.

Passo 3: adicione um "Custom Provider" no dsh

Seguindo o método 2 do CH 06: Settings → Models → Add Custom Provider, preencha:

Campo	O que preencher
Provider ID	lm-studio-local (minúsculas)
Endereço da API	http://localhost:1234/v1
Protocolo da API	OpenAI Chat Completions compatível
Key	Preencha qualquer coisa (local não valida, lm-studio serve como placeholder)
Modelo	O ID completo de /v1/models no passo anterior

Efeito e gestão de expectativas

• Benefícios: completamente offline, zero taxas de API, código e docs ficam na sua máquina — para cenários sensíveis à privacidade, o modelo local é a única escolha.
• Realidade: um modelo local pequeno é para "rodar pelo loop", não para trabalho pesado. Agents em particular comem tool calling e contexto longo; modelos pequenos têm mais chance de errar chamadas de ferramenta e planejar mal do que modelos flagship. É muito adequado para testes durante o desenvolvimento de plugins; para trabalho real, volte para um modelo na nuvem.

O Gemma 4 E2B deployado nesta demo é um modelo de visão (Google oficial: E2B tem um encoder de visão, suporta entrada de imagem) — mas para ele realmente receber imagens e fazer OCR no dsh, é necessária mais uma declaração: o custom provider do dsh trata como texto plano por padrão; sem a declaração, imagens são rejeitadas como entrada inválida (coberto no CH 06). Como fazer: na janela de settings do dsh clique no canto superior direito em Open config file, encontre llm-pi-ai.providers.lm-studio-local.models e o modelo correspondente, adicione uma linha input: [text, image]:

llm-pi-ai:
  providers:
    lm-studio-local:
      apiKeyEnv: LM_STUDIO_API_KEY
      api: openai-completions
      baseURL: http://localhost:1234/v1
      models:
        - id: gemma-4-e2b-it-qat
          input: [text, image]

Depois de salvar, reinicie a sessão, mande uma imagem para ele e ele consegue fazer OCR.

Tool calling também funciona: na demo mandei "crie um arquivo txt dizendo quem você é", e o modelo realmente chamou a ferramenta write — errou e tentou de novo algumas vezes, e por fim escreveu com sucesso identity.txt. Isso prova que o modelo local consegue realmente rodar o loop de ferramentas do dsh, não só conversar; só não é tão estável quanto o flagship, com mais erros.

Local ou nuvem: como escolher

Cenário	Escolha
Trabalho diário, quer o melhor resultado	API na nuvem (por token, fácil)
Tarefas diárias simples, ex. o briefing de hot-topics agendado com aihot antes	Modelo local LM Studio (offline, grátis)

Eles não são mutuamente excludentes: o dsh pode ter vários providers montados ao mesmo tempo, e você pode trocar numa nova sessão à vontade. Quando sensível ao custo, roteie sessões diárias para flash e deixe o trabalho pesado para pro — a postura mais simples de economia; o modelo local sustenta cenários de teste e privacidade.

Armadilhas comuns

Armadilha	Como evitar
Base URL digitada errada	Endpoints compatíveis com OpenAI geralmente terminam em /v1; primeiro abra GET {baseURL}/models no navegador para verificar
Variável de ambiente da Key não definida	apiKeyEnv apenas referencia, não cria; confirme que o ambiente no qual o dsh inicia consegue realmente ler essa variável
Model ID não bate	Modelos locais precisam usar o ID completo retornado por /v1/models (vendor/model-name), não preencha com base na memória
Erro de imagem, diz que não suporta OCR	O modelo do custom provider é tratado como texto plano por padrão — mesmo que o modelo em si suporte OCR, é preciso adicionar input: [text, image] na config do provider
Modelo local continua errando tool calls	Não é problema de configuração, é o limite de capacidade do modelo pequeno — volte para modelos na nuvem ou troque por um modelo local maior

O que você aprendeu neste capítulo

• [ ] Dizer "modelo é configuração": o dsh só reconhece endpoints compatíveis com OpenAI, trocar modelo = trocar uma configuração de provider
• [ ] Dizer a diferença essencial entre deploy local e API na nuvem: por que é grátis (compute é seu), offline, dados ficam na sua máquina
• [ ] Saber como usar o LM Studio para baixar um modelo, ativar o servidor local, e confirmar que localhost:1234/v1/models está vivo
• [ ] Saber como adicionar o custom provider lm-studio-local no dsh e rodar com sucesso uma sessão local
• [ ] Saber que modelos de visão precisam de input: [text, image], saber que modelos locais pequenos são adequados para testes não para trabalho pesado