Formát JSONL a nahrávanie cez Files API
Na tejto strane
Aktualizované 2. novembra 2026 na základe dokumentácie xAI: zľava pre batch je 20 % na kvalifikované textové modely (nie 50 %), príklady nasledujú REST API a oficiálny
xai-sdk(client.batch.*; Batch API od xAI nepoužíva formát OpenAI, takže SDK od OpenAI nie je použiteľné) a Responses API má prednosť pred Chat Completions, čo je zastaraný koncový bod v xAI. Zdroje: Batch API · REST referencia · Cenník Batch.
Hromadné spracovanie s JSONL
Pre veľké objemy dát pripravené vopred je súbor JSONL najjednoduchšou cestou. Všetky svoje požiadavky zapíšeš do súboru, nahraješ ho cez Files API a následne z neho vytvoríš batch. Jeden súbor môže obsahovať až 50 000 požiadaviek.
Štruktúra súboru JSONL
Súbor JSONL (JSON Lines) obsahuje jeden objekt JSON na každom riadku. Každý riadok predstavuje úplnú požiadavku so štyrmi poľami:
{"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: jedinečný identifikátor v rámci súboru; vo výsledkoch sa stávabatch_request_idmethod: vždy"POST"url: cieľový koncový bod, jeden zo siedmich akceptovanýchbody: telo požiadavky, zodpovedajúce referencii API pre daný koncový bod
Každý riadok musí byť platný, samostatný JSON: žiadna oddeľujúca čiarka, žiadne uzatváracie zátvorky. Koncové body sa môžu v rámci toho istého súboru miešať; každá požiadavka sa smeruje nezávisle.
Generovanie súboru JSONL v Pythone
import json
documents = [
{"id": "doc-001", "text": "First article to summarize..."},
{"id": "doc-002", "text": "Second article to summarize..."},
# ... až 50 000 dokumentov na súbor
]
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")
Nahrávanie cez Files API
Súbor nahraješ cez koncový bod /v1/files bez akýchkoľvek ďalších parametrov:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F file="@batch_requests.jsonl"
S Python SDK:
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}")
Vytvorenie batchu zo súboru
Súbor sa nepridáva do existujúceho batchu: určíš ho v čase vytvorenia pomocou 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}")
Súbor sa následne číta na pozadí. Ak je čo i len jeden riadok neplatný, batch sa zruší s chybovou správou. Sledovanie a získavanie výsledkov potom funguje presne tak ako pri batchi odoslanom priamo cez API.
Obmedzenia formátu JSONL
- Maximálne 50 000 požiadaviek na súbor
- Maximálne 200 MB na súbor
- Jedinečné
custom_idna každý riadok - Batch vytvorený zo súboru je uzavretý: neskôr cez API do neho nemôžeš nič pridať
Ak tvoj batch presahuje tieto limity, rozdeľ ho na viacero súborov a vytvor jeden batch na každý súbor. Počet batchov na tím nie je obmedzený.
Generovanie súboru JSONL v JavaScripte
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");
Validácia a ladenie
Jeden neplatný riadok zruší celý batch: pred nahratím súbor over. Jednoduchý skript pokryje to podstatné:
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")
Kľúčové poznatky
- Formát JSONL obsahuje jeden objekt JSON na riadok:
custom_id,method,url,body - Súbor nahraješ cez
/v1/filesa následne ho špecifikuješ pri vytváraní batchu (input_file_id) - Maximum 50 000 požiadaviek a 200 MB na súbor; ak to presiahneš, vytvor jeden batch na každý súbor
- Batch vytvorený zo súboru je uzavretý a jeden neplatný riadok ho celý zruší
- Pred nahratím súbor vždy validuj