Adamant Tools

Adamant Tools › Blog

  • API
  • Python
  • JavaScript
  • Affidabilità
  • Streaming

Timeout e cancellazione delle chiamate ai modelli: idle, deadline totale, pulsante Stop (Python, Node.js)

Una chiamata a un modello può essere lenta, muta o infinita. Quattro tipi di timeout, perché il read timeout non ferma una risposta in streaming, e codice testato in Python e Node.js.

Pubblicato 7 min di letturaGitHubRead in English

Timeout e cancellazione delle chiamate ai modelli: idle, deadline totale, pulsante Stop (Python, Node.js)
Foto: Jacek Rużyczka, CC BY-SA 4.0, Wikimedia Commons

Una normale chiamata HTTP risponde in pochi millisecondi oppure fallisce. Con un modello linguistico è diverso: il primo token può arrivare dopo molti secondi, la risposta può continuare per minuti e un servizio a monte bloccato può restare in silenzio mentre la tua connessione resta aperta. Se il codice non ha limiti di tempo chiari, una sola richiesta lenta può occupare per sempre un thread, una connessione e la pazienza di un utente.

In questa guida separiamo i timeout che servono, vediamo perché l'impostazione "timeout" abituale non protegge una risposta in streaming e proponiamo codice testato per Python (httpx) e Node.js (fetch). Entrambi i client prevedono tre modi per chiudere una chiamata: timeout di inattività (idle), scadenza totale e annullamento da parte del chiamante (un pulsante "Stop"). I test girano contro un server finto locale, quindi non servono chiavi API. Se riprovi anche le chiamate fallite, leggi pure HTTP 429 dalle API di AI: retry con backoff e Retry-After: timeout e retry vanno progettati insieme.

Versioni verificate il 2026-11-10: httpx 0.28.1 su PyPI, Python 3.11 o successivo, Node.js 20.3 o successivo (i test sono girati su 22). Java non è trattato in questo articolo.

Quattro timeout diversi

"Timeout" significa cose diverse a livelli diversi. Per una chiamata a un modello conviene pensarne quattro:

Timeout Cosa limita Guasto tipico che intercetta
Connessione Apertura della connessione TCP/TLS Host sbagliato, firewall che scarta i pacchetti
Tempo al primo byte Attesa della prima parte della risposta Modello sovraccarico o ancora "a pensare"
Idle (lettura) Silenzio tra due blocchi di dati Un servizio a monte che si è bloccato a metà risposta
Scadenza totale L'intera chiamata, dall'inizio all'ultimo byte Uno stream che non finisce mai, o molto lento

La maggior parte delle librerie HTTP offre i primi tre in qualche forma e lascia a te il quarto. La libreria Python httpx documenta timeout separati connect, read, write e pool nella guida ai timeout. Nel browser e in Node.js fetch non ha alcuna opzione di timeout: si passa un AbortSignal.

Perché il read timeout non ferma una risposta in streaming

Il read timeout è il silenzio più lungo che il client accetta. Si azzera ogni volta che arrivano dati. In una risposta in streaming (vedi come mostrarla nel browser) il server invia un token ogni pochi millisecondi, quindi il timer non scade mai, anche se la risposta è infinita o il modello sta generando un testo enorme che nessuno vuole più.

In altre parole, il read timeout risponde a "il servizio a monte è rimasto in silenzio?", non a "questa chiamata ha impiegato troppo?". Servono entrambe le domande, e la seconda richiede una scadenza totale separata che non si azzera.

Seconda trappola: le librerie hanno i propri valori predefiniti. La documentazione di httpx dice che per impostazione predefinita solleva un'eccezione dopo 5 secondi di inattività di rete. Va bene per una normale API, ma un modello che ragiona per dieci secondi prima del primo token farà fallire ogni richiesta, a meno che tu non alzi il read timeout di quel client. Il predefinito opposto, nessun timeout, esiste in altre librerie ed è peggio: la chiamata può restare appesa per sempre.

Scegli i numeri dalle misure, non a intuito. Registra per qualche giorno il tempo al primo token e la durata totale, poi imposta il timeout idle sopra il primo token normale più lento e la scadenza sopra la risposta normale più lenta.

Python: httpx più asyncio.timeout

python
import asyncio

import httpx

# Four separate limits. "read" is the longest silence allowed between two chunks,
# not the time for the whole answer.
TIMEOUTS = httpx.Timeout(connect=5.0, read=30.0, write=10.0, pool=5.0)


async def stream_completion(url, payload, total_deadline=120.0, on_token=print):
    """Stream lines from a model endpoint with a per-chunk timeout AND a total deadline.

    Leaving the `async with` blocks (deadline, error or task.cancel()) closes the
    connection, which is the signal the server needs to stop generating.
    """
    tokens = []
    async with httpx.AsyncClient(timeout=TIMEOUTS) as client:
        async with asyncio.timeout(total_deadline):  # Python 3.11+
            async with client.stream("POST", url, json=payload) as resp:
                resp.raise_for_status()
                async for line in resp.aiter_lines():
                    tokens.append(line)
                    on_token(line)
    return tokens

Cosa fa il codice:

  • TIMEOUTS imposta quattro limiti separati. Qui read=30.0 è il silenzio più lungo tra due blocchi del corpo della risposta, non la durata della risposta.
  • asyncio.timeout(total_deadline) è la scadenza totale. È stato aggiunto in Python 3.11 (vedi la documentazione di asyncio) e allo scadere solleva il TimeoutError incorporato.
  • client.stream(...) non carica il corpo in memoria: restituisce le righe man mano che arrivano.
  • Quando il codice esce dai blocchi async with per qualsiasi motivo (scadenza, errore o task.cancel()), httpx chiude la connessione. Quella chiusura è l'unico messaggio di "stop" che il server riceve.

Attenzione ai due tipi di eccezione. Un read timeout solleva httpx.ReadTimeout, sottoclasse di httpx.TimeoutException; la scadenza solleva il TimeoutError incorporato. Intercettali entrambi se vuoi trattarli allo stesso modo, e non intercettare l'Exception generica: asyncio.CancelledError non è un TimeoutError, e ingoiarla romperebbe la cancellazione.

JavaScript: AbortSignal.timeout e AbortSignal.any

javascript
// Node.js 20.3+ (AbortSignal.any). No dependencies.
export async function streamCompletion(url, payload, { totalMs = 120_000, idleMs = 30_000, signal, onToken = console.log } = {}) {
  // One controller we abort ourselves when the stream goes quiet.
  const idle = new AbortController();
  let idleTimer;
  const armIdle = () => {
    clearTimeout(idleTimer);
    idleTimer = setTimeout(() => idle.abort(new Error(`no data for ${idleMs} ms`)), idleMs);
  };

  const signals = [AbortSignal.timeout(totalMs), idle.signal];  // total deadline + idle timeout
  if (signal) signals.push(signal);                              // + cancellation from the caller (a "Stop" button)

  const tokens = [];
  armIdle();
  try {
    const res = await fetch(url, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify(payload),
      signal: AbortSignal.any(signals),
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const decoder = new TextDecoder();
    let buffer = '';
    for await (const chunk of res.body) {
      armIdle();                                                 // data arrived: restart the idle clock
      buffer += decoder.decode(chunk, { stream: true });
      const lines = buffer.split('\n');
      buffer = lines.pop();
      for (const line of lines) { tokens.push(line); onToken(line); }
    }
    return tokens;
  } finally {
    clearTimeout(idleTimer);
  }
}

Qui i tre limiti sono tre segnali uniti in uno:

  • AbortSignal.timeout(ms) è la scadenza totale e interrompe con un TimeoutError.
  • idle è un AbortController che interrompiamo noi da un timer. Il timer viene riarmato a ogni blocco ricevuto, e questo lo rende un timeout di inattività.
  • Il signal passato dal chiamante è il pulsante "Stop": controller.abort() chiude la richiesta e il ciclo con un AbortError.
  • AbortSignal.any([...]) li unisce. Richiede Node.js 20.3 o successivo (o 18.17), come indica la documentazione di Node.js; per i browser controlla la tabella di compatibilità su MDN prima di usarlo.

Un dettaglio facile da dimenticare: il timer idle deve partire anche prima del primo blocco (chiamiamo armIdle() prima di fetch), altrimenti un server che accetta la connessione e non risponde mai viene fermato solo dalla scadenza totale. E il finally cancella il timer, altrimenti una chiamata finita terrebbe vivo il processo Node.js fino allo scattare del timer.

Annullare significa chiudere la connessione

HTTP non ha un messaggio "annulla". Quando interrompi una richiesta, il client chiude la connessione (o resetta lo stream con HTTP/2). Che il modello smetta di generare dipende dal fatto che il server se ne accorga. Molti server se ne accorgono solo quando provano a scrivere il blocco successivo e ottengono un errore; alcuni proxy continuano a leggere dal servizio a monte comunque. Se paghi per token generato, una chiamata abbandonata può essere fatturata almeno in parte. Verifica come si comportano il tuo provider e il tuo gateway, e non dare per scontato che un annullamento sia gratuito.

Il server finto dell'esempio mostra il meccanismo in poche righe: scrive un token ogni 0,1 secondi e considera abbandonato uno stream quando la scrittura fallisce.

python
    def _stream(self, stall):
        self.send_response(200)
        self.send_header("content-type", "text/plain")
        self.end_headers()
        try:
            n = 0
            while True:
                n += 1
                self.wfile.write(f"token {n}\n".encode())
                self.wfile.flush()
                if stall:
                    time.sleep(30)
                    return
                time.sleep(0.1)
        except (BrokenPipeError, ConnectionResetError):
            with lock:
                stats["abandoned"] += 1

I test

Tre test per linguaggio, con gli stessi tre scenari. /drip invia un token ogni 0,1 s per sempre, /stall invia una riga e poi tace per 30 s. Questo è il test Python della scadenza totale:

python
    async def test_total_deadline_stops_a_stream_that_never_ends(self):
        before = abandoned(self.base)
        got = []
        # Tokens keep arriving every 0.1 s, so the read timeout (30 s) never fires.
        with self.assertRaises(TimeoutError):
            await client.stream_completion(f"{self.base}/drip", {}, total_deadline=1.0, on_token=got.append)
        self.assertGreater(len(got), 3)  # it did receive tokens before the deadline
        self.assertTrue(await wait_for_abandoned(self.base, before + 1), "server never saw the disconnect")

Il test dimostra due cose: la scadenza scatta anche se i dati continuano ad arrivare, e il server ha davvero visto chiudersi la connessione. Gli altri test verificano che il read timeout (httpx.ReadTimeout, o il timeout idle in JavaScript) chiuda la chiamata bloccata, e che annullare il task o interrompere il segnale chiuda a sua volta la connessione. I test Node.js usano lo stesso server finto Python, quindi i due client sono verificati sullo stesso comportamento.

Cosa ho notato scrivendo i test:

  • Il server si accorge della disconnessione con un po' di ritardo, quindi il test interroga /stats per alcuni secondi invece di controllare una volta sola. Un test che controlla subito è instabile.
  • Il timeout di connessione è configurato nel codice ma non testato: riprodurlo richiede un indirizzo che scarta i pacchetti in silenzio, cosa poco affidabile su un runner di CI.
  • /stall fa tenere al server un thread per 30 s. Il server finto usa thread daemon, così l'esecuzione dei test non deve aspettarli.

Puoi eseguire tutto con python3 -m unittest -v e node --test nella cartella dell'esempio. L'esecuzione di CI per questo articolo è verde.

Timeout e retry

Quando scatta un timeout, la domanda successiva è se riprovare. Alcune regole che reggono nella pratica:

  • Riprova i timeout di connessione: non è stato inviato nulla. Riprova i timeout idle solo se la richiesta si può ripetere senza danni, e ricorda che il modello potrebbe aver già elaborato la prima. Nell'articolo sul 429 trovi perché una chiamata ripetuta è una chiamata nuova e fatturabile.
  • Un fallimento per scadenza totale di solito significa che il lavoro è troppo grande per il limite. Ripetere la stessa richiesta con lo stesso limite fallirà allo stesso modo: accorcia invece il prompt o l'output massimo.
  • Aggiungi attesa tra i tentativi con backoff esponenziale e jitter; il simulatore di retry e backoff mostra cosa produce una certa politica.
  • Rendi visibile il budget: se una richiesta rivolta all'utente ha un limite di 30 s, la somma di tutti i tentativi e delle attese deve starci dentro. Passa a ogni livello il budget residuo invece di dare a ogni tentativo 30 s nuovi.

Se il guasto arriva come stato HTTP e non come timeout, il nostro riferimento ai codici di stato HTTP spiega quali vale la pena riprovare.

  • Una chiamata a un modello richiede quattro limiti: connessione, primo byte, idle e totale.
  • Un timeout di lettura o idle non ferma mai uno stream che continua a inviare dati; aggiungi una scadenza totale.
  • In httpx combina httpx.Timeout(...) con asyncio.timeout(...); in Node.js combina AbortSignal.timeout, un timer idle riarmato e il segnale del chiamante con AbortSignal.any.
  • Annullare significa chiudere la connessione. Che il server smetta di generare, e che ti venga comunque fatturato, dipende dal server e dagli eventuali proxy in mezzo: prova con il tuo provider.
  • Misura le latenze reali prima di scegliere i numeri, e tieni il budget totale di timeout e retry entro ciò che l'utente accetta.

Fonti: httpx timeouts, Python asyncio.timeout, MDN AbortSignal, Node.js globals, RFC 9110, HTTP Semantics.

Codice completo su GitHub
L'esempio completo e testato di questo articolo è nel nostro repository pubblico: adamant-solutions/ai-dev-examples/timeouts

Chi l'ha scritto

Scritto dal team tecnico di Adamant Solutions: ingegneri senior che lavorano su API, identità e integrazione enterprise, certificati WSO2 e Spring. Il codice è testato prima della pubblicazione; se trovi un errore, scrivi a administrata@adamant-solutions.com.