Vai al contenuto principale
Italiano— Scegli una lingua
Menu

AsyncOpenAI con httpx.Timeout

Lezione 2 di 12 Aggiornata il 30 luglio 2026 Avanzato
In questa pagina
  1. L’alternativa all’SDK OpenAI
  2. Configurare AsyncOpenAI per xAI
  3. Comprendere httpx.Timeout
  4. Inviare richieste
  5. Gestione degli errori con httpx
  6. Quando scegliere AsyncOpenAI invece dell’SDK xAI
  7. Punti chiave

L’alternativa all’SDK OpenAI

L’SDK nativo di xAI non è l’unica opzione per lavorare in modo asincrono con l’API Grok. L’SDK OpenAI, ampiamente adottato nell’ecosistema Python, funziona con l’API xAI grazie alla compatibilità dei formati. Questo approccio ti permette di riutilizzare il codice OpenAI esistente e di sfruttare l’ecosistema di strumenti circostante.

Configurare AsyncOpenAI per xAI

L’inizializzazione richiede tre parametri: la tua chiave API, l’URL base di xAI e un timeout adattato per i modelli di ragionamento:

from openai import AsyncOpenAI
import httpx

client = AsyncOpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(3600.0)
)

Il dettaglio cruciale qui è httpx.Timeout(3600.0). L’SDK OpenAI utilizza httpx come client HTTP sottostante e il timeout predefinito è di 10 minuti. Per i modelli di ragionamento Grok, devi aumentarlo a 3600 secondi (un’ora) per evitare disconnessioni premature.

Comprendere httpx.Timeout

La classe httpx.Timeout accetta diversi parametri che controllano le diverse fasi della connessione:

# Timeout uniforme: 3600s per tutto
timeout = httpx.Timeout(3600.0)

# Timeout granulare
timeout = httpx.Timeout(
    connect=10.0,    # timeout connessione iniziale
    read=3600.0,     # timeout lettura risposta
    write=30.0,      # timeout invio richiesta
    pool=10.0        # tempo di attesa per una connessione libera
)

In produzione, puoi ottimizzare questi valori. La connessione iniziale dovrebbe fallire rapidamente se il server è irraggiungibile (10 secondi sono sufficienti), mentre il timeout di lettura deve essere abbastanza paziente da attendere il ragionamento del modello.

Inviare richieste

La sintassi segue il formato standard dell’SDK OpenAI, utilizzando await:

import asyncio

async def query_grok(prompt: str) -> str:
    response = await client.chat.completions.create(
        model="grok-4.20-0309-reasoning",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

result = asyncio.run(query_grok("What are the advantages of Rust over C++?"))

Vedrai la stessa struttura dell’API OpenAI: un array messages con ruoli e contenuti. La risposta segue lo stesso schema, accessibile tramite response.choices[0].message.content.

Gestione degli errori con httpx

L’SDK OpenAI con httpx fornisce eccezioni specifiche che devi intercettare:

from openai import APITimeoutError, APIConnectionError, RateLimitError

async def safe_query(prompt: str) -> str | None:
    try:
        response = await client.chat.completions.create(
            model="grok-4.20-0309-reasoning",
            messages=[{"role": "user", "content": prompt}]
        )
        return response.choices[0].message.content
    except APITimeoutError:
        print("Timeout superato: la richiesta ha impiegato troppo tempo")
        return None
    except RateLimitError:
        print("Limite di frequenza raggiunto: rallenta le richieste")
        return None
    except APIConnectionError:
        print("Impossibile connettersi al server xAI")
        return None

Le tre eccezioni più comuni sono APITimeoutError (il modello non ha risposto entro il tempo assegnato), RateLimitError (hai superato i limiti RPM/TPM) e APIConnectionError (problema di rete).

Quando scegliere AsyncOpenAI invece dell’SDK xAI

L’SDK OpenAI è preferibile se possiedi già una base di codice OpenAI, utilizzi strumenti di terze parti compatibili con OpenAI (LangChain, LiteLLM) o desideri cambiare provider senza modificare il tuo codice. L’SDK nativo di xAI, tuttavia, offre un accesso più diretto alle funzionalità specifiche di Grok, come gli strumenti integrati.

Punti chiave

  • AsyncOpenAI funziona con l’API xAI tramite base_url="https://api.x.ai/v1"
  • httpx.Timeout(3600.0) è necessario per i modelli di ragionamento
  • Il formato di richiesta e risposta è identico all’API OpenAI standard
  • Le eccezioni APITimeoutError, RateLimitError e APIConnectionError coprono i principali casi di errore
  • Questa scelta è ideale per riutilizzare codice esistente o integrare strumenti di terze parti compatibili con OpenAI