Формат JSONL и качване чрез Files API
На тази страница
Обновено на 2 ноември 2026 г. въз основа на документацията на xAI: отстъпката за пакетна обработка е 20% за допустимите текстови модели (не 50%), примерите следват REST API и официалния
xai-sdk(client.batch.*; Batch API на xAI не използва формата на OpenAI, следователно SDK на OpenAI не се прилага), а Responses API има предимство пред Chat Completions, който е остаряла крайна точка в xAI. Източници: Batch API · REST справка · Цени за пакетна обработка.
Пакетна обработка с JSONL
За големи обеми данни, подготвени предварително, файлът във формат JSONL е най-простото решение. Записвате всички свои заявки във файл, качвате го чрез Files API и след това създавате пакетната задача от този файл. Един единствен файл може да съдържа до 50 000 заявки.
Структура на JSONL файла
Файлът JSONL (JSON Lines) съдържа по един JSON обект на ред. Всеки ред представлява пълна заявка с четири полета:
{"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: уникален идентификатор в рамките на файла; той се превръща вbatch_request_idв резултатитеmethod: винаги"POST"url: целевата крайна точка, една от седемте разрешениbody: тялото на заявката, съответстващо на справочника на API за тази крайна точка
Всеки ред трябва да бъде валиден, самостоятелен JSON: без разделителни запетаи, без обграждащи скоби. Крайните точки могат да бъдат смесени в един и същи файл; всяка заявка се маршрутизира независимо.
Генериране на JSONL файл в Python
import json
documents = [
{"id": "doc-001", "text": "First article to summarize..."},
{"id": "doc-002", "text": "Second article to summarize..."},
# ... до 50 000 документа на файл
]
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")
Качване чрез Files API
Качвате файла чрез крайната точка /v1/files, без други параметри:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F file="@batch_requests.jsonl"
С 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}")
Създаване на пакетната задача от файла
Файлът не се добавя към съществуваща пакетна задача: трябва да го посочите по време на създаването ѝ чрез 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}")
След това файлът се чете във фонов режим. Дори само един невалиден ред да бъде открит, пакетната задача се анулира със съобщение за грешка. Проследяването и извличането на резултатите след това работят точно както при пакетна задача, подадена директно чрез API.
Ограничения на формата JSONL
- Максимум 50 000 заявки на файл
- Максимум 200 MB на файл
- Уникален
custom_idза всеки ред - Пакетна задача, създадена от файл, е заключена: не можете да добавяте към нея по-късно чрез API
Ако вашата пакетна задача надвишава тези лимити, разделете я на множество файлове и създайте по една пакетна задача за всеки файл. Няма ограничение за броя на пакетните задачи на екип.
Генериране на JSONL файл в JavaScript
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");
Валидиране и отстраняване на грешки
Един невалиден ред анулира цялата пакетна задача: валидирайте файла, преди да го качите. Един прост скрипт покрива основните изисквания:
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")
Ключови изводи
- Форматът JSONL съдържа по един JSON обект на ред:
custom_id,method,url,body - Качвате файла чрез
/v1/files, след което го посочвате при създаване на пакетната задача (input_file_id) - Максимум 50 000 заявки и 200 MB на файл; при надвишаване създавайте по една пакетна задача за файл
- Пакетна задача, създадена от файл, е заключена и един невалиден ред я анулира изцяло
- Валидирайте файла преди качване