Client asincrono e prestazioni
In questa pagina
Aggiornato il 3 novembre 2026 sulla base della pagina Limiti di frequenza di xAI e del riferimento API Images: i limiti del modello Imagine contano come richieste al secondo—6 al livello base, 100 al livello più alto—non “30 al minuto”; un semaforo limita le richieste concorrenti, non il throughput; le immagini vengono prodotte in JPEG di default; e i tempi specifici della vecchia versione, privi di misurazioni pubblicate, lasciano il posto a un calcolo. Fonti: Limiti di frequenza · API Images.
Ottimizza le prestazioni con l’asincronia
Quando devi generare o modificare molte immagini, le chiamate sequenziali diventano un collo di bottiglia. Il client asincrono delle API xAI ti permette di eseguire più richieste in parallelo, riducendo significativamente il tempo totale di elaborazione.
Il client AsyncOpenAI
L’asincronia non rende una singola generazione più veloce: una richiesta di immagine singola richiede esattamente lo stesso tempo. Ciò che elimina è l’attesa inutile tra le richieste: mentre la prima immagine viene calcolata sul server, il tuo programma può richiederne altre dieci invece di rimanere bloccato. Ecco perché il guadagno è nullo per un’immagine e drammatico per cinquanta.
from openai import AsyncOpenAI
import asyncio
import os
async_client = AsyncOpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1"
)
async def generate_image(prompt):
"""Genera un'immagine in modo asincrono."""
response = await async_client.images.generate(
model="grok-imagine-image",
prompt=prompt,
extra_body={"resolution": "1k"},
)
return response.data[0].url
async def main():
url = await generate_image("A lighthouse on a cliff, watercolor style")
print(url)
asyncio.run(main())
Richieste parallele con asyncio.gather
asyncio.gather avvia tutte le richieste e attende poi che l’insieme termini. La durata totale diventa quella della richiesta più lenta, non la somma di tutte: questa è l’intera differenza, e la noti già con sole tre o quattro immagini.
async def generate_batch(prompts):
"""Genera immagini per più prompt in parallelo."""
tasks = [generate_image(prompt) for prompt in prompts]
results = await asyncio.gather(*tasks)
return results
async def main():
prompts = [
"Portrait of an engineer, corporate style",
"Panoramic view of a futuristic city",
"Isometric diagram of a data center",
"Abstract blue and silver logo",
"Illustration of a team in a meeting"
]
urls = await generate_batch(prompts)
for prompt, url in zip(prompts, urls):
print(f"{prompt[:40]}... → {url}")
asyncio.run(main())
Con cinque prompt, invece di attendere che ogni richiesta termini prima di lanciare la successiva, tutte e cinque le immagini vengono calcolate contemporaneamente: il tempo totale si avvicina a quello della richiesta più lenta.
Controlla il parallelismo
Senza un limite, gather lancia tutto in una volta: cinquanta richieste concorrenti su un modello limitato a 6 richieste al secondo al livello base producono un’ondata di errori 429 che ti costa più tempo dell’esecuzione sequenziale. Il semaforo non è quindi una precauzione opzionale: è ciò che rende il parallelismo utilizzabile. Calibralo sul limite di frequenza del modello, mai sulla capacità della tua macchina.
async def generate_with_limit(prompts, max_concurrent=5):
"""Genera immagini con un numero massimo di richieste parallele."""
semaphore = asyncio.Semaphore(max_concurrent)
async def limited_generate(prompt):
async with semaphore:
return await generate_image(prompt)
tasks = [limited_generate(prompt) for prompt in prompts]
return await asyncio.gather(*tasks)
I fogli ufficiali per grok-imagine-image e grok-imagine-image-2.0 indicano 6 richieste al secondo al livello base, un limite che cresce con il livello del tuo team fino a 100. Nota: un semaforo limita le richieste concorrenti, non il throughput. Con max_concurrent=5, resti sotto le 6 richieste al secondo finché ogni generazione dura più di un secondo; se le tue risposte arrivano più velocemente, distanzia anche le sottomissioni. Controlla i limiti del tuo team nella console xAI prima di aumentarli.
Pipeline asincrona completa
Questa pipeline concatena le tre operazioni che devono andare insieme: generare, scaricare immediatamente—gli URL scadono—e isolare i guasti. Su un batch ampio, questo terzo punto fa la differenza tra un incidente e una perdita totale.
import aiohttp
import aiofiles
async def download_image(session, url, filepath):
"""Scarica un'immagine in modo asincrono."""
async with session.get(url) as resp:
if resp.status == 200:
async with aiofiles.open(filepath, "wb") as f:
await f.write(await resp.read())
return filepath
return None
async def pipeline(prompts, output_dir="output"):
"""Pipeline completa: generazione + download."""
os.makedirs(output_dir, exist_ok=True)
# Passo 1: genera tutte le immagini in parallelo
urls = await generate_with_limit(prompts, max_concurrent=5)
# Passo 2: scarica tutte le immagini in parallelo
async with aiohttp.ClientSession() as session:
download_tasks = []
for i, url in enumerate(urls):
if url:
# JPEG di default (image/jpeg), a meno che l'impostazione di qualità non produca PNG
filepath = os.path.join(output_dir, f"image_{i:03d}.jpg")
download_tasks.append(download_image(session, url, filepath))
saved_files = await asyncio.gather(*download_tasks)
count = sum(1 for f in saved_files if f)
print(f"{count}/{len(prompts)} immagini generate e salvate")
Confronto tra sincrono e asincrono
Il guadagno si calcola sulla carta. Se una generazione richiede T secondi, venti immagini richieste una dopo l’altra richiedono circa 20 × T. Con cinque richieste concorrenti, procedono a ondate di cinque: circa 4 × T, un guadagno vicino a cinque, il numero di richieste concorrenti—purché tu resti sotto il limite di throughput. Misura T sul tuo account prima di promettere una scadenza: le pagine immagini di xAI non forniscono tempi di generazione, che variano in base al modello, alla risoluzione e al carico.
Gestione degli errori
Il comportamento predefinito di gather è brutale: un’eccezione in un task propaga l’errore e perdi i risultati degli altri, inclusi quelli già pagati. return_exceptions=True cambia le cose: ogni task restituisce il suo risultato o la sua eccezione, e decidi cosa fare dei guasti senza sacrificare i successi.
async def safe_generate(prompt):
"""Genera un'immagine con gestione degli errori."""
try:
return await generate_image(prompt)
except Exception as e:
print(f"Errore per '{prompt[:30]}...' : {e}")
return None
Punti chiave
- Il client
AsyncOpenAIabilita richieste parallele tramiteasyncio - Usa
asyncio.gatherper lanciare più generazioni simultaneamente - Limita la concorrenza con un semaforo per rispettare i limiti di frequenza
- Il guadagno si avvicina al numero di richieste concorrenti, entro il limite di throughput autorizzato (6 richieste al secondo al livello base)
- Gestisci gli errori singolarmente per evitare di perdere l’intero batch