AsyncOpenAI con httpx.Timeout
In questa pagina
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
AsyncOpenAIfunziona con l’API xAI tramitebase_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,RateLimitErroreAPIConnectionErrorcoprono i principali casi di errore - Questa scelta è ideale per riutilizzare codice esistente o integrare strumenti di terze parti compatibili con OpenAI