Vai al contenuto principale
Italiano— Scegli una lingua
Menu

xAI SDK AsyncClient

Lezione 1 di 12 Aggiornata il 2 novembre 2026 Avanzato
In questa pagina
  1. Perché passare all’asincrono
  2. Inizializzare l’AsyncClient
  3. Inviare una richiesta asincrona
  4. Differenze rispetto al client sincrono
  5. Punti chiave

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.

3600s
Timeout consigliato
5x
Throughput parallelo
-50%
Alternativa alle API batch
RPM
Limite di frequenza da rispettare

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’AsyncClient dell’SDK xAI ti permette di inviare richieste senza bloccare l’esecuzione
  • Il parametro timeout=3600 è essenziale per i modelli di ragionamento
  • xai-sdk richiede 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