Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

JSONL formátum és feltöltés a Files API-n keresztül

6. lecke 12 közül Frissítve 2026. november 2. Fejlesztő
Ezen az oldalon
  1. Tömeges feldolgozás JSONL-lel
  2. JSONL-fájl szerkezete
  3. JSONL-fájl generálása Pythonban
  4. Feltöltés a Files API-n keresztül
  5. A köteg létrehozása a fájlból
  6. A JSONL-formátum korlátai
  7. JSONL-fájl generálása JavaScriptben
  8. Ellenőrzés és hibakeresés
  9. Főbb megállapítások

Frissítve: 2026. november 2. az xAI dokumentációja alapján: a kötegelt kedvezmény 20% a jogosult szöveges modellekre (nem 50%), a példák a REST API-t és a hivatalos xai-sdk-t (client.batch.*) követik (az xAI Batch API-ja nem az OpenAI formátumát használja, így az OpenAI SDK nem alkalmazható), és a Responses API elsőbbséget élvez a Chat Completions-szel szemben, amely az xAI-nál már elavult végpont. Források: Batch API · REST referenciák · Batch árazás.

Tömeges feldolgozás JSONL-lel

Nagy mennyiségű, előre elkészített adat esetén a JSONL-fájl a legegyszerűbb megoldás. Minden kérésedet egy fájlba írod, feltöltöd a Files API-n keresztül, majd ebből a fájlból hozod létre a köteget. Egyetlen fájl legfeljebb 50 000 kérést tartalmazhat.

JSONL-fájl szerkezete

A JSONL (JSON Lines) fájl soronként egy JSON-objektumot tartalmaz. Minden sor egy teljes kérést képvisel négy mezővel:

{"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: egyedi azonosító a fájlon belül; ez lesz a batch_request_id az eredményekben
  • method: mindig "POST"
  • url: a célvégpont, a hét elfogadott egyikének kell lennie
  • body: a kérés törzse, amelynek meg kell felelnie az adott végpont API-referenciájának

Minden sornak érvényes, önálló JSON-nak kell lennie: nincs elválasztó vessző, nincs körülvevő szögletes zárójel. A végpontok keverhetők ugyanabban a fájlban; minden kérés függetlenül kerül útvonalazásra.

JSONL-fájl generálása Pythonban

import json

documents = [
    {"id": "doc-001", "text": "First article to summarize..."},
    {"id": "doc-002", "text": "Second article to summarize..."},
    # ... legfeljebb 50 000 dokumentum fájlonként
]

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

Feltöltés a Files API-n keresztül

A fájlt a /v1/files végponton keresztül töltöd fel, további paraméterek nélkül:

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

A Python SDK-val:

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

A köteg létrehozása a fájlból

A fájl nem kerül hozzáadásra egy meglévő köteghez: a létrehozás pillanatában kell megadnod az input_file_id paraméterrel:

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

A rendszer ezután a háttérben beolvassa a fájlt. Ha akár csak egy sor is érvénytelen, a köteg megszakad egy hibaüzenettel. A nyomon követés és az eredmények lekérése pontosan úgy működik, mint az API-n keresztül beküldött kötegeknél.

A JSONL-formátum korlátai

  • Fájlonként maximum 50 000 kérés
  • Fájlonként maximum 200 MB
  • Soronként egyedi custom_id
  • A fájlból létrehozott köteg lezárt: később nem adhatsz hozzá új elemeket az API-n keresztül

Ha a köteged meghaladja ezeket a limiteket, oszd fel több fájlra, és hozz létre fájlonként egy köteget. A kötegek számára csapatonként nincs korlát.

JSONL-fájl generálása JavaScriptben

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

Ellenőrzés és hibakeresés

Egyetlen érvénytelen sor is megszakítja az egész köteget: ezért feltöltés előtt validáld a fájlt. Egy egyszerű script lefedi az alapokat:

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

Főbb megállapítások

  • A JSONL-formátum soronként egy JSON-objektumot tartalmaz: custom_id, method, url, body
  • A fájlt a /v1/files végponton keresztül töltöd fel, majd a köteg létrehozásakor adod meg (input_file_id)
  • Maximum 50 000 kérés és 200 MB fájlonként; efölött fájlonként egy köteg
  • A fájlból létrehozott köteg lezárt, és egyetlen érvénytelen sor is teljesen megszakítja azt
  • Feltöltés előtt mindig validáld a fájlt