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:
- Classi di eccezione. L’SDK solleva
RateLimitErrorper il 429,InternalServerErrorper 500 e superiori, eAPIConnectionError(conAPITimeoutErrorcome sottoclasse) quando non riesce a connettersi. Tutto il resto resta volutamente non intercettato. Per escludere i 429 da limite di spesa, esaminaerr.responseprima di proseguire. - 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.
- Registra chi ha risposto. Restituisci il nome del provider e conserva
reply.model. Quando la qualità cambia, devi sapere quale provider ha risposto. - 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_tokense 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?
- In una configurazione di test, punta il primario a un host irraggiungibile e verifica che le richieste arrivino al backup.
- Invia una richiesta volutamente non valida e verifica che non faccia failover.
- Usa una chiave primaria non valida e verifica che il 401 emerga come errore, non come cambio silenzioso.
- Osserva il breaker: dopo tre errori il primario deve essere saltato senza aspettare il timeout.
- 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.
