JSONL formāts un augšupielāde, izmantojot Files API
Šajā lapā
Atjaunināts 2026. gada 2. novembrī, pamatojoties uz xAI dokumentāciju: atlaide par partijas apstrādi ir 20% atbilstošajiem teksta modeļiem (nevis 50%), piemēri atbilst REST API un oficiālajam
xai-sdk(client.batch.*; xAI partijas API neizmanto OpenAI formātu, tāpēc OpenAI SDK nav piemērojams), un Responses API ir prioritārs pār Chat Completions, kas xAI vidē ir novecojis galapunkts. Avoti: Batch API · REST atsauce · Partijas cenu politika.
Masveida apstrāde ar JSONL
Lieliem iepriekš sagatavotiem datu apjomiem JSONL fails ir vienkāršākais risinājums. Tu ieraksti visus savus pieprasījumus failā, augšupielādē to, izmantojot Files API, un pēc tam izveido partiju no šī faila. Vienā failā var būt līdz 50 000 pieprasījumu.
JSONL faila struktūra
JSONL (JSON Lines) fails satur vienu JSON objektu katrā rindā. Katra rinda reprezentē pilnīgu pieprasījumu ar četriem laukiem:
{"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: unikāls identifikators faila ietvaros; rezultātos tas kļūst parbatch_request_idmethod: vienmēr"POST"url: mērķa galapunkts, viens no septiņiem pieņemtajiembody: pieprasījuma ķermenis, kas atbilst šī galapunkta API atsaucei
Katrai rindai jābūt derīgam, pašpietiekamam JSON: bez atdalošām komatām, bez ietverošām iekavām. Galapunktus vienā failā var jaukt; katrs pieprasījums tiek maršrutēts neatkarīgi.
JSONL faila ģenerēšana Python valodā
import json
documents = [
{"id": "doc-001", "text": "First article to summarize..."},
{"id": "doc-002", "text": "Second article to summarize..."},
# ... līdz 50 000 dokumentu vienā failā
]
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")
Augšupielāde, izmantojot Files API
Tu augšupielādē failu, izmantojot /v1/files galapunktu, bez citiem parametriem:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F file="@batch_requests.jsonl"
Izmantojot 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}")
Partijas izveide no faila
Fails netiek pievienots esošai partijai: tu to norādi izveides brīdī, izmantojot 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}")
Pēc tam fails tiek nolasīts fona režīmā. Ja pat viena rinda ir nederīga, partija tiek atcelta ar kļūdas ziņojumu. Rezultātu izsekošana un iegūšana pēc tam darbojas tieši tāpat kā partijai, kas iesniegta caur API.
JSONL formāta ierobežojumi
- Maksimums 50 000 pieprasījumu vienā failā
- Maksimums 200 MB vienā failā
- Unikāls
custom_idkatrā rindā - No faila izveidota partija ir noslēgta: tai vēlāk nevari neko pievienot caur API
Ja tava partija pārsniedz šos ierobežojumus, sadali to vairākos failos un izveido vienu partiju katram failam. Nav ierobežojumu partiju skaitam vienā komandā.
JSONL faila ģenerēšana JavaScript valodā
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ācija un atkļūdošana
Viena nederīga rinda atceļ visu partiju: validē failu pirms augšupielādes. Vienkāršs skripts aptver būtiskāko:
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")
Galvenās atziņas
- JSONL formāts satur vienu JSON objektu katrā rindā:
custom_id,method,url,body - Tu augšupielādē failu caur
/v1/filesun pēc tam norādi to, izveidojot partiju (input_file_id) - Maksimums 50 000 pieprasījumu un 200 MB vienā failā; pārsniedzot šos limitus, veido vienu partiju katram failam
- No faila izveidota partija ir noslēgta, un viena nederīga rinda to atceļ pilnībā
- Validē failu pirms augšupielādes