Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Formato JSONL e caricamento tramite Files API

Lezione 6 di 12 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Elaborazione in blocco con JSONL
  2. Struttura del file JSONL
  3. Generare un file JSONL in Python
  4. Caricamento tramite Files API
  5. Creare il batch dal file
  6. Limiti del formato JSONL
  7. Generare un file JSONL in JavaScript
  8. Validazione e debug
  9. Punti chiave

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

Elaborazione in blocco con JSONL

Per grandi volumi di dati preparati in anticipo, un file JSONL è la via più semplice. Scrivi tutte le tue richieste in un file, lo carichi tramite le Files API, quindi crei il batch da quel file. Un singolo file può contenere fino a 50.000 richieste.

Struttura del file JSONL

Un file JSONL (JSON Lines) contiene un oggetto JSON per riga. Ogni riga rappresenta una richiesta completa con quattro campi:

{"custom_id": "req-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "Summarize this text in one sentence: ..."}]}}
{"custom_id": "req-2", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "Classify this ticket: bug, feature, or question. ..."}]}}
{"custom_id": "req-3", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "grok-4.3", "messages": [{"role": "user", "content": "Translate into English: ..."}]}}
  • custom_id: un identificatore univoco all’interno del file; diventa il batch_request_id nei risultati
  • method: sempre "POST"
  • url: l’endpoint di destinazione, uno dei sette accettati
  • body: il corpo della richiesta, conforme al riferimento API per quell’endpoint

Ogni riga deve essere un JSON valido e autonomo: nessuna virgola di separazione, nessuna parentesi di chiusura. Gli endpoint possono essere mescolati nello stesso file; ogni richiesta viene instradata indipendentemente.

Generare un file JSONL in Python

import json

documents = [
    {"id": "doc-001", "text": "First article to summarize..."},
    {"id": "doc-002", "text": "Second article to summarize..."},
    # ... fino a 50.000 documenti per file
]

with open("batch_requests.jsonl", "w", encoding="utf-8") as f:
    for doc in documents:
        ligne = {
            "custom_id": doc["id"],
            "method": "POST",
            "url": "/v1/responses",
            "body": {
                "model": "grok-4.3",
                "input": [
                    {"role": "system", "content": "Summarize in three sentences."},
                    {"role": "user", "content": doc["text"]},
                ],
            },
        }
        f.write(json.dumps(ligne, ensure_ascii=False) + "\n")

Caricamento tramite Files API

Carichi il file tramite l’endpoint /v1/files, senza altri parametri:

curl -X POST https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F file="@batch_requests.jsonl"

Con l’SDK Python:

from xai_sdk import Client

client = Client()

with open("batch_requests.jsonl", "rb") as f:
    fichier = client.files.upload(f, filename="batch_requests.jsonl")
print(f"Uploaded file: {fichier.id}")

Creare il batch dal file

Il file non viene aggiunto a un batch esistente: lo specifichi al momento della creazione con input_file_id:

curl -X POST https://api.x.ai/v1/batches \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "article_summaries", "input_file_id": "file-abc123"}'
batch = client.batch.create(batch_name="article_summaries", input_file_id=fichier.id)
print(f"Batch created: {batch.batch_id}")

Il file viene quindi letto in background. Se anche una sola riga non è valida, il batch viene annullato con un messaggio di errore. Il monitoraggio e il recupero dei risultati funzionano esattamente come per un batch inviato tramite API.

Limiti del formato JSONL

  • Massimo 50.000 richieste per file
  • Massimo 200 MB per file
  • un custom_id univoco per riga
  • un batch creato da un file è sigillato: non puoi aggiungergli elementi in seguito tramite API

Se il tuo batch supera questi limiti, dividilo in più file e crea un batch per file. Non c’è limite al numero di batch per team.

Generare un file JSONL in JavaScript

import fs from "fs";

const documents = [
  { id: "doc-001", text: "First article..." },
  { id: "doc-002", text: "Second article..." },
];

const lines = documents.map(doc => JSON.stringify({
  custom_id: doc.id,
  method: "POST",
  url: "/v1/responses",
  body: {
    model: "grok-4.3",
    input: [
      { role: "user", content: `Summarize: ${doc.text}` }
    ]
  }
}));

fs.writeFileSync("batch_requests.jsonl", lines.join("\n") + "\n");

Validazione e debug

Una singola riga non valida annulla l’intero batch: valida il file prima di caricarlo. Uno script semplice copre l’essenziale:

import json
import os

ENDPOINTS = {
    "/v1/responses", "/v1/chat/completions",
    "/v1/images/generations", "/v1/images/edits",
    "/v1/videos/generations", "/v1/videos", "/v1/videos/edits", "/v1/videos/extensions",
}

def valider_jsonl(chemin: str) -> list[str]:
    erreurs, ids = [], set()
    if os.path.getsize(chemin) > 200 * 1024 * 1024:
        erreurs.append("file larger than 200 MB")
    with open(chemin, encoding="utf-8") as f:
        for i, ligne in enumerate(f, 1):
            try:
                obj = json.loads(ligne)
            except json.JSONDecodeError as e:
                erreurs.append(f"line {i}: invalid JSON ({e})")
                continue
            cid = obj.get("custom_id")
            if not cid or cid in ids:
                erreurs.append(f"line {i}: missing or duplicate custom_id")
            ids.add(cid)
            if obj.get("method") != "POST" or obj.get("url") not in ENDPOINTS:
                erreurs.append(f"line {i}: invalid method or url")
            if not isinstance(obj.get("body"), dict):
                erreurs.append(f"line {i}: missing body")
    if len(ids) > 50_000:
        erreurs.append("more than 50,000 requests")
    return erreurs

print(valider_jsonl("batch_requests.jsonl") or "File is valid")

Punti chiave

  • Il formato JSONL contiene un oggetto JSON per riga: custom_id, method, url, body
  • Carichi il file tramite /v1/files, quindi lo specifichi durante la creazione del batch (input_file_id)
  • Massimo 50.000 richieste e 200 MB per file; oltre tale limite, un batch per file
  • Un batch creato da un file è sigillato e una singola riga non valida lo annulla interamente
  • Valida il file prima di caricarlo