msd-core/docs/pt-BR/how-to/configure-model-profiles.md

Como configurar perfis de modelo

Escolha a estratégia de nível de modelo adequada para o seu projeto e ajuste agentes individuais ou tipos de fase inteiros sem precisar escrever um bloco de substituição extenso. Este guia começa pelo controle mais simples e avança até o roteamento dinâmico.

---

Os quatro perfis (mais adaptive e inherit)

Defina model_profile em .planning/config.json ou via /gsd-config --profile <name>:

Perfil	Planejador	Executor	Pesquisadores	Verificador	Usar quando
quality	Opus	Opus	Opus	Sonnet	Trabalho de qualidade para produção onde o custo é secundário
balanced	Opus	Sonnet	Sonnet	Sonnet	Desenvolvimento normal — o padrão
budget	Sonnet	Sonnet	Haiku	Haiku	Prototipagem rápida, contextos com restrições de custo
adaptive	Opus	Sonnet	Sonnet	Sonnet	Resolve da mesma forma que os outros níveis em perfis cientes de runtime; use ao alternar entre runtimes com frequência
inherit	(modelo da sessão)	(modelo da sessão)	(modelo da sessão)	(modelo da sessão)	Provedores não-Anthropic (OpenRouter, modelos locais) — todos os agentes seguem o modelo atual da sessão

A tabela acima mostra um subconjunto representativo. Todos os 33 agentes incluídos possuem atribuições de nível explícitas por perfil em sdk/shared/model-catalog.json. Para a tabela completa, consulte Perfis de Modelo na referência de configuração.

Troca rápida via comando:

/gsd-config --profile balanced   # Desenvolvimento normal
/gsd-config --profile budget     # Prototipagem ou fases de alto custo
/gsd-config --profile quality    # Lançamento em produção
/gsd-config --profile inherit    # OpenRouter, modelos locais

Ou edite .planning/config.json diretamente:

{
  "model_profile": "balanced"
}

---

Substituições por agente (model_overrides)

Se um único agente precisa de um nível diferente sem alterar o perfil inteiro, use model_overrides:

{
  "model_profile": "balanced",
  "model_overrides": {
    "gsd-executor": "opus",
    "gsd-codebase-mapper": "haiku"
  }
}

Valores válidos: opus, sonnet, haiku, inherit ou qualquer ID de modelo totalmente qualificado (ex.: "openai/o3", "google/gemini-2.5-pro").

model_overrides pode ser definido por projeto em .planning/config.json ou globalmente em ~/.gsd/defaults.json. Entradas por projeto têm precedência em conflitos; entradas globais sem conflito são preservadas.

Importante para Codex e OpenCode: Esses runtimes incorporam o modelo resolvido na configuração estática de cada agente no momento da instalação. Após editar model_overrides, execute novamente o instalador para que a alteração entre em vigor:

npx @opengsd/gsd-core@latest --codex --global   # ou --opencode, --kilo, etc.

---

Modelos por tipo de fase (models)

Se você quer dizer "Opus para planejamento, Sonnet para todo o resto" sem precisar aprender todos os 33 nomes de agentes, use o bloco models. Ele mapeia seis tipos de fase para aliases de nível:

{
  "model_profile": "balanced",
  "models": {
    "planning":      "opus",
    "discuss":       "opus",
    "research":      "sonnet",
    "execution":     "opus",
    "verification":  "sonnet",
    "completion":    "sonnet"
  }
}

Tipos de fase e seus agentes:

Tipo de fase	Agentes cobertos
planning	gsd-planner, gsd-roadmapper, gsd-pattern-mapper
research	gsd-phase-researcher, gsd-project-researcher, gsd-research-synthesizer, gsd-codebase-mapper, gsd-ui-researcher
execution	gsd-executor, gsd-debugger, gsd-doc-writer
verification	gsd-verifier, gsd-plan-checker, gsd-integration-checker, gsd-nyquist-auditor, gsd-ui-checker, gsd-ui-auditor, gsd-doc-verifier
discuss, completion	Reservado — nenhum subagente hoje; aceito pelo esquema para compatibilidade futura

O bloco models aceita apenas aliases de nível (opus, sonnet, haiku, inherit). Para um ID de modelo totalmente qualificado, use model_overrides por agente.

Combinando models com uma exceção por agente:

{
  "model_profile": "balanced",
  "models": {
    "research": "sonnet"
  },
  "model_overrides": {
    "gsd-codebase-mapper": "haiku"
  }
}

Todos os cinco agentes de pesquisa resolvem para sonnet exceto gsd-codebase-mapper, que está fixado em haiku.

---

Roteamento dinâmico — comece barato, escale em caso de falha

Se você quiser pagar pelos níveis mais baratos por padrão e só escalar quando um agente falhar em um controle de qualidade, habilite dynamic_routing:

{
  "dynamic_routing": {
    "enabled": true,
    "tier_models": {
      "light":    "haiku",
      "standard": "sonnet",
      "heavy":    "opus"
    },
    "escalate_on_failure": true,
    "max_escalations": 1
  }
}

Cada agente possui um nível padrão (light, standard ou heavy). Na primeira tentativa, o GSD escolhe tier_models[default_tier]. Se o orquestrador detectar uma falha suave (verificação inconclusiva, verificação de plano sinalizada, etc.), ele reinicia o agente um nível acima. max_escalations limita o total de novas tentativas.

Agentes que já estão em heavy não podem escalar mais.

Desativar a escalada mantendo a resolução dinâmica:

{
  "dynamic_routing": {
    "enabled": true,
    "escalate_on_failure": false
  }
}

Cada tentativa usa tier_models[default_tier] independentemente do resultado — útil quando você quer mapeamento explícito de nível para modelo sem o comportamento de escalada.

dynamic_routing está desabilitado por padrão. Omitir o bloco ou definir enabled: false preserva a resolução estática.

---

Usando o GSD em runtimes não-Anthropic

Se você instalou o GSD para Codex, OpenCode, Gemini CLI ou Kilo, o instalador já definiu resolve_model_ids: "omit" na sua configuração. Isso instrui o GSD a pular a resolução de IDs de modelo Anthropic e deixar o runtime escolher seu próprio modelo padrão. Nenhuma configuração manual é necessária para o caso básico.

Se você quiser modelos por nível no Codex:

{
  "runtime": "codex",
  "model_profile": "balanced"
}

O GSD resolve cada alias de nível para o modelo nativo do Codex e o esforço de raciocínio definido no mapa de nível do runtime.

Se você quiser IDs de modelo por agente em qualquer runtime não-Claude:

{
  "resolve_model_ids": "omit",
  "model_overrides": {
    "gsd-planner":   "o3",
    "gsd-executor":  "o4-mini",
    "gsd-debugger":  "o3"
  }
}

Para a referência completa de perfis cientes de runtime e a superfície model_policy (predefinições neutras em relação ao provedor adicionadas na v1.42), consulte Referência de configuração — Perfis de Modelo.

---

Precedência de resolução (maior para menor)

Quando múltiplas camadas se aplicam, o resolvedor escolhe a entrada de maior prioridade:

1. model_overrides[<agent>]           — por agente; IDs completos; exceção direcionada
2. dynamic_routing.tier_models[<tier>] — quando habilitado; escala em falha suave
3. models[<phase_type>]               — nível de fase grosseiro
4. model_profile (coluna por agente)  — estratégia global de nível
5. Padrão do runtime                  — quando nada mais se aplica

---

Escolhendo o controle certo

O que você quer	Use
Uma estratégia de nível para todos os agentes	model_profile
Ajuste grosseiro por fase ("Opus para planejamento")	models.<phase_type>
Precisão por agente ("forçar Haiku no mapeador de base de código")	model_overrides[<agent>]
Um ID de modelo totalmente qualificado para um agente específico	model_overrides[<agent>]: "openai/gpt-5"
Começar barato, escalar apenas em falha	dynamic_routing
Todos os agentes seguem o modelo da sessão (provedor não-Anthropic)	model_profile: "inherit"

---

Relacionados

• Referência de configuração
• Orquestração multi-agente
• Referência de comandos
• Índice da documentação