Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Format JSONL i prijenos putem Files API-ja

Lekcija 6 od 12 Ažurirano 2. studenoga 2026. Programer
Na ovoj stranici
  1. Masovna obrada s JSONL-om
  2. Struktura JSONL datoteke
  3. Generiranje JSONL datoteke u Pythonu
  4. Prijenos putem Files API-ja
  5. Stvaranje batcha iz datoteke
  6. Ograničenja JSONL formata
  7. Generiranje JSONL datoteke u JavaScriptu
  8. Validacija i otklanjanje pogrešaka
  9. Ključne točke

Ažurirano 2. studenoga 2026. na temelju xAI dokumentacije: popust za batch iznosi 20 % na kvalificirane tekstualne modele (ne 50 %), primjeri slijede REST API i službeni xai-sdk (client.batch.*; xAI-jev Batch API ne koristi OpenAI format, stoga se OpenAI SDK ne primjenjuje), a Responses API ima prednost nad Chat Completions, koji je kod xAI-ja zastarjela točka pristupa. Izvori: Batch API · REST referenca · Batch cijene.

Masovna obrada s JSONL-om

Za velike količine podataka pripremljene unaprijed, JSONL datoteka najjednostavnije je rješenje. Svoje zahtjeve upisuješ u datoteku, prenosiš je putem Files API-ja, a zatim iz te datoteke stvaraš batch. Jedna datoteka može sadržavati do 50 000 zahtjeva.

Struktura JSONL datoteke

JSONL (JSON Lines) datoteka sadrži jedan JSON objekt po retku. Svaki redak predstavlja kompletan zahtjev s četiri polja:

{"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: jedinstveni identifikator unutar datoteke; u rezultatima postaje batch_request_id
  • method: uvijek "POST"
  • url: ciljana točka pristupa, jedna od sedam prihvaćenih
  • body: tijelo zahtjeva, usklađeno s API referencom za tu točku pristupa

Svaki redak mora biti valjan, samostalan JSON: bez razdjelnih zareza, bez obuhvatnih zagrada. Točke pristupa mogu se miješati u istoj datoteci; svaki se zahtjev usmjerava neovisno.

Generiranje JSONL datoteke u Pythonu

import json

documents = [
    {"id": "doc-001", "text": "First article to summarize..."},
    {"id": "doc-002", "text": "Second article to summarize..."},
    # ... do 50 000 dokumenata po datoteci
]

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")

Prijenos putem Files API-ja

Datoteku prenosiš putem točke pristupa /v1/files, bez ikakvih drugih parametara:

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

S Python SDK-om:

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}")

Stvaranje batcha iz datoteke

Datoteka se ne dodaje u postojeći batch: navodiš je u trenutku stvaranja pomoću 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}")

Datoteka se zatim čita u pozadini. Ako je čak i jedan redak nevaljan, batch se otkazuje uz poruku o pogrešci. Praćenje i dohvaćanje rezultata zatim funkcioniraju točno kao kod batcha poslanog putem API-ja.

Ograničenja JSONL formata

  • Najviše 50 000 zahtjeva po datoteci
  • Najviše 200 MB po datoteci
  • jedinstveni custom_id po retku
  • batch stvoren iz datoteke zapečaćen je: kasnije mu ne možeš ništa dodati putem API-ja

Ako tvoj batch premašuje ova ograničenja, podijeli ga na više datoteka i stvori po jedan batch po datoteci. Ne postoji ograničenje broja batcheva po timu.

Generiranje JSONL datoteke u JavaScriptu

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");

Validacija i otklanjanje pogrešaka

Jedan nevaljan redak otkazuje cijeli batch: validiraj datoteku prije prijenosa. Jednostavna skripta pokriva osnove:

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")

Ključne točke

  • JSONL format sadrži jedan JSON objekt po retku: custom_id, method, url, body
  • Datoteku prenosiš putem /v1/files, a zatim je navodiš pri stvaranju batcha (input_file_id)
  • Najviše 50 000 zahtjeva i 200 MB po datoteci; iznad toga, jedan batch po datoteci
  • Batch stvoren iz datoteke zapečaćen je, a jedan nevaljan redak otkazuje ga u cijelosti
  • Validiraj datoteku prije prijenosa