BroadRouter
Começar

Failover de API de LLM: passe para um segundo provedor no seu código

Pela equipe da BroadNet Inference · 8 min de leitura · Publicado em · Atualizado em

Mantenha uma lista ordenada de provedores compatíveis com a OpenAI, cada um com seu próprio client e ID de modelo. Faça failover em erros de conexão, timeouts, 5xx e 429 de limite de taxa depois que as tentativas do próprio SDK se esgotarem. Nunca faça failover em 400, 401, 402, 403, 413 ou 422. Adicione um circuit breaker e confira se o reserva acompanha o principal em recursos e termos de dados.

Toda API de LLM tem seus minutos ruins: um 503, um timeout, uma rajada de 429. Fallback significa que esses minutos não viram uma queda no seu app. Este post mostra como fazer failover entre provedores compatíveis com a OpenAI no seu próprio código. Ele cobre quais erros devem acioná-lo, como um circuit breaker o mantém rápido e o que precisa bater entre os provedores para os usuários não perceberem a troca.

Antes de tudo: a BroadNet Inference não roteia nem faz failover entre provedores por você, e o BroadRouter também não. O BroadRouter é o site da própria BroadNet, não um roteador. Você monta o fallback, seja no seu client, como mostrado abaixo, seja num gateway como o LiteLLM.

Por que manter um provedor de fallback?

Porque a maioria das APIs self-service não promete nada sobre uptime. Os termos da BroadNet dizem isso com todas as letras na seção 7.4: “self-serve has no availability commitment” (tradução: o self-service não tem compromisso de disponibilidade), e níveis de serviço só existem num acordo escrito separado (verificado em 15 de novembro de 2026). A comparação de SLAs de APIs de LLM mostra com o que outros provedores se comprometem. Se a sua funcionalidade precisa ficar no ar, um segundo provedor é o seguro prático, diga o SLA o que disser.

Limites de taxa são o segundo motivo. Uma chave de pagamento por uso da BroadNet permite 30 requisições por minuto e 4 em andamento. Um pico de tráfego acima disso devolve 429, e um segundo provedor pode absorver o excesso enquanto você aumenta a capacidade.

Quais erros devem acionar um failover?

Divida os erros em dois grupos. Alguns são culpa do provedor e podem dar certo em outro lugar. Outros são culpa sua e vão falhar em qualquer lugar.

Erro Failover? Por quê
Erro de conexão, timeout Sim, depois das novas tentativas O provedor ou a rede está inacessível
500, 502, 503, 504 Sim, depois das novas tentativas A documentação da BroadNet diz para primeiro “retry with bounded exponential backoff” (tradução: tentar de novo com backoff exponencial limitado)
429, limite de taxa ou de concorrência Sim, depois do backoff Falta capacidade neste provedor, a requisição não está errada
429, limite de gasto Não O failover contorna o orçamento que você definiu de propósito
400, 422 Não A requisição é inválida e vai falhar no próximo provedor também
401, 402 Não Chave, franquia ou saldo. Na BroadNet, um 401 também cobre uma franquia de pagamento por uso esgotada, então o failover esconde um problema de cobrança
403, 413 Não Política ou tamanho; corrija a requisição

A referência da API da BroadNet diz que um 429 significa “a rate, concurrency, token-rate or spending limit was reached” (tradução: foi atingido um limite de taxa, de concorrência, de tokens por segundo ou de gasto) e recomenda “use response details and bounded backoff” (tradução: usar os detalhes da resposta e um backoff limitado). Leia esses detalhes antes do failover, para que um 429 por limite de gasto pare a requisição em vez de movê-la. O guia de códigos de erro lista todos os status.

Tente de novo antes do failover. O SDK Python da OpenAI já repete erros de conexão, 408, 409, 429 e respostas 5xx “2 times by default, with a short exponential backoff” (tradução: 2 vezes por padrão, com um backoff exponencial curto), e o timeout padrão dele é de 10 minutos (README, verificado em 15 de novembro de 2026). Dez minutos é tempo demais para esperar antes de um failover. Defina timeout por client. O post sobre como tratar 429 explica backoff com jitter.

Como fica um failover em Python?

Dois clients, uma lista ordenada e um pequeno circuit breaker. O principal é o GLM 5.3 na BroadNet. O reserva é o mesmo modelo aberto na DeepInfra, cuja documentação informa a base URL https://api.deepinfra.com/v1/openai (verificado em 15 de novembro de 2026).

import os
import time
from openai import (OpenAI, APIConnectionError, APITimeoutError,
                    RateLimitError, InternalServerError)

PROVIDERS = [
    {"name": "broadnet", "model": "broadnet/glm-5.3",
     "client": OpenAI(base_url="https://inference.broadnet.ai/v1",
                      api_key=os.environ["BROADNET_API_KEY"],
                      max_retries=2, timeout=60)},
    {"name": "deepinfra", "model": "zai-org/GLM-5.3",
     "client": OpenAI(base_url="https://api.deepinfra.com/v1/openai",
                      api_key=os.environ["DEEPINFRA_API_KEY"],
                      max_retries=2, timeout=60)},
]

# Provider-side failures only. 400, 401, 402, 403 and 422 raise straight through.
FAILOVER_ON = (APIConnectionError, APITimeoutError, RateLimitError, InternalServerError)
TRIP_AFTER = 3     # consecutive failures before the breaker opens
COOLDOWN = 30      # seconds to skip a provider once its breaker is open
state = {p["name"]: {"fails": 0, "open_until": 0.0} for p in PROVIDERS}


def chat(messages, **kwargs):
    last_error = None
    for p in PROVIDERS:
        s = state[p["name"]]
        if time.monotonic() < s["open_until"]:
            continue  # breaker open: don't wait on a provider that is down
        try:
            reply = p["client"].chat.completions.create(
                model=p["model"], messages=messages, **kwargs)
            s["fails"] = 0
            return p["name"], reply
        except FAILOVER_ON as err:
            last_error = err
            s["fails"] += 1
            if s["fails"] >= TRIP_AFTER:
                s["open_until"] = time.monotonic() + COOLDOWN
    raise RuntimeError("every provider failed") from last_error


served_by, reply = chat([{"role": "user", "content": "Reply with one short sentence."}],
                        max_tokens=1000)
print(served_by, reply.model, reply.choices[0].message.content)

Quatro detalhes importam:

  1. Classes de exceção. O SDK lança RateLimitError para 429, InternalServerError para 500 ou mais, e APIConnectionError (com APITimeoutError como subclasse) quando não consegue conectar. Todo o resto fica sem captura de propósito. Para deixar de fora os 429 de limite de gasto, inspecione err.response antes de continuar.
  2. O circuit breaker. Sem ele, cada requisição paga o timeout inteiro num principal morto antes de seguir. Depois de três falhas seguidas, o principal é pulado por 30 segundos. Depois disso, a próxima requisição testa ele de novo.
  3. Registre quem atendeu. Devolva o nome do provedor e guarde reply.model. Quando a qualidade mudar, você precisa saber qual provedor respondeu.
  4. Orçamento de raciocínio. O GLM 5.3 raciocina antes de responder. A documentação da BroadNet diz que o raciocínio conta em max_tokens, então deixe 1.000 ou mais em todos os provedores.

Como mapear IDs de modelo entre provedores?

O mesmo modelo aberto tem um ID diferente em cada host, e os recursos que cada host lista podem variar. O GLM 5.3 em 15 de novembro de 2026:

BroadNet Inference DeepInfra Fireworks AI
ID do modelo broadnet/glm-5.3 zai-org/GLM-5.3 accounts/fireworks/models/glm-5p3
Contexto 1.048.576 tokens 1.048.576 tokens “1040k” tokens
Ferramentas Documentadas “Function” listado Suportadas
Saída estruturada Documentada “JSON” listado Não verificado

Daí saem duas regras. Primeiro, mantenha o mapeamento na configuração, não espalhado pelo código. Segundo, escolha o fallback de acordo com o que as suas requisições usam. Na BroadNet, ferramentas e saída estruturada estão documentadas só para o GLM 5.3 e o Qwen3.8 27B. Um agente com chamada de ferramentas pode passar do GLM 5.3 para o GLM 5.3 em outro lugar. Ele não pode passar com segurança para um modelo que não documenta ferramentas. Se o reserva tiver uma janela de contexto menor, corte o prompt ou pule esse reserva nas requisições longas. As base URLs de 14 provedores estão na referência de base URLs.

Como manter respostas comparáveis depois da troca?

Os mesmos pesos em dois hosts ainda podem responder diferente, porque os hosts podem servir precisões, chat templates ou parâmetros padrão diferentes. Um modelo diferente com certeza responde diferente.

  • Rode o seu conjunto de avaliação contra cada item da lista, não só contra o principal.
  • Fixe temperature, max_tokens e o prompt de sistema em cada requisição, para que os padrões do provedor não mudem a saída.
  • Valide a saída estruturada do mesmo jeito em todos os caminhos. Como corrigir JSON inválido cobre o loop de reparo e nova tentativa.
  • Prefira o mesmo modelo em outro lugar a um modelo diferente no mesmo host. Os usuários notam uma mudança de estilo mais que alguns segundos de latência.

E o streaming e as chamadas de ferramenta?

Um stream pode falhar no meio. A documentação da BroadNet diz que um stream que termina antes de data: [DONE] deve ser tratado como incompleto: registre o X-Request-ID e decida se a sua aplicação pode enviar uma nova requisição com segurança.

  • Antes do primeiro token: faça failover à vontade. O usuário não viu nada.
  • Depois que os tokens apareceram: recomece no reserva e substitua a resposta parcial, ou mostre um erro com um botão de tentar de novo. Emendar meias respostas de dois provedores fica ruim de ler.
  • Chamadas de ferramenta com efeitos colaterais: nunca execute de novo um passo que envia um e-mail, cobra um cartão ou grava num banco de dados só porque a chamada ao modelo falhou. Dê a cada ação uma chave de idempotência. Agentes de longa duração trata de checkpoints.

Streaming com SSE explica como detectar um stream que terminou antes da hora.

Quanto custa o failover?

  • Trabalho duplicado. Um timeout do seu lado não prova que o provedor parou. Na cobrança por token, cada nova tentativa é uma nova inferência, então espere pagar duas vezes por algumas requisições.
  • Preços diferentes. O reserva cobra pelas próprias tarifas. Em 15 de novembro de 2026 a DeepInfra listava um preço promocional para o GLM-5.3, então confira de novo antes de fazer o orçamento. A BroadNet cobra $0.78 de entrada, $0.173 de entrada em cache e $3.46 de saída por 1M de tokens.
  • Cache frio. A entrada em cache não passa de um provedor para outro. As primeiras requisições no reserva pagam preço cheio de entrada por um prefixo que estava em cache no principal. Veja tokens de entrada em cache.
  • Hedging. Mandar cada requisição para dois provedores ao mesmo tempo e ficar com a primeira resposta reduz a latência de cauda, mas praticamente dobra a conta. Use só onde a latência vale isso.

O fallback atende aos mesmos termos de dados?

Um provedor de fallback é outro operador que recebe os mesmos prompts. Se você prometeu algo aos clientes sobre os dados deles, a promessa precisa valer para cada item da lista.

A declaração de privacidade da BroadNet diz: “We do not retain prompts, audio, images, answers or transcripts” (tradução: não retemos prompts, áudio, imagens, respostas ou transcrições). O conteúdo de inferência não é retido; os metadados necessários de conta, cobrança e segurança são mantidos conforme descrito nessa declaração. Ela também diz que dados de inferência não são usados para treinar, fazer fine-tuning ou avaliar modelos. A declaração diz que os modelos hospedados “run on BroadNet-owned or leased hardware in the United States, with partner capacity as backup” (tradução: rodam em hardware próprio ou alugado da BroadNet nos Estados Unidos, com capacidade de parceiros como reserva); o DeepSeek V4.1 Flash é hospedado por parceiro. Para dados com requisitos de residência, os termos (seção 7.3a) dizem para combinar os locais de processamento antes de enviá-los. Confira os mesmos pontos no reserva: retenção, uso para treinamento, local e suboperadores. Se ele não atender, deixe as requisições sensíveis fora do caminho de fallback e faça-as falhar de forma fechada. O checklist de retenção zero de dados lista as perguntas.

Vale usar um gateway como o LiteLLM?

Use um gateway se vários serviços precisam das mesmas regras de fallback. O proxy do LiteLLM aceita uma lista fallbacks testada em ordem. num_retries repete um grupo de modelos antes de cair no fallback. allowed_fails e cooldown_time tiram por um tempo um deployment que está falhando, o que funciona como circuit breaker. context_window_fallbacks e content_policy_fallbacks, separados, cuidam desses tipos de erro (documentação do LiteLLM, verificado em 15 de novembro de 2026):

model_list:
  - model_name: glm
    litellm_params:
      model: openai/broadnet/glm-5.3
      api_base: https://inference.broadnet.ai/v1
      api_key: os.environ/BROADNET_API_KEY
  - model_name: glm-backup
    litellm_params:
      model: openai/zai-org/GLM-5.3
      api_base: https://api.deepinfra.com/v1/openai
      api_key: os.environ/DEEPINFRA_API_KEY

router_settings:
  fallbacks: [{"glm": ["glm-backup"]}]
  allowed_fails: 3
  cooldown_time: 30

litellm_settings:
  num_retries: 2
  request_timeout: 60

O guia do proxy LiteLLM mostra a entrada da BroadNet completa. As duas entradas usam o prefixo genérico openai/ do LiteLLM com um api_base, o mesmo padrão do guia. Um gateway adiciona um salto e mais uma peça para manter rodando. Para um único app, cerca de 40 linhas no client, como acima, é suficiente.

Como testar o failover antes de precisar dele?

  1. Numa configuração de teste, aponte o principal para um host inacessível e confira se as requisições chegam ao reserva.
  2. Envie uma requisição propositalmente inválida e confira se ela não faz failover.
  3. Use uma chave principal inválida e confira se o 401 aparece como erro, não como uma troca silenciosa.
  4. Observe o breaker: depois de três falhas, o principal deve ser pulado sem esperar o timeout.
  5. Crie um alerta quando o reserva atender mais que uma pequena parte do tráfego. Um failover silencioso pode esconder um principal quebrado por dias.

O Router do LiteLLM aceita mock_testing_fallbacks=True em testes diretos para forçar um fallback.

Onde a BroadNet Inference se encaixa

O BroadRouter é o site da BroadNet, e a BroadNet Inference pode ser qualquer um dos itens da sua lista. Como principal, ela oferece o GLM 5.3 e o Qwen3.8 27B com ferramentas e saída estruturada documentadas, além do Gemma 4 VL 26B e do DeepSeek V4.1 Flash, numa única base URL sem conteúdo retido. Como reserva, é mais um endpoint compatível com a OpenAI para adicionar à lista. Nos dois casos, a lógica de failover é sua: a BroadNet não roteia entre provedores, e o self-service não tem SLA. Se você precisa de níveis de serviço contratados, eles só vêm com um acordo escrito separado. Compare os modelos, ou crie uma conta e teste sua cadeia com o crédito inicial de $5 no Gemma 4 VL 26B. O GLM 5.3 e o Qwen3.8 27B exigem uma recarga.

Perguntas frequentes

Quais erros devem acionar o fallback de uma API de LLM?

Erros de conexão, timeouts, 5xx e 429 de limite de taxa, depois das novas tentativas do próprio SDK. Não faça failover em 400, 401, 402, 403, 413 ou 422: o problema está na requisição ou na conta, e o próximo provedor falha do mesmo jeito ou esconde um problema de cobrança.

A BroadNet faz failover para outro provedor automaticamente?

Não. A BroadNet Inference não roteia requisições entre modelos ou provedores, e o BroadRouter, este site, é o site informativo da BroadNet, não um roteador. Você monta o fallback no seu client ou num gateway como o LiteLLM.

Posso usar o mesmo ID de modelo em todos os provedores?

Não. Cada provedor dá um nome diferente ao mesmo modelo aberto. O GLM 5.3 é `broadnet/glm-5.3` na BroadNet, `zai-org/GLM-5.3` na DeepInfra e `accounts/fireworks/models/glm-5p3` na Fireworks (verificado em 15 de novembro de 2026). Mantenha um mapeamento por provedor.

Tentativas que falham custam dinheiro?

Podem custar. Um timeout do seu lado não prova que o provedor parou o trabalho, e na cobrança por token cada nova tentativa é uma nova inferência. Conte com algumas requisições cobradas em dobro e limite as tentativas por requisição.

O provedor de fallback precisa ter os mesmos termos de privacidade?

Sim. Um fallback é outro operador que vê os mesmos prompts. Confira os termos de retenção, treinamento e local de processamento antes de adicioná-lo, ou a sua promessa de privacidade só vale enquanto o principal estiver no ar.

A BroadNet tem SLA?

Não no self-service. Os termos da BroadNet (seção 7.4) dizem que o self-service não tem compromisso de disponibilidade; níveis de serviço só existem num acordo escrito separado.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity