Ogni chiamata di rete ha bisogno di un punto in cui smetti di aspettare. Per le chiamate LLM quel punto è difficile da scegliere, perché per un po’ una risposta lenta e una connessione morta sembrano uguali.
Come funziona
I client HTTP dividono l’attesa in fasi. HTTPX, un client HTTP Python molto diffuso, ne ha quattro:
| Timeout | Significato in HTTPX | Errore |
|---|---|---|
| Connect | Tempo massimo per stabilire una connessione socket | ConnectTimeout |
| Read | Attesa massima per un chunk di dati in arrivo | ReadTimeout |
| Write | Attesa massima per inviare un chunk del body della richiesta | WriteTimeout |
| Pool | Attesa massima per ottenere una connessione dal pool | PoolTimeout |
HTTPX da solo va in timeout dopo cinque secondi di inattività di rete. L’SDK Python di OpenAI imposta un proprio default: “By default requests time out after 10 minutes” (traduzione: per impostazione predefinita le richieste vanno in timeout dopo 10 minuti), solleva APITimeoutError e ritenta due volte una richiesta andata in timeout. Di default ritenta anche errori di connessione e risposte 408, 409, 429 e 5xx.
from openai import OpenAI
client = OpenAI(base_url="https://inference.broadnet.ai/v1", timeout=120.0, max_retries=2)
Anche i server hanno dei timeout. MDN definisce il 504 Gateway Timeout come un gateway o proxy che “did not get a response in time from the upstream server” (non ha ricevuto in tempo una risposta dal server a monte), e il 408 Request Timeout come il server che vuole “to shut down this unused connection” (chiudere questa connessione inutilizzata).
Perché è importante
- I modelli di ragionamento partono lenti. Il ragionamento avviene prima del primo token visibile. Un timeout di lettura breve su una chiamata senza streaming può interrompere una richiesta che sta andando bene.
- Gli stream rivelano i blocchi. Con lo streaming, ogni chunk azzera il timer di lettura, quindi un blocco emerge subito anche in una risposta lunga.
- I retry possono raddoppiare il costo. Un timeout non significa che il server si sia fermato. Ritentare una richiesta ancora in esecuzione può farti pagare due volte. Usa un backoff esponenziale con un tetto, e una idempotency key dove l’API la supporta.
Su BroadNet Inference
Il riferimento API di BroadNet dice di leggere uno stream fino a data: [DONE]. Se la connessione si chiude prima, “treat the response as incomplete, record the X-Request-ID” (traduzione: considera la risposta incompleta, registra l’X-Request-ID) e decidi se la tua applicazione può fare una nuova richiesta in sicurezza. Per 500, 502, 503 e 504 indica di ritentare con un backoff esponenziale limitato; un 429 significa che è stato raggiunto un limite di frequenza, di concorrenza, di token al minuto o di spesa. Conserva l’X-Request-ID per l’assistenza. La guida a errori e retry e l’articolo sugli agenti di lunga durata mostrano impostazioni funzionanti.
Errori comuni
- Lasciare il default e chiedersi perché una chiamata bloccata tenga fermo un worker per dieci minuti.
- Ritentare senza un tetto, così un minuto storto diventa una valanga di richieste.