Limiti di frequenza e best practice
In questa pagina
Aggiornato il 2 novembre 2026. Basato sulla documentazione xAI: lo sconto batch è del 20% sui modelli di testo idonei, gli esempi seguono l’API REST e l’SDK ufficiale
xai-sdk(client.batch.*; l’API Batch di xAI non utilizza il formato di OpenAI, quindi l’SDK OpenAI non si applica), e l’API Responses ha la precedenza su Chat Completions, un endpoint legacy presso xAI. Fonti: Batch API · Riferimento REST · Prezzi Batch.
Vincoli da conoscere
L’API Batch impone limiti tecnici che devi considerare nella tua architettura. Ignorarli porta a rifiuti, batch annullati o risultati persi. Questa lezione riassume i vincoli documentati da xAI e le best practice per l’uso in produzione.
Limiti di frequenza
| Vincolo | Valore | Ambito |
|---|---|---|
| Creazione batch | 2 al secondo | Per team |
| Numero di batch | Illimitato | Per team |
| Chiamate di aggiunta richieste | 1.000 ogni 30 secondi | Finestra scorrevole, condivisa tra tutti i batch del team |
| Dimensione richiesta | 25 MB | Per singola richiesta |
| Richieste per batch | Teoricamente illimitate | Oltre 100.000, l’elaborazione potrebbe essere più lenta |
Creazione batch: il limite di 2 creazioni al secondo raramente costituisce un problema, dato che generalmente crei un batch per operazione.
Aggiunta richieste: il limite si applica alle chiamate e ogni chiamata trasporta un elenco di richieste. Con blocchi di 100 richieste, ciò consente già più di 3.000 richieste al secondo.
Dimensione richiesta: il limite di 25 MB riguarda principalmente le richieste caricate con immagini codificate in base64; una richiesta di testo raramente supera pochi kilobyte.
Al contrario, le richieste batch non contano verso i limiti di frequenza dell’API in tempo reale: un batch di grandi dimensioni non rallenta la tua applicazione interattiva.
Limiti dei file JSONL
| Vincolo | Valore |
|---|---|
| Richieste per file | Massimo 50.000 |
| Dimensione file | Massimo 200 MB |
| Aggiunte dopo la creazione | Non possibili: il batch viene sigillato |
Se il tuo batch supera questi limiti, dividilo in più file e crea un batch per file; aggregherai i risultati successivamente.
Scadenza degli URL
Gli URL firmati per i risultati di immagini e video scadono dopo un’ora. Questo è il vincolo più critico da gestire in produzione: il tuo processo di recupero deve scaricare immediatamente i media, senza intervento manuale (la funzione telecharger_medias della lezione 9). Per il batch, monitora anche expire_time, dopo il quale nessun risultato è accessibile.
Best practice per la produzione
ID deterministici
Deriva gli ID delle tue richieste (batch_request_id, o custom_id in JSONL) dai tuoi dati di input. Se devi reinviare un batch, gli stessi dati produrranno gli stessi ID, rendendo più facile la deduplicazione:
import hashlib
def identifiant_requete(document_id: str, operation: str) -> str:
"""Genera un ID richiesta deterministico."""
brut = f"{document_id}:{operation}"
return hashlib.sha256(brut.encode()).hexdigest()[:16]
Gestione dei fallimenti parziali
Un batch completamente elaborato può comunque contenere richieste fallite. Controlla sempre ogni risultato:
reussies, echouees = [], []
jeton = None
while True:
page = client.batch.list_batch_results(
batch_id=batch_id, limit=1000, pagination_token=jeton
)
reussies.extend(page.succeeded)
echouees.extend(page.failed)
if page.pagination_token is None:
break
jeton = page.pagination_token
if echouees:
print(f"{len(echouees)} richieste fallite da reinviare in un nuovo batch")
Tracciamento dei costi
Ogni batch tiene traccia del suo costo totale in tick (decimiliardesimi di dollaro):
batch = client.batch.get(batch_id=batch_id)
print("Costo totale: %.4f $" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Tramite l’API REST, il costo di ogni richiesta di testo appare nel suo risultato, nel campo usage.cost_in_usd_ticks.
Log e tracciabilità
Registra ogni operazione per poter diagnosticare i problemi:
import logging
logger = logging.getLogger("batch_api")
logger.info("Batch creato: %s", batch_id)
logger.info("File caricato: %s, %d richieste", file_id, len(documents))
logger.info("Risultati: %d riusciti, %d falliti", len(reussies), len(echouees))
Retry con backoff
Per errori transitori (timeout, limite di frequenza, errore server), riprova con un ritardo crescente:
import time
def appel_avec_retry(fonction, max_essais=3):
for essai in range(max_essais):
try:
return fonction()
except Exception as e:
if essai == max_essais - 1:
raise
attente = 2 ** essai
print(f"Riprovo tra {attente} s: {e}")
time.sleep(attente)
Checklist pre-produzione
Prima di distribuire una pipeline API Batch in produzione, verifica:
- Il modello accetta l’elaborazione batch e appare nell’elenco dei modelli scontati se il costo è rilevante
- Gli ID richiesta sono unici e deterministici
- Il file JSONL è convalidato prima del caricamento (una riga non valida annulla il batch)
- Il download dei risultati multimodali è automatizzato, entro un’ora
- I fallimenti parziali sono rilevati e reinviati in un nuovo batch
- I risultati sono recuperati prima di
expire_time - I log coprono ogni fase del flusso di lavoro
- La chiave API è letta da una variabile d’ambiente, mai hardcoded
Punti chiave
- Limiti: 2 creazioni al secondo, 1.000 chiamate di aggiunta richieste ogni 30 secondi, 25 MB per richiesta
- File JSONL: massimo 50.000 richieste e 200 MB, un batch per file
- Gli URL di immagini e video scadono in un’ora: scaricali immediatamente
- ID deterministici, controllo di ogni risultato, tracciamento costi in tick
- Log, retry con backoff e un timeout massimo per la produzione
Metti alla prova le tue conoscenze
Elaborazione in blocco: l’API Batch senza zone d’ombra.
1. Quando è la scelta giusta l'API Batch?
Risposta: Per grandi volumi senza vincoli di tempo reale: classificazione, arricchimento, valutazioni, generazione in blocco. Le richieste batch non contano verso i limiti di frequenza e i modelli di testo idonei ottengono uno sconto del 20%.
2. Qual è il flusso di lavoro in quattro passaggi?
Risposta: Crea un batch denominato, aggiungi le richieste (tramite API o creando il batch da un file JSONL caricato), monitora i suoi contatori, quindi recupera i risultati man mano che arrivano o alla fine. L’elaborazione inizia autonomamente, senza un passaggio di avvio.
3. Cosa puoi inserire in un batch?
Risposta: Richieste Responses (consigliate) e Chat Completions (legacy), con strumenti server e function calling, nonché generazioni ed editing di immagini e video, ed estensioni video. Solo i token di testo per i modelli idonei ottengono lo sconto.
4. Come monitori l'esecuzione?
Risposta: Tramite i contatori del batch (num_pending, num_success, num_error…), lo stato di ogni richiesta (pending, succeeded, failed, cancelled) e i risultati paginati, che separano i successi dai fallimenti. Il batch è completamente elaborato quando num_pending è zero.
5. Quali best practice si applicano ai limiti?
Risposta: Aggiungi le richieste a blocchi, dividi i file grandi in un batch per file, scarica i media entro un’ora, recupera i risultati prima di expire_time e reinvia i fallimenti in un nuovo batch: progetta il batch come una pipeline robusta, non come una sottomissione in blocco cieca.
Batch ben formati, contatori monitorati, fallimenti ritentati: l’API Batch trasforma il volume in routine, al miglior costo.