Format JSONL in nalaganje prek API-ja za datoteke
Na tej strani
Posodobljeno 2. novembra 2026 na podlagi dokumentacije xAI: popust za paketne obdelave znaša 20 % za upravičene besedilne modele (ne 50 %), primeri sledijo REST API-ju in uradnemu paketu
xai-sdk(client.batch.*; paketni API xAI ne uporablja formata OpenAI, zato paket SDK OpenAI ni primeren), API Responses pa ima prednost pred Chat Completions, ki je pri xAI zastarela končna točka. Viri: Batch API · Referenca REST · Cenik za paketne obdelave.
Paketna obdelava s formatom JSONL
Za velike količine vnaprej pripravljenih podatkov je datoteka JSONL najpreprostejša pot. Vse zahteve zapišeš v datoteko, jo naložiš prek API-ja za datoteke (Files API) in nato iz te datoteke ustvariš paketno obdelavo. Ena sama datoteka lahko vsebuje do 50.000 zahtev.
Struktura datoteke JSONL
Datoteka JSONL (JSON Lines) vsebuje en objekt JSON na vrstico. Vsaka vrstica predstavlja popolno zahtevo s štirimi polji:
{"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: edinstven identifikator znotraj datoteke; v rezultatih postanebatch_request_idmethod: vedno"POST"url: ciljna končna točka, ena od sedmih sprejetihbody: telo zahteve, ki ustreza referenci API-ja za to končno točko
Vsaka vrstica mora biti veljaven, samostojen JSON: brez ločilnih vejic, brez obdajajočih oglatih oklepajev. Končne točke se lahko v isti datoteki mešajo; vsaka zahteva se usmeri neodvisno.
Ustvarjanje datoteke JSONL v Pythonu
import json
documents = [
{"id": "doc-001", "text": "First article to summarize..."},
{"id": "doc-002", "text": "Second article to summarize..."},
# ... do 50.000 dokumentov na datoteko
]
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")
Nalaganje prek API-ja za datoteke
Datoteko naložiš prek končne točke /v1/files, brez drugih parametrov:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F file="@batch_requests.jsonl"
S paketom SDK za 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}")
Ustvarjanje paketne obdelave iz datoteke
Datoteka se ne doda obstoječi paketni obdelavi; določiš jo ob ustvarjanju s parametrom 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 nato prebere v ozadju. Če je čeprav ena vrstica neveljavna, se paketna obdelava prekliče s sporočilom o napaki. Spremljanje in pridobivanje rezultatov nato potekata popolnoma enako kot pri paketni obdelavi, oddani prek API-ja.
Omejitve formata JSONL
- Največ 50.000 zahtev na datoteko
- Največ 200 MB na datoteko
- Edinstven
custom_idna vrstico - Paketna obdelava, ustvarjena iz datoteke, je zaklenjena: kasneje ji prek API-ja ne moreš ničesar dodati
Če tvoja paketna obdelava presega te omejitve, jo razdeli na več datotek in ustvari eno paketno obdelavo na datoteko. Število paketnih obdelav na ekipo ni omejeno.
Ustvarjanje datoteke JSONL v 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");
Preverjanje veljavnosti in odpravljanje napak
Ena sama neveljavna vrstica prekliče celotno paketno obdelavo: pred nalaganjem preveri veljavnost datoteke. Preprosta skripta pokriva bistveno:
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 ugotovitve
- Format JSONL vsebuje en objekt JSON na vrstico:
custom_id,method,url,body - Datoteko naložiš prek
/v1/files, nato pa jo določiš ob ustvarjanju paketne obdelave (input_file_id) - Največ 50.000 zahtev in 200 MB na datoteko; če presežeš te meje, ustvari eno paketno obdelavo na datoteko
- Paketna obdelava, ustvarjena iz datoteke, je zaklenjena in ena sama neveljavna vrstica jo v celoti prekliče
- Pred nalaganjem preveri veljavnost datoteke