Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Flusso di lavoro in quattro fasi

Lezione 2 di 12 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Il ciclo di vita di un batch
  2. Fase 1: Creare un batch
  3. Fase 2: Aggiungere le richieste
  4. Fase 3: Monitorare l’avanzamento
  5. Fase 4: Recuperare i risultati
  6. Il flusso di lavoro nella pratica
  7. Gestione degli errori nel flusso di lavoro
  8. Punti chiave

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, o custom_id in JSONL) è la tua chiave di corrispondenza
  • L’avanzamento si legge dai contatori state; tutto è elaborato quando num_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