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

Seleção e recuperação de modelo

Status: Ativo Escopo: estado atual Última revisão: 2026-10-10 Responsável: ax-code runtime

O AX Code preserva seleções exatas de provedor e de modelo. Conectar um provedor não o acrescenta a um conjunto automático de recuperação. Sem uma alternativa configurada, falhas transitórias tentam de novo o alvo selecionado dentro do limite de tentativas já existente e depois param.

Configurar uma alternativa ordenada

Defina llm_routing.fallback na configuração do usuário, numa configuração personalizada escolhida por AX_CODE_CONFIG, ou num AX_CODE_CONFIG_CONTENT explícito. Os alvos são pares exatos; IDs de modelo podem conter barras. Por exemplo:

{
  "model": "my-gateway/openai/gpt-oss-120b",
  "llm_routing": {
    "fallback": [
      { "providerID": "my-gateway", "modelID": "my-backup-model" },
      { "providerID": "my-other-provider", "modelID": "my-approved-model" }
    ]
  }
}

Substitua estes exemplos pelos IDs exatos dos seus provedores configurados. A lista aceita até oito alvos distintos. Vazia ou ausente significa que nenhum alvo muda. A configuração do projeto e a remota podem estreitar concessões do usuário, mas não podem acrescentá-las nem reordená-las. Restrições gerenciadas formam um teto final. Se o próximo alvo configurado estiver ausente, a recuperação para; o AX Code não substitui outra entrada do catálogo.

Limites comuns e transitórios de taxa, sobrecarga reconhecida e erros de servidor podem avançar por esta lista depois das tentativas no mesmo alvo. Falhas de autenticação, de permissão, de cota permanente e de solicitação inválida não autorizam uma troca. Sessões de provedor local não migram sozinhas para inferência remota. O cancelamento interrompe a sequência. A recuperação também para depois que a solicitação atual publica saída ou inicia uma ferramenta, para preservar o progresso parcial em vez de repetir efeitos.

O processador normalmente permite cinco novas tentativas no mesmo alvo depois da tentativa inicial; erros de limite de concorrência têm um limite de oito tentativas. Disjuntores do provedor e limites externos de erro podem parar antes. Passos bem-sucedidos do laço de ferramentas são solicitações novas, não novas tentativas do trabalho anterior. As novas tentativas do AI SDK ficam desativadas nos pontos controlados de geração direta. Tentativas internas de uma CLI externa e de um gateway podem continuar opacas.

Trabalho auxiliar e configuração existente

Sem small_model, título, recapitulação e compactação herdam o modelo principal. Um small_model explícito, ou um modelo de agente específico do papel, ainda seleciona aquele alvo exato. Fixações inválidas falham em vez de passar para outro provedor ou modelo. O trabalho opcional de título e de recapitulação conserva o comportamento de título local ou de pular. A compactação preserva a transcrição quando falha e só troca de modelo pela recuperação configurada.

Modelos principais configurados, fixações de tarefa, de agente ou de comando, e seleções recentes salvas também permanecem exatos. Remova ou corrija de forma explícita uma fixação indisponível. Execuções headless sem seleção configurada ou recente exigem --model. O seletor visível de modelo pode oferecer recomendações, mas essas sugestões não se tornam uma lista de recuperação.

O classificador opcional de complexidade exige um modelo auxiliar explícito; sem um, a classificação é pulada. Ele fica ancorado no provedor solicitado quando um modelo principal é informado. Escolhas explícitas do modelo principal sobrevivem ao roteamento por tema do agente.

Inspecionar a configuração efetiva

ax-code debug routing
ax-code debug routing --model my-gateway/openai/gpt-oss-120b

Isto imprime o modelo principal exato, a alternativa ordenada, a seleção auxiliar, as fixações de agente e o limite de tentativas. Não envia uma solicitação de modelo nem sonda a disponibilidade de um modelo. O carregamento normal da configuração pode buscar ajustes remotos já configurados. Isto é uma explicação da configuração, não uma reconstrução do comportamento passado do gateway.

As mensagens do usuário registram se a seleção veio de uma solicitação, de uma fixação de agente, do roteamento por complexidade ou híbrido, ou de padrões de sessão e de configuração. Essa origem descreve a entrada local; request não atesta quem operou um cliente de API. A evidência da solicitação registra o propósito e o alvo selecionados. Autodescrições geradas pelo modelo e nomes de modelo na memória ou em exemplos de ferramenta não são evidência de roteamento. O AX Trust e os provedores externos continuam responsáveis pelo roteamento e pela autorização na origem.