CH 06 · Configurar Modelo e Nível de Raciocínio

Tamanho~4.000 palavrasTempo~15 minPré-requisitoCH 03 já em execuçãoNívelReproduzível

Objetivo do Capítulo

Configure corretamente os dois botões "qual modelo" e "quanto pensar": primeiro entenda as três coisas que uma chamada de modelo precisa (API Key / Base URL / Model ID), depois leia o arquivo de configuração, mude o modelo padrão, ajuste o reasoning effort e, finalmente, aprenda a conectar modelos de terceiros.

Primeiro Entenda Três Conceitos: API Key / Base URL / Model ID

Independentemente da ferramenta que você use para chamar um grande modelo, uma requisição carrega três coisas — API Key (quem você é), Base URL (para onde ir), Model ID (qual modelo usar):

Vamos detalhar um por um:

• API Key: uma string com prefixo sk-, seu "documento de identidade" em uma plataforma de modelo. A requisição a carrega para que a plataforma saiba quem você é e em qual conta cobrar. É uma senha — não vaze, não faça commit em um repositório Git. Observação: o prefixo sk- é um formato comum em todo o ecossistema compatível com OpenAI; DeepSeek e muitas plataformas nacionais e gateways auto-construídos seguem esse formato.
• Base URL: o "endereço" do modelo, ou seja, o endpoint do serviço de API. Todas as requisições vão para esse endereço.
• Model ID: o nome do modelo, especificando exatamente qual usar. Se a requisição diz deepseek-v4-flash-vision-exp, você usa a versão de visão; deepseek-v4-pro é o flagship.

Esses três valores vêm todos da própria plataforma de modelo, não são inventados pelo dsh. Tomando DeepSeek como exemplo, como obtê-los:

1. API Key: abra a DeepSeek Open Platform, registre-se e faça login, vá em Console → API Keys → Create API key, nomeie e clique em criar, imediatamente copie e salve — a chave é mostrada por completo apenas no momento da criação, depois disso a página mostra apenas um descritor mascarado.
2. Base URL: os documentos oficiais da DeepSeek declaram claramente que o endpoint compatível com OpenAI é https://api.deepseek.com (o endpoint compatível com Anthropic é https://api.deepseek.com/anthropic).
3. Model ID: encontre na lista de modelos nos documentos da API oficial; são os mesmos que você viu no seletor de modelo (deepseek-v4-pro / deepseek-v4-flash / deepseek-v4-flash-vision-exp).

Quando você conectar modelos de terceiros mais tarde, vai descobrir que são as mesmas três coisas — apenas com valores diferentes.

Onde Está o Arquivo de Configuração: $DSH_HOME/settings.yaml

A configuração global do dsh é um único arquivo: C:\Users\<seu-usuário>\.dsh\settings.yaml. Na minha máquina ele se parece com isto:

ui-onboarding:
  welcomeNoticeVersion: 2026-08-13.1
agent-default-model:
  provider: deepseek-official
  model: deepseek-v4-flash-vision-exp
  reasoningEffort: high

Este arquivo é o ponto de aterrissagem para mudanças de modelo e reasoning effort que você fizer na Web UI — tudo o que você mudar na UI acaba sendo gravado aqui. Cada um dos três campos cuida de uma coisa:

Campo	Função	Meu valor
provider	Por qual provider rotear	deepseek-official (DeepSeek oficial)
model	Modelo padrão para novas sessões	deepseek-v4-flash-vision-exp
reasoningEffort	Reasoning effort padrão	high

Como Escolher Entre os Três Modelos

O adapter oficial DeepSeek publica três modelos por padrão, cada um com janela de contexto de 1M tokens:

Model ID	Posicionamento
deepseek-v4-pro	Flagship, tarefas complexas e críticas em qualidade, mais capaz, porém mais caro
deepseek-v4-flash	Rápido, econômico, para tarefas diárias
deepseek-v4-flash-vision-exp	Versão de visão: consegue ler imagens, ver screenshots; no mesmo nível do flash para texto puro

Um detalhe: o Model ID é passado para o protocolo como está, então quando a equipe oficial lança novos modelos, você não precisa re-registrar — basta preencher o novo ID na configuração.

Reasoning Effort: off / low / high / max

Reasoning effort decide quanto o modelo "pensa" antes de agir. O modelo oficial DeepSeek tem quatro níveis. Na Web UI, clique no botão de modelo à direita da caixa de entrada para ver e alternar entre esses quatro níveis (teste local, High é o padrão marcado):

Nível	Comportamento
off	Desativa pensamento (thinking: disabled), mais rápido e barato
low	Pensamento leve
high (padrão)	Raciocínio profundo, adequado para tarefas de Agent
max	Intensidade máxima de pensamento, apenas para o trabalho mais difícil

O padrão oficial é high. O nível afeta diretamente tempo e custo: um nível com pensamento habilitado é ligeiramente mais lento e mais caro, porém mais confiável em tarefas complexas; off não pensa, então Q&A simples volta instantaneamente. Escolher um nível tem um princípio — quanto mais difícil a tarefa, mais alto o nível.

Como Mudar: Web UI ou Editar o Arquivo

Ambos os caminhos terminam em settings.yaml:

• Web UI: Settings → Models. Armazene chaves, veja modelos configurados, adicione providers. O modelo escolhido no seletor de modelo torna-se o padrão para novas sessões; sessões que já enviaram requests manterão o modelo que estavam usando quando iniciaram, e não mudarão com o padrão.

• Editar o arquivo diretamente: mude os três campos em agent-default-model, ou adicione uma seção llm-deepseek: para sobrescrever mais campos (usado depois ao configurar um custom provider).

Regra de efetivação: mudanças entram em vigor no próximo request, sem necessidade de reiniciar o serviço.

Configurar Modelos de Terceiros

O que acabamos de cobrir é a configuração oficial DeepSeek. É exatamente aqui que o dsh mostra um recurso distintivo: conecte qualquer modelo, sem ficar preso ao próprio. O adapter oficial apenas usa DeepSeek como padrão; você pode conectar completamente Anthropic, OpenAI, qualquer gateway compatível com OpenAI, até mesmo modelos locais. Em contraste, produtos como Codex estão limitados a um conjunto fixo de modelos; para trocar de provider você precisa esperar a equipe oficial abrir. No dsh, há duas formas de conectar um terceiro.

Método Um: Adicionar um Provider (Usar Diretório Existente)

A página Settings → Models tem uma entrada Add Provider, onde você encontra um lote de "diretórios" oficiais — escolha Anthropic, OpenAI ou outro diretório existente; o endpoint e o protocolo já estão configurados. Depois de adicionar, siga o formulário de três passos:

1. Escolha o provider: clique no dropdown "Provider" e escolha o provider que você quer conectar (por exemplo, minimax-cn).
2. Preencha a API key: cole a Key daquela plataforma na caixa "API Key" — exibição mascarada, apenas escrita.
3. Buscar modelos disponíveis: clique em "Fetch available models" para puxar o diretório de modelos dele, depois você pode escolher o Model ID dele da lista.

Depois de salvar, os modelos do provider aparecem no seletor de modelo para uso normal.

Método Dois: Adicionar um Custom Provider (Seu Próprio Gateway / Modelo Local)

Se o dsh não pré-instala a plataforma que você usa, use Add Custom Provider. As coisas a preencher são exatamente as três do início deste capítulo mais uma:

Campo	O que é	Exemplo
Provider ID	Um ID único para este provider (minúsculas, permanente uma vez definido)	my-gateway
API address	A Base URL, o endereço do serviço de modelo	https://your-gateway-address
API protocol	Em qual formato falar (compatível com OpenAI / Anthropic, etc.)	openai-completions
Key	A API Key, a credencial de autenticação	sk-...
Model	Preencha pelo menos um Model ID	deepseek-v4-flash

Depois de salvar, este custom provider aparece na lista de modelos para uso normal. Algumas observações:

• Provider ID é permanente uma vez definido, não mude por capricho; configurações posteriores o referenciam.
• Para modelos locais / gateways auto-construídos, aponte o API address para o seu próprio serviço e preencha a chave do serviço local no campo key (ou deixe um placeholder conforme seus requisitos).
• Se o seu modelo customizado é um modelo de visão (recebe imagens), preencher apenas o Model ID não é suficiente — o requisito oficial é declarar adicionalmente que ele suporta entrada de imagem. Em settings.yaml, adicione uma linha input: [text, image] para aquele provider, caso contrário as imagens serão rejeitadas como entrada inválida.

Chaves e Credenciais

Por trás do card de Key que você preencheu (CH 03) há dois mecanismos:

• A chave é apenas escrita: depois de salvar em Settings → Models, a página mostra apenas um descritor mascarado, o texto puro só vai para C:\Users\<seu-usuário>\.dsh\.credentials.yaml, e settings.yaml armazena apenas uma referência de credencial, nunca o texto puro.
• Ordem de resolução: no momento da requisição, o credential store é verificado primeiro, depois a variável de ambiente (padrão DEEPSEEK_API_KEY) é usada como fallback. Se nenhum dos dois tiver, você recebe MISSING_CREDENTIAL.

Cheatsheet de Resolução de Problemas

Há apenas um punhado de erros relacionados à configuração; encontre o seu:

Erro	Significado	Resolução
MISSING_CREDENTIAL	Nenhuma chave configurada	Vá até a página Models para armazenar uma chave, ou configure a variável de ambiente que ela referencia
INVALID_CREDENTIAL	Formato da chave está errado	Verifique a Key que você preencheu
UNKNOWN_MODEL	Modelo não existe ou não está configurado	Escolha um modelo configurado
UNSUPPORTED_REASONING_EFFORT	Reasoning effort não suportado	Use um entre off / low / high / max
Fetch available models retorna 401	A chave está errada	Verifique a chave; a descoberta de modelos chama o endpoint OpenAI-compatível GET /models

O que você aprendeu neste capítulo

Você passa se conseguir completar os itens abaixo:

• [ ] Explicar os três conceitos API Key / Base URL / Model ID, e onde obtê-los (usando DeepSeek como exemplo)
• [ ] Indicar a localização de settings.yaml e o que os três campos em agent-default-model significam
• [ ] Indicar o posicionamento de cada um dos três Model IDs DeepSeek
• [ ] Indicar os quatro valores de reasoning effort (off / low / high / max) e o padrão, e o princípio para escolher um
• [ ] Saber que após mudar o modelo/esforço, ele entra em vigor no próximo request, sem necessidade de reiniciar
• [ ] Conhecer as duas formas de conectar modelos de terceiros: adicionar um Provider (diretório existente, preencha sua chave, use seu Model ID) vs adicionar um Custom Provider (Provider ID / API address / protocolo / chave / modelo)
• [ ] Saber onde as chaves são armazenadas e por que settings não armazena texto puro
• [ ] Usar a tabela de resolução de problemas para localizar erros como MISSING_CREDENTIAL e UNKNOWN_MODEL