Flusso di lavoro in quattro fasi
In questa pagina
Aggiornato il 2 novembre 2026 sulla base della documentazione xAI: lo sconto batch è del 20% sui modelli di testo idonei (non del 50%); gli esempi utilizzano l’API REST e l’SDK ufficiale
xai-sdk(client.batch.*; l’API Batch di xAI non segue il formato di OpenAI, quindi l’SDK di OpenAI non si applica); e l’API Responses ha la priorità rispetto a Chat Completions, un endpoint legacy su xAI. Fonti: Batch API · Riferimento REST · Prezzi Batch.
Il ciclo di vita di un batch
Ogni batch segue lo stesso ciclo: creazione, aggiunta delle richieste, elaborazione, recupero dei risultati. Comprendere questo ciclo è essenziale prima di passare all’implementazione, poiché ogni fase ha i propri vincoli e le migliori pratiche da seguire.
Fase 1: Creare un batch
Tutto inizia con una chiamata POST /v1/batches, con un campo obbligatorio: il nome del batch. L’API restituisce un identificativo univoco (batch_id) che utilizzerai per tutte le operazioni successive.
curl -X POST https://api.x.ai/v1/batches \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "customer_review_analysis"}'
La risposta contiene anche le date di creazione e scadenza del batch (create_time, expire_time) e un oggetto state i cui contatori sono tutti ancora a zero.
Fase 2: Aggiungere le richieste
Esistono due metodi:
Tramite API: invii le richieste con POST /v1/batches/{batch_id}/requests. Ogni chiamata trasporta un elenco di richieste e puoi continuarne ad aggiungere finché il batch non viene annullato. Questa è la strada per i batch costruiti in modo incrementale.
Tramite file JSONL: prepari un file contenente tutte le tue richieste, lo carichi tramite l’API Files, quindi crei il batch a partire da quel file. Il batch viene quindi sigillato: non sono più possibili aggiunte. Questa è la strada per grandi volumi preparati in anticipo.
Ogni richiesta porta con sé un identificativo univoco all’interno del batch: batch_request_id nell’API, custom_id nel file JSONL. Se lo ometti nell’API, xAI genera un UUID; forniscine uno tuo invece (un ID di database, ad esempio): funge da chiave di corrispondenza tra i tuoi dati e i risultati, e garantisce che una richiesta venga elaborata una sola volta.
Fase 3: Monitorare l’avanzamento
L’elaborazione inizia non appena arrivano le richieste; non esiste una fase di “avvio”. Nel frattempo, GET /v1/batches/{batch_id} restituisce l’oggetto state e i suoi contatori: num_requests (totale), num_pending (in attesa), num_success (riuscite), num_error (fallite) e num_cancelled (annullate).
curl https://api.x.ai/v1/batches/$BATCH_ID \
-H "Authorization: Bearer $XAI_API_KEY"
Quando num_pending scende a zero, tutte le richieste sono state elaborate, con successo o meno. Il polling periodico è sufficiente: pochi secondi per un batch di test piccolo, pochi minuti per un batch grande.
Fase 4: Recuperare i risultati
I risultati si leggono con GET /v1/batches/{batch_id}/results, senza attendere il completamento del batch: ogni richiesta è disponibile non appena viene elaborata. La risposta è paginata: limit imposta la dimensione della pagina (massimo 1.000) e il pagination_token restituito serve per richiedere la pagina successiva; è vuoto nell’ultima pagina.
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Ogni risultato riporta il batch_request_id della sua richiesta: questo ti permette di ricostruire la mappatura tra i tuoi dati di input e le risposte di Grok.
Il flusso di lavoro nella pratica
In una pipeline di produzione, il flusso di lavoro si traduce generalmente in due processi separati:
- Un processo di invio che crea il batch, prepara e aggiunge le richieste, quindi memorizza il
batch_id - Un processo di recupero che controlla periodicamente i contatori e scarica i risultati man mano che diventano disponibili
Questa separazione ti consente di integrare l’API Batch in architetture guidate da eventi o pipeline dati esistenti (job cron, Apache Airflow, code).
Gestione degli errori nel flusso di lavoro
Un batch non ha uno stato globale di “riuscito” o “fallito”: lo leggi attraverso i suoi contatori. Una richiesta fallita incrementa num_error e appare nei risultati con il suo messaggio di errore, senza bloccare le altre. Devi quindi esaminare ogni risultato e gestire i fallimenti caso per caso.
Due eventi influenzano l’intero batch. Il primo è l’annullamento, da parte tua o di xAI, che ne spiega poi il motivo nel campo cancel_by_xai_message. Questo accade in particolare quando una riga in un file JSONL non è valida. L’altro è la scadenza (expire_time), dopo la quale i risultati non sono più accessibili: recuperali tempestivamente.
Punti chiave
- Il flusso di lavoro segue l’ordine: creare (con un nome), aggiungere, monitorare, recuperare
- L’identificativo della richiesta (
batch_request_id, ocustom_idin JSONL) è la tua chiave di corrispondenza - L’avanzamento si legge dai contatori
state; tutto è elaborato quandonum_pendingè zero - I risultati sono paginati (
limit,pagination_token) e disponibili man mano che vengono elaborati - Gli errori si gestiscono richiesta per richiesta; annullamento e scadenza influenzano l’intero batch