xAI SDK AsyncClient
In questa pagina
Perché passare all’asincrono
Quando interroghi le API xAI in modo sincrono, ogni chiamata blocca l’esecuzione del tuo programma fino all’arrivo della risposta. Per un modello di ragionamento come grok-4.5, una singola richiesta può richiedere diverse decine di secondi. Se devi elaborare 100 richieste, il tempo di attesa totale diventa proibitivo.
La modalità asincrona risolve questo problema. Invece di attendere ogni risposta, il tuo programma avvia la richiesta e prosegue l’esecuzione. Recuperi il risultato successivamente, quando è disponibile. Questo approccio ti consente di elaborare più richieste in parallelo e di sfruttare appieno la tua banda verso le API.
Inizializzare l’AsyncClient
L’SDK xAI fornisce la classe AsyncClient dedicata alle chiamate asincrone. L’inizializzazione è simile a quella del client sincrono, con un parametro timeout che devi sempre configurare:
import os
from xai_sdk import AsyncClient
from xai_sdk.chat import user
client = AsyncClient(
api_key=os.getenv("XAI_API_KEY"),
timeout=3600,
)
timeout=3600 equivale a un’ora. Questo valore potrebbe sembrare elevato, ma è necessario per i modelli di ragionamento che eseguono processi logici estesi prima di rispondere. Un timeout troppo breve causa errori di disconnessione su richieste complesse.
Inviare una richiesta asincrona
Una volta inizializzato il client, invii le richieste utilizzando la sintassi await di Python:
import asyncio
async def ask_grok(question: str) -> str:
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
max_tokens=500
)
chat.append(user(question))
response = await chat.sample()
return response.text
# Punto di ingresso
result = asyncio.run(ask_grok("Explain the algorithmic complexity of quicksort"))
print(result)
La funzione ask_grok utilizza async def, rendendola una coroutina. La chiamata await chat.sample() sospende questa coroutina fino all’arrivo della risposta, senza bloccare altre potenziali attività.
Differenze rispetto al client sincrono
Il client sincrono blocca il thread corrente per l’intera durata della richiesta. Il client asincrono libera il thread per eseguire altre coroutines. Questa distinzione non ha importanza se invii una sola richiesta, ma diventa critica quando elabori più richieste in parallelo.
# Sync: ogni chiamata attende la risposta
for question in questions:
response = client.chat.completions.create(...) # bloccante
process(response)
# Async: le chiamate vengono eseguite in parallelo
async def main():
tasks = [ask_grok(q) for q in questions]
responses = await asyncio.gather(*tasks) # parallelo
for r in responses:
process(r)
Nell’esempio sincrono, se ogni richiesta richiede 10 secondi e ne hai 20, il tempo totale è di 200 secondi. In modalità asincrona, con un semaforo di 5 (che scoprirai nelle lezioni successive), il tempo scende a circa 40 secondi.
Punti chiave
- L’
AsyncClientdell’SDK xAI ti permette di inviare richieste senza bloccare l’esecuzione - Il parametro
timeout=3600è essenziale per i modelli di ragionamento xai-sdkrichiede Python 3.10 o successivo (versione 1.21.0 al 2 novembre 2026, secondo PyPI)- Il vero vantaggio emerge quando si elaborano più richieste in parallelo
asyncio.run()funge da punto di ingresso per eseguire una coroutina da codice sincrono