Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Timeout e robustezza in produzione

Lezione 15 di 16 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Prepara la tua applicazione per il mondo reale
  2. Il timeout di 3600 secondi
  3. Gestione degli errori
  4. Architettura asincrona
  5. Circuit Breaker
  6. Punti chiave

Prepara la tua applicazione per il mondo reale

In produzione, le richieste alle API Responses possono richiedere tempo, specialmente con i modelli di ragionamento che elaborano a lungo prima di rispondere. Una gestione inadeguata dei timeout può causare fallimenti silenziosi o degradare l’esperienza utente.

Il timeout di 3600 secondi

xAI raccomanda un timeout minimo di 3600 secondi (1 ora) per le richieste indirizzate ai modelli di ragionamento. Questo valore è significativamente superiore a quello delle API standard e ha un impatto diretto sulla tua architettura.

Perché così lungo?

I modelli di ragionamento Grok-4.5 possono utilizzare centinaia di migliaia di token interni per il ragionamento prima di generare una risposta. Su problemi complessi (matematica avanzata, analisi del codice, ragionamento multi-step), il modello può impiegare diversi minuti per “pensare”.

Configurazione lato client

import httpx
from openai import OpenAI

# OpenAI SDK con timeout esteso
client = OpenAI(
    api_key="xai-...",
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(3600.0, connect=10.0)
)

In curl:

curl --max-time 3600 https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

Gestione degli errori

Errori comuni

Codice HTTPCausaAzione
401Chiave API non validaVerifica la chiave
429Limite di frequenza raggiuntoRiprova con backoff esponenziale
500Errore server xAIRiprova dopo alcuni secondi
503Servizio non disponibileRiprova dopo 30 secondi
TimeoutRichiesta troppo lungaAumenta il timeout o semplifica il prompt

Pattern di retry con backoff

import time

def call_with_retry(client, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        try:
            return client.responses.create(**kwargs)
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            wait = 2 ** attempt  # 1s, 2s, 4s
            print(f"Error: {e}. Retrying in {wait}s...")
            time.sleep(wait)

Limitazione della frequenza (Rate Limiting)

xAI applica limiti di frequenza in base al tuo piano. Implementa un limitatore di frequenza lato client:

import time
from collections import deque

class RateLimiter:
    def __init__(self, max_requests_per_minute=60):
        self.max_rpm = max_requests_per_minute
        self.timestamps = deque()

    def wait_if_needed(self):
        now = time.time()
        # Rimuovi i timestamp più vecchi di un minuto
        while self.timestamps and self.timestamps[0] < now - 60:
            self.timestamps.popleft()
        if len(self.timestamps) >= self.max_rpm:
            sleep_time = 60 - (now - self.timestamps[0])
            time.sleep(max(0, sleep_time))
        self.timestamps.append(time.time())

Architettura asincrona

Per le applicazioni web, non bloccare il thread principale per 3600 secondi. Utilizza un’architettura asincrona:

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(
    api_key="xai-...",
    base_url="https://api.x.ai/v1"
)

async def process_request(user_input):
    response = await client.responses.create(
        model="grok-4.20-0309-reasoning",
        input=user_input,
        stream=True
    )
    async for event in response:
        if event.type == "response.output_text.delta":
            yield event.delta

Lo streaming è l’approccio migliore per le applicazioni interattive: gli utenti vedono i primi token entro pochi secondi, anche se la generazione completa richiede più tempo.

Circuit Breaker

Per proteggere la tua applicazione da interruzioni delle API xAI:

class CircuitBreaker:
    def __init__(self, failure_threshold=5, reset_timeout=60):
        self.failures = 0
        self.threshold = failure_threshold
        self.reset_timeout = reset_timeout
        self.last_failure = 0
        self.is_open = False

    def call(self, func, *args, **kwargs):
        if self.is_open:
            if time.time() - self.last_failure > self.reset_timeout:
                self.is_open = False
                self.failures = 0
            else:
                raise Exception("Circuit open — API unavailable")

        try:
            result = func(*args, **kwargs)
            self.failures = 0
            return result
        except Exception as e:
            self.failures += 1
            self.last_failure = time.time()
            if self.failures >= self.threshold:
                self.is_open = True
            raise

Punti chiave

  • Configura un timeout minimo di 3600 secondi per i modelli di ragionamento
  • Implementa un meccanismo di retry con backoff esponenziale per gli errori 429 e 500
  • Usa lo streaming per le applicazioni interattive: gli utenti vedono i token immediatamente
  • Gestisci la limitazione di frequenza lato client per evitare errori 429
  • Considera l’uso di un circuit breaker per proteggere la tua applicazione da interruzioni delle API