Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Aggiungere richieste in JSON

Lezione 5 di 12 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Aggiunta tramite API
  2. Struttura della richiesta
  3. Richiesta cURL
  4. Aggiunta con l’SDK Python
  5. Limiti di frequenza per l’aggiunta
  6. Quando utilizzare l’aggiunta via API
  7. Validazione delle richieste
  8. Punti chiave

Aggiornato il 2 novembre 2026 sulla base della documentazione xAI: lo sconto per i batch è del 20% sui modelli di testo idonei (non del 50%), gli esempi seguono l’API REST e l’SDK ufficiale xai-sdk (client.batch.*; l’API Batch di xAI non utilizza il formato OpenAI, quindi l’SDK OpenAI non si applica) e le API Responses hanno la priorità rispetto alle Chat Completions, un endpoint legacy su xAI. Fonti: Batch API · Riferimento REST · Prezzi Batch.

Aggiunta tramite API

Una volta creato il batch, aggiungi le richieste utilizzando POST /v1/batches/{batch_id}/requests. Ogni chiamata trasporta un elenco di richieste e puoi invocare l’endpoint quante volte necessario, purché il batch non sia stato annullato. Questo approccio è ideale per i batch costruiti in modo incrementale.

Struttura della richiesta

Il corpo della chiamata contiene un array batch_requests. Ogni elemento associa un identificatore (batch_request_id) alla richiesta vera e propria, archiviata sotto la chiave corrispondente al suo tipo: responses per le API Responses:

{
  "batch_requests": [
    {
      "batch_request_id": "avis-001",
      "batch_request": {
        "responses": {
          "model": "grok-4.3",
          "input": [
            {"role": "system", "content": "Classifica il sentiment: positivo, negativo o neutro."},
            {"role": "user", "content": "Il prodotto ha superato le mie aspettative!"}
          ]
        }
      }
    }
  ]
}
  • batch_request_id: Il tuo identificatore, unico all’interno del batch. È la chiave che collega la richiesta al suo risultato; se mancante, xAI genera un UUID.
  • batch_request: La richiesta, inserita sotto la chiave del suo tipo; il riferimento API documenta anche chat_get_completion per il formato Chat Completions.

Per immagini e video, utilizza l’SDK (lezione 9) o un file JSONL (prossima lezione).

Richiesta cURL

curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID/requests" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_requests": [
      {
        "batch_request_id": "article-42",
        "batch_request": {
          "responses": {
            "model": "grok-4.3",
            "input": [
              {"role": "user", "content": "Classifica questo testo: positivo, neutro o negativo."}
            ]
          }
        }
      }
    ]
  }'

Aggiunta con l’SDK Python

Con l’SDK, ogni richiesta viene costruita come una conversazione standard, assegnandole un batch_request_id; successivamente le aggiungi a blocchi:

from xai_sdk import Client
from xai_sdk.chat import system, user

client = Client()

documents = [
    {"id": "doc-1", "text": "Primo documento da analizzare..."},
    {"id": "doc-2", "text": "Secondo documento da analizzare..."},
    {"id": "doc-3", "text": "Terzo documento da analizzare..."},
]

batch_id = "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8"

requests = []
for doc in documents:
    chat = client.chat.create(model="grok-4.3", batch_request_id=doc["id"])
    chat.append(system("Riassumi il documento in due frasi."))
    chat.append(user(doc["text"]))
    requests.append(chat)

# Aggiungi a blocchi di 100: una chiamata API per blocco
for i in range(0, len(requests), 100):
    client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])

La documentazione non impone un numero massimo di richieste per chiamata; dimensioni moderate dei blocchi limitano semplicemente la quantità di dati da reinviare in caso di problemi di rete.

Limiti di frequenza per l’aggiunta

Un team può effettuare fino a 1.000 chiamate di aggiunta ogni 30 secondi, in una finestra scorrevole condivisa tra tutti i suoi batch. Il limite si applica alle chiamate, non alle singole richieste: con blocchi di 100 richieste, questo consente già di elaborare oltre 3.000 richieste al secondo. Due altri vincoli sono più rilevanti:

  • 25 MB massimi per singola richiesta, aspetto che riguarda principalmente le immagini codificate in base64.
  • Oltre 100.000 richieste in un batch, xAI potrebbe rallentare l’elaborazione per preservare la stabilità del servizio.

Quando utilizzare l’aggiunta via API

L’aggiunta via API è preferibile quando la flessibilità conta più della preparazione iniziale. Diventa la scelta naturale quando il batch viene costruito in modo incrementale: le richieste che arrivano da una coda vengono aggiunte man mano che pervengono, mentre un file JSONL richiederebbe di conoscere tutto in anticipo e chiuderebbe il batch. È anche la strada maestra per il prototipaggio, per testare l’intero flusso di lavoro con cinque richieste prima di scalare, e per gestire batch eterogenei.

Validazione delle richieste

Controlla il codice di stato di ogni chiamata di aggiunta: un errore in questa fase significa che il blocco non è stato salvato e devi reinviarlo. Una richiesta può anche fallire successivamente, durante l’elaborazione; in tal caso apparirà nei risultati con il relativo messaggio di errore. Un modello che non accetta il batch viene rifiutato con il messaggio not supported for batch processing: verifica l’idoneità nella pagina del modello prima di lanciare un batch di grandi dimensioni.

Punti chiave

  • L’aggiunta avviene tramite POST /v1/batches/{id}/requests, con un elenco batch_requests.
  • Ogni richiesta include un batch_request_id unico e il suo contenuto sotto la chiave del tipo (responses, chat_get_completion).
  • L’SDK costruisce le richieste con client.chat.create(..., batch_request_id=...) e le aggiunge con client.batch.add.
  • Il limite è di 1.000 chiamate di aggiunta ogni 30 secondi per team; ogni chiamata può trasportare molte richieste.
  • A differenza del file JSONL, l’aggiunta via API lascia il batch aperto a nuove aggiunte.