BroadRouter
Inizia

Failover API LLM: passare a un secondo provider nel tuo codice

A cura del team di BroadNet Inference · 8 min di lettura · Pubblicato · Aggiornato

Tieni un elenco ordinato di provider compatibili con OpenAI, ciascuno con il proprio client e il proprio ID modello. Fai failover su errori di connessione, timeout, 5xx e 429 da rate limit, dopo aver esaurito i retry dell’SDK. Mai su 400, 401, 402, 403, 413 o 422. Aggiungi un circuit breaker e verifica che il backup sia allineato al primario su funzionalità e condizioni sui dati.

Ogni API LLM ha i suoi minuti storti: un 503, un timeout, una raffica di 429. Il fallback fa sì che quei minuti non diventino un disservizio nella tua app. Questo articolo mostra come fare failover tra provider compatibili con OpenAI nel tuo codice: quali errori devono attivarlo, come un circuit breaker lo mantiene veloce e cosa deve combaciare tra i provider perché gli utenti non si accorgano del cambio.

Una premessa: BroadNet Inference non instrada né fa failover tra provider al posto tuo, e nemmeno BroadRouter. BroadRouter è il sito web di BroadNet, non un router. Il fallback lo costruisci tu, nel client come mostrato sotto oppure in un gateway come LiteLLM.

Perché tenere un provider di fallback?

Perché la maggior parte delle API self-service non promette nulla sull’uptime. I termini di BroadNet lo dicono chiaramente nella sezione 7.4: «self-serve has no availability commitment» (traduzione: il self-service non ha alcun impegno di disponibilità), e i livelli di servizio esistono solo in un accordo scritto separato (verifica del 15 novembre 2026). Il confronto degli SLA delle API LLM spiega a cosa si impegnano gli altri provider. Se la tua funzionalità deve restare attiva, un secondo provider è l’assicurazione pratica, qualunque cosa dica lo SLA.

I rate limit sono il secondo motivo. Una chiave BroadNet a consumo consente 30 richieste al minuto e 4 in parallelo. Un picco di traffico oltre quella soglia restituisce 429, e un secondo provider può assorbire l’eccesso mentre aumenti la capacità.

Quali errori devono attivare un failover?

Dividi gli errori in due gruppi. Alcuni sono colpa del provider e altrove potrebbero andare a buon fine. Altri sono colpa tua e falliranno ovunque.

Errore Failover? Perché
Errore di connessione, timeout Sì, dopo i retry Il provider o la rete non sono raggiungibili
500, 502, 503, 504 Sì, dopo i retry La documentazione di BroadNet dice di fare prima «retry with bounded exponential backoff» (traduzione: retry con backoff esponenziale limitato)
429, limite di frequenza o di concorrenza Sì, dopo il backoff Manca capacità presso questo provider, la richiesta non è sbagliata
429, limite di spesa No Il failover aggira il budget che hai fissato di proposito
400, 422 No La richiesta non è valida e fallirà anche sul provider successivo
401, 402 No Chiave, plafond o saldo. Su BroadNet un 401 copre anche un plafond a consumo esaurito, quindi il failover nasconde un problema di fatturazione
403, 413 No Policy o dimensione; correggi la richiesta

Il riferimento API di BroadNet dice che un 429 significa «a rate, concurrency, token-rate or spending limit was reached» (traduzione: è stato raggiunto un limite di frequenza, di concorrenza, di token al secondo o di spesa) e consiglia di «use response details and bounded backoff» (traduzione: usare i dettagli della risposta e un backoff limitato). Leggi quei dettagli prima del failover, così un 429 per limite di spesa ferma la richiesta invece di spostarla. La guida ai codici di errore elenca tutti gli status.

Fai i retry prima del failover. L’SDK Python di OpenAI ritenta già errori di connessione, 408, 409, 429 e risposte 5xx «2 times by default, with a short exponential backoff» (traduzione: 2 volte di default, con un breve backoff esponenziale), e il suo timeout predefinito è di 10 minuti (README, verifica del 15 novembre 2026). Dieci minuti sono decisamente troppi da aspettare prima di un failover. Imposta timeout per ogni client. L’articolo sulla gestione dei 429 spiega il backoff con jitter.

Com’è un failover in Python?

Due client, un elenco ordinato e un piccolo circuit breaker. Il primario è GLM 5.3 su BroadNet. Il backup è lo stesso modello open-weight su DeepInfra, la cui documentazione indica la base URL https://api.deepinfra.com/v1/openai (verifica del 15 novembre 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)

Contano quattro dettagli:

  1. Classi di eccezione. L’SDK solleva RateLimitError per il 429, InternalServerError per 500 e superiori, e APIConnectionError (con APITimeoutError come sottoclasse) quando non riesce a connettersi. Tutto il resto resta volutamente non intercettato. Per escludere i 429 da limite di spesa, esamina err.response prima di proseguire.
  2. Il circuit breaker. Senza, ogni richiesta paga l’intero timeout su un primario morto prima di andare avanti. Dopo tre errori consecutivi il primario viene saltato per 30 secondi. Poi la richiesta successiva lo riprova.
  3. Registra chi ha risposto. Restituisci il nome del provider e conserva reply.model. Quando la qualità cambia, devi sapere quale provider ha risposto.
  4. Budget di ragionamento. GLM 5.3 ragiona prima di rispondere. La documentazione di BroadNet dice che il ragionamento conta in max_tokens, quindi lascia 1.000 o più su ogni provider.

Come si mappano gli ID modello tra i provider?

Lo stesso modello open-weight ha un ID diverso presso ogni host, e le funzionalità dichiarate da ciascun host possono differire. GLM 5.3 al 15 novembre 2026:

BroadNet Inference DeepInfra Fireworks AI
ID del modello broadnet/glm-5.3 zai-org/GLM-5.3 accounts/fireworks/models/glm-5p3
Contesto 1.048.576 token 1.048.576 token «1040k» token
Tool Documentati «Function» indicato Supportati
Output strutturato Documentato «JSON» indicato Non verificato

Ne derivano due regole. Primo, tieni la mappatura nella configurazione, non sparsa nel codice. Secondo, scegli il fallback in base a ciò che usano le tue richieste. Su BroadNet tool e output strutturato sono documentati solo per GLM 5.3 e Qwen3.8 27B. Un agente con tool calling può passare da GLM 5.3 a GLM 5.3 altrove. Non può passare in sicurezza a un modello che non documenta i tool. Se il backup ha una finestra di contesto più piccola, accorcia il prompt o salta quel backup per le richieste lunghe. Le base URL di 14 provider sono nel riferimento delle base URL.

Come mantenere risposte confrontabili dopo il cambio?

Gli stessi pesi presso due host possono comunque rispondere in modo diverso, perché gli host possono servire precisioni, chat template o parametri predefiniti diversi. Un modello diverso risponde in modo diverso di sicuro.

  • Esegui il tuo set di valutazione su ogni voce dell’elenco, non solo sul primario.
  • Fissa temperature, max_tokens e il prompt di sistema in ogni richiesta, così i default del provider non possono cambiare l’output.
  • Valida l’output strutturato allo stesso modo su ogni percorso. Correggere JSON non valido spiega il ciclo di riparazione e retry.
  • Preferisci lo stesso modello altrove a un modello diverso presso lo stesso host. Gli utenti notano un cambio di stile più di qualche secondo di latenza.

E lo streaming e le tool call?

Uno stream può interrompersi a metà. La documentazione di BroadNet dice che uno stream che termina prima di data: [DONE] va trattato come incompleto: registra l’X-Request-ID e decidi se la tua applicazione può inviare in sicurezza una nuova richiesta.

  • Prima del primo token: fai failover liberamente. L’utente non ha visto nulla.
  • Dopo che i token sono stati mostrati: riparti sul backup e sostituisci la risposta parziale, oppure mostra un errore con un pulsante per riprovare. Cucire insieme due mezze risposte di provider diversi si legge male.
  • Tool call con effetti collaterali: non rieseguire mai un passaggio che invia un’email, addebita una carta o scrive in un database solo perché la chiamata al modello è fallita. Assegna a ogni azione una chiave di idempotenza. Agenti di lunga durata parla dei checkpoint.

Lo streaming con SSE spiega come rilevare uno stream terminato in anticipo.

Quanto costa il failover?

  • Lavoro duplicato. Un timeout lato tuo non prova che il provider si sia fermato. Con la fatturazione a token ogni retry è una nuova inferenza, quindi aspettati di pagare due volte alcune richieste.
  • Prezzi diversi. Il backup fattura alle proprie tariffe. Il 15 novembre 2026 DeepInfra indicava un prezzo promozionale per GLM-5.3, quindi ricontrolla prima di fare il budget. BroadNet applica $0.78 di input, $0.173 di input in cache e $3.46 di output per 1M di token.
  • Cache fredde. L’input in cache non si trasferisce tra provider. Le prime richieste sul backup pagano l’input a prezzo pieno su un prefisso che sul primario era in cache. Vedi token di input in cache.
  • Hedging. Inviare ogni richiesta a due provider insieme e tenere la prima risposta riduce la latenza di coda, ma raddoppia circa la fattura. Usalo solo dove la latenza vale quel prezzo.

Il fallback rispetta le stesse condizioni sui dati?

Un provider di fallback è un altro responsabile del trattamento che riceve gli stessi prompt. Se hai promesso qualcosa ai clienti sui loro dati, la promessa deve valere per ogni voce dell’elenco.

L’informativa privacy di BroadNet dice: «We do not retain prompts, audio, images, answers or transcripts» (traduzione: non conserviamo prompt, audio, immagini, risposte o trascrizioni). I contenuti dell’inferenza non vengono conservati; i metadati necessari di account, fatturazione e sicurezza vengono conservati come descritto in quell’informativa. Dice anche che i dati dell’inferenza non sono usati per addestrare, fare fine-tune o valutare modelli. L’informativa dice che i modelli ospitati «run on BroadNet-owned or leased hardware in the United States, with partner capacity as backup» (traduzione: girano su hardware di proprietà di BroadNet o in leasing negli Stati Uniti, con capacità dei partner come backup); DeepSeek V4.1 Flash è ospitato da un partner. Per i dati con requisiti di residenza, i termini (sezione 7.3a) dicono di concordare i luoghi di elaborazione prima di inviarli. Verifica gli stessi punti per il backup: conservazione, uso per l’addestramento, luogo e sub-responsabili. Se non è all’altezza, tieni le richieste sensibili fuori dal percorso di fallback e falle fallire in modo chiuso. La checklist zero data retention elenca le domande da fare.

Conviene usare un gateway come LiteLLM?

Usa un gateway se più servizi hanno bisogno delle stesse regole di fallback. Il proxy di LiteLLM accetta un elenco fallbacks provato in ordine. num_retries ritenta un gruppo di modelli prima del fallback. allowed_fails e cooldown_time escludono per un po’ un deployment che fallisce, e funzionano come circuit breaker. context_window_fallbacks e content_policy_fallbacks, separati, gestiscono quei tipi di errore (documentazione di LiteLLM, verifica del 15 novembre 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

La guida al proxy LiteLLM mostra la voce BroadNet completa. Entrambe le voci usano il prefisso generico openai/ di LiteLLM con un api_base, lo stesso schema della guida. Un gateway aggiunge un passaggio e un componente in più da tenere in piedi. Per una singola app bastano circa 40 righe nel client, come sopra.

Come testare il failover prima che serva?

  1. In una configurazione di test, punta il primario a un host irraggiungibile e verifica che le richieste arrivino al backup.
  2. Invia una richiesta volutamente non valida e verifica che non faccia failover.
  3. Usa una chiave primaria non valida e verifica che il 401 emerga come errore, non come cambio silenzioso.
  4. Osserva il breaker: dopo tre errori il primario deve essere saltato senza aspettare il timeout.
  5. Imposta un avviso quando il backup serve più di una piccola quota del traffico. Un failover silenzioso può nascondere per giorni un primario guasto.

Il Router di LiteLLM accetta mock_testing_fallbacks=True nei test diretti per forzare un fallback.

Dove si colloca BroadNet Inference

BroadRouter è il sito web di BroadNet, e BroadNet Inference può essere l’una o l’altra voce del tuo elenco. Come primario ti dà GLM 5.3 e Qwen3.8 27B con tool e output strutturato documentati, più Gemma 4 VL 26B e DeepSeek V4.1 Flash, su un’unica base URL senza conservazione dei contenuti. Come backup è un altro endpoint compatibile con OpenAI da aggiungere all’elenco. In entrambi i casi la logica di failover è tua: BroadNet non instrada tra provider e il self-service non ha SLA. Se ti servono livelli di servizio contrattuali, arrivano solo con un accordo scritto separato. Confronta i modelli, oppure crea un account e prova la tua catena con il credito iniziale di $5 su Gemma 4 VL 26B. GLM 5.3 e Qwen3.8 27B richiedono una ricarica.

Domande frequenti

Quali errori devono attivare il fallback di un’API LLM?

Errori di connessione, timeout, 5xx e 429 da rate limit, dopo i retry dell’SDK. Non fare failover su 400, 401, 402, 403, 413 o 422: è sbagliata la richiesta o l’account, e il provider successivo fallisce allo stesso modo oppure nasconde un problema di fatturazione.

BroadNet fa failover su un altro provider in automatico?

No. BroadNet Inference non instrada le richieste tra modelli o provider, e BroadRouter, questo sito, è il sito informativo di BroadNet, non un router. Il fallback lo costruisci tu, nel client o in un gateway come LiteLLM.

Posso usare lo stesso ID modello su tutti i provider?

No. Ogni provider chiama in modo diverso lo stesso modello open-weight. GLM 5.3 è `broadnet/glm-5.3` su BroadNet, `zai-org/GLM-5.3` su DeepInfra e `accounts/fireworks/models/glm-5p3` su Fireworks (verifica del 15 novembre 2026). Tieni una mappatura per provider.

I tentativi falliti costano?

Possono costare. Un timeout lato tuo non prova che il provider abbia interrotto il lavoro, e con la fatturazione a token ogni retry è una nuova inferenza. Metti in conto qualche richiesta pagata due volte e limita i tentativi per richiesta.

Il provider di fallback deve avere le stesse condizioni privacy?

Sì. Un fallback è un altro responsabile del trattamento che vede gli stessi prompt. Verifica le sue condizioni su conservazione, addestramento e luogo di elaborazione prima di aggiungerlo, altrimenti la tua promessa sulla privacy vale solo finché il primario è attivo.

BroadNet ha uno SLA?

Non per il self-service. I termini di BroadNet (sezione 7.4) dicono che il self-service non ha impegni di disponibilità; i livelli di servizio esistono solo in un accordo scritto separato.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity