Fallback de Provedores

O ChatCLI suporta uma cadeia de failover automático entre provedores LLM. Quando o provedor primário falha (rate limit, timeout, erro de servidor), o sistema tenta automaticamente o próximo provedor na cadeia, de forma totalmente transparente.

Como Funciona

A cadeia de fallback e uma lista ordenada de provedores. Cada request percorre a lista até obter sucesso ou esgotar todas as opcoes:

Request -> OpenAI (primário)
             | falhou (rate limit)
           Claude (secundário)
             | falhou (timeout)
           Google AI (terciario)
             | sucesso
           Resposta retornada ao usuário

Configuração

Variáveis de Ambiente
Flags do Servidor
Helm Chart

# Lista ordenada de provedores (primeiro = maior prioridade)
export CHATCLI_FALLBACK_PROVIDERS="OPENAI,CLAUDEAI,GOOGLEAI,OPENROUTER,ZAI,MINIMAX,MOONSHOT,COPILOT"

# Modelo específico por provedor (opcional)
export CHATCLI_FALLBACK_MODEL_OPENAI="gpt-5.4"
export CHATCLI_FALLBACK_MODEL_CLAUDEAI="claude-sonnet-4-6"
export CHATCLI_FALLBACK_MODEL_GOOGLEAI="gemini-2.5-flash"
export CHATCLI_FALLBACK_MODEL_OPENROUTER="anthropic/claude-sonnet-4"
export CHATCLI_FALLBACK_MODEL_ZAI="glm-5"
export CHATCLI_FALLBACK_MODEL_MINIMAX="MiniMax-M2.7"
export CHATCLI_FALLBACK_MODEL_COPILOT="gpt-4o"

# MiniMax no modo Anthropic-compatível (opcional)
export MINIMAX_API_COMPAT="anthropic"

# Controle de retentativas e cooldown
export CHATCLI_FALLBACK_MAX_RETRIES="2"       # tentativas por provedor
export CHATCLI_FALLBACK_COOLDOWN_BASE="30s"    # cooldown base
export CHATCLI_FALLBACK_COOLDOWN_MAX="5m"      # cooldown máximo

chatcli server \
  --fallback-providers OPENAI,CLAUDEAI,GOOGLEAI,OPENROUTER,ZAI,MINIMAX,MOONSHOT,COPILOT \
  --fallback-max-retries 2 \
  --fallback-cooldown-base 30s \
  --fallback-cooldown-max 5m

# values.yaml
fallback:
  enabled: true
  providers:
    - name: OPENAI
      model: gpt-5.4
    - name: CLAUDEAI
      model: claude-sonnet-4-6
    - name: GOOGLEAI
      model: gemini-2.5-flash
    - name: OPENROUTER
      model: anthropic/claude-sonnet-4
    - name: ZAI
      model: glm-5
    - name: MINIMAX
      model: MiniMax-M2.7
    - name: COPILOT
      model: gpt-4o
  maxRetries: 2
  cooldownBase: "30s"
  cooldownMax: "5m"

Classificacao de Erros

O sistema classifica automaticamente cada falha para decidir a estrategia:

Classe	Comportamento	Exemplos
`rate_limit`	Aguarda backoff, depois retenta	HTTP 429, “too many requests”
`timeout`	Retenta até maxRetries	Deadline exceeded, connection timeout
`server_error`	Retenta até maxRetries	HTTP 500, 502, 503
`auth_error`	Tenta refresh do token OAuth e retenta uma vez; se falhar, avanca na cadeia	HTTP 401, 403, “invalid api key”
`model_not_found`	Não retenta — avanca na cadeia	HTTP 404, “model not found”
`context_too_long`	Não retenta — avanca na cadeia	”context length exceeded”

Cooldown Exponencial

Após falhas consecutivas, o provedor entra em cooldown com backoff exponencial:

Falhas Consecutivas	Cooldown
1	30s
2	60s
3	120s
4	240s
5+	300s (max)

No modo CLI interativo, erros de autenticação (401) disparam automaticamente o refresh do token OAuth e retentam o request. No modo servidor (fallback chain), erros de autenticação recebem cooldown máximo imediato (5m). Um request bem-sucedido limpa todo o cooldown do provedor. Use ResetCooldowns() para limpar manualmente (ex: após atualizar credenciais).

Monitoramento de Saude

A cadeia rastreia o estado de cada provedor em tempo real:

health := chain.GetHealth()
for _, h := range health {
    fmt.Printf("Provider: %s, Available: %v, Fails: %d, Cooldown: %v\n",
        h.Name, h.Available, h.ConsecutiveFails, h.CooldownUntil)
}

Campos rastreados por provedor:

Campo	Descrição
`Available`	Se o provedor está disponível para requests
`ConsecutiveFails`	Número de falhas consecutivas
`LastErrorClass`	Tipo da ultima falha
`CooldownUntil`	Quando o cooldown expira
`LastErrorAt`	Timestamp da ultima falha

Tool Use com Fallback

A cadeia de fallback também suporta SendPromptWithTools para provedores que implementam a interface ToolAwareClient. Provedores sem suporte a tool use nativo são automaticamente ignorados na cadeia de tool calls.

Boas Praticas

Ordene por custo-beneficio

Coloque o provedor mais barato/rápido primeiro na cadeia.

Diversifique provedores

Misture provedores de diferentes empresas para resiliencia real.

Configure modelos por provedor

Use modelos equivalentes em capacidade para manter qualidade.

Monitore a saude

Verifique regularmente se algum provedor está em cooldown persistente.

Fallback nativo do OpenRouter: Além do sistema de fallback do ChatCLI (entre provedores), o OpenRouter oferece seu próprio roteamento de fallback dentro do provedor. Configure OPENROUTER_FALLBACK_MODELS com modelos alternativos (ex: openai/gpt-4o,google/gemini-2.5-flash). Se o modelo principal falhar, o OpenRouter tenta os alternativos antes de devolver o erro ao ChatCLI. Os dois mecanismos são complementares.

Cada provedor na cadeia precisa de sua propria API key configurada. Certifique-se de configurar as chaves de todos os provedores listados em CHATCLI_FALLBACK_PROVIDERS.

As entradas da cadeia são identificadas pelo nome do provider — cada provider pode aparecer apenas uma vez, e entradas com o mesmo nome compartilham a mesma chave, endpoint e estado de saúde. Para adicionar um gateway compatível com OpenAI como entrada separada da OpenAI, use o preset OpenRouter apontado para ele: defina OPENROUTER_API_KEY com a chave do gateway e OPENROUTER_API_URL com a URL completa de chat completions do gateway, e liste OPENROUTER junto de OPENAI na cadeia.

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Segurança

Suporte

Fallback de Provedores

Como Funciona

Configuração

Classificacao de Erros

Cooldown Exponencial

Monitoramento de Saude

Tool Use com Fallback

Boas Praticas

Ordene por custo-beneficio

Diversifique provedores

Configure modelos por provedor

Monitore a saude

​Como Funciona

​Configuração

​Classificacao de Erros

​Cooldown Exponencial

​Monitoramento de Saude

​Tool Use com Fallback

​Boas Praticas

Ordene por custo-beneficio

Diversifique provedores

Configure modelos por provedor

Monitore a saude

Como Funciona

Configuração

Classificacao de Erros

Cooldown Exponencial

Monitoramento de Saude

Tool Use com Fallback

Boas Praticas