Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Boas práticas de roteamento entre vários modelos

Status: Ativo Escopo: público, estado atual Última revisão: 2026-09-13 Responsável: ax-code runtime

Este guia registra a forma recomendada de executar o ax-code com um modelo premium de raciocínio e modelos auxiliares mais baratos do mesmo provedor.

Princípio central

Use o modelo caro para trabalho denso em raciocínio, e modelos baratos para trabalho mecânico ou somente leitura. A economia real vem da filtragem de contexto: o modelo premium só vê contexto destilado, preparado por modelos mais baratos ou por subagentes.

Divisão recomendada de camadas

Fixe IDs provider/model que estejam conectados. IDs de plano de primeira parte desativados (alibaba-token-plan, deepseek, zai-coding-plan, minimax-coding-plan) ainda resolvem por SKU, mas cada chamada tenta primeiro o provedor desativado e avisa. Qwen 3.8 Max é uma escolha explícita válida, não o padrão do produto nem do exemplo; sem config.model, o padrão implícito percorre os catálogos conectados nesta ordem: deepseek-flash, glm-5.3-flash, qwen3.8-flash, MiniMax-M3, grok-4.6, claude-sonnet-5, gpt-6, gemini-3.8-flash, qwen3.8-27b.

Modelo de configuração

Veja ax-code.json.example na raiz do repositório para um padrão concreto de DeepSeek Flash, com Pro nos agentes de raciocínio.

Modelos auxiliares da CLI do Codex

A disponibilidade de modelos do Codex depende do método de entrada da conta e do cliente, não apenas do texto do catálogo ou das capacidades de ferramenta. Por isso o AX Code não infere um modelo pequeno codex-cli a partir de nomes ou de metadados de família. Sem um modelo explícito small_model ou de agente de compactação, a compactação usa o modelo da sessão.

Se você configurar um modelo auxiliar, verifique se ele funciona com o mesmo login do Codex. Uma rejeição explícita do Codex, de que um modelo não tem suporte numa conta ChatGPT, permite que a compactação tente o modelo da sessão uma vez, pulando outros modelos pequenos. A tentativa rejeitada permanece no histórico da sessão. Outras falhas de autenticação, cobrança, validação, cancelamento e estouro de contexto conservam o tratamento existente; a proteção de privacidade do provedor local continua valendo.

Numa instalação mais antiga afetada, remova uma substituição incompatível de small_model ou de agent.compaction.model e fixe de forma explícita agent.compaction.model num modelo já verificado com essa conta do Codex. Mudar só o modelo visível da sessão não substitui um modelo de compactação fixado à parte.

Regras de roteamento automático por tipo de tarefa

Não encaminhe de forma automática todas as tarefas de baixo valor para um modelo barato. Separe-as pelo custo da falha:

• Seguro encaminhar sozinho (somente leitura ou revisável por uma pessoa):
  • exploração do repositório, triagem de grep e de busca, classificação de arquivos
  • resumo de código, resumo de log, explicação de código
  • preparar contexto para o modelo premium
  • documentação
• Somente com opção explícita (verificável de forma mecânica, mas pode esconder mudanças de comportamento):
  • código repetitivo, correções de lint
• Nunca encaminhar sozinho por padrão (erros silenciosos saem caros):
  • testes de unidade
  • renomear e refatorar
  • SQL simples
  • invólucro de API
  • CRUD simples

O último grupo deve permanecer no modelo da sessão, a menos que o usuário fixe de forma explícita um modelo mais barato.

Manual de operação

1. Comece tarefas não triviais no modo plan, para que o conselheiro valide o desenho antes de o trabalhador escrever código.
2. Se o trabalhador entrar em laço ou falhar na verificação duas vezes, mude para debug com o sinal da falha.
3. Use council para um diagnóstico independente quando duas correções forem plausíveis, não para terminar a tarefa.
4. Reserve trocas manuais de modelo para turnos raros e pesados em raciocínio; volte depois.

Limitações conhecidas do ax-code

• Provider.getSmallModel() devolve undefined para provedores cujo catálogo nem marca um family com indicação de nível nem casa com as listas fixas de prioridade; as chamadas auxiliares então recaem no modelo da sessão (registrado como ausência de modelo pequeno para o provedor).
• Não há escalada no meio da execução, de um trabalhador travado para um modelo mais forte.