Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Formát JSONL a nahrávanie cez Files API

Lekcia 6 z 12 Aktualizované 2. novembra 2026 Vývojár
Na tejto strane
  1. Hromadné spracovanie s JSONL
  2. Štruktúra súboru JSONL
  3. Generovanie súboru JSONL v Pythone
  4. Nahrávanie cez Files API
  5. Vytvorenie batchu zo súboru
  6. Obmedzenia formátu JSONL
  7. Generovanie súboru JSONL v JavaScripte
  8. Validácia a ladenie
  9. Kľúčové poznatky

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áva batch_request_id
  • method: vždy "POST"
  • url: cieľový koncový bod, jeden zo siedmich akceptovaných
  • body: 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_id na 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/files a 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