Format JSONL i przesyłanie przez Files API
Na tej stronie
Zaktualizowano 2 listopada 2026 r. na podstawie dokumentacji xAI: rabat na wsady (batch) wynosi 20% dla kwalifikujących się modeli tekstowych (a nie 50%), przykłady odnoszą się do REST API oraz oficjalnego
xai-sdk(client.batch.*; Batch API od xAI nie używa formatu OpenAI, więc SDK OpenAI nie ma zastosowania), a Responses API ma pierwszeństwo przed Chat Completions, które są przestarzałym punktem końcowym w xAI. Źródła: Batch API · Referencje REST · Cennik Batch.
Przetwarzanie wsadowe z użyciem JSONL
W przypadku dużych wolumenów danych przygotowanych wcześniej, plik JSONL jest najprostszą drogą. Zapisujesz wszystkie swoje żądania w pliku, przesyłasz go przez Files API, a następnie tworzysz wsad na podstawie tego pliku. Pojedynczy plik może zawierać do 50 000 żądań.
Struktura pliku JSONL
Plik JSONL (JSON Lines) zawiera jeden obiekt JSON w każdej linii. Każda linia reprezentuje kompletne żądanie z czterema polami:
{"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: unikalny identyfikator w obrębie pliku; staje siębatch_request_idw wynikachmethod: zawsze"POST"url: docelowy punkt końcowy, jeden z siedmiu akceptowanychbody: treść żądania, zgodna z referencjami API dla danego punktu końcowego
Każda linia musi być poprawnym, samowystarczalnym kodem JSON: bez przecinków rozdzielających, bez nawiasów zamykających całość. Punkty końcowe mogą być mieszane w tym samym pliku; każde żądanie jest routowane niezależnie.
Generowanie pliku JSONL w Pythonie
import json
documents = [
{"id": "doc-001", "text": "First article to summarize..."},
{"id": "doc-002", "text": "Second article to summarize..."},
# ... do 50 000 dokumentów na plik
]
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")
Przesyłanie przez Files API
Przesyłasz plik przez punkt końcowy /v1/files, bez żadnych innych parametrów:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F file="@batch_requests.jsonl"
Z użyciem 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}")
Tworzenie wsadu na podstawie pliku
Plik nie jest dodawany do istniejącego wsadu: wskazujesz go w momencie tworzenia, używając 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}")
Plik jest następnie odczytywany w tle. Jeśli nawet jedna linia jest nieprawidłowa, wsad zostaje anulowany z komunikatem o błędzie. Śledzenie i pobieranie wyników działa dokładnie tak samo jak w przypadku wsadu przesłanego bezpośrednio przez API.
Ograniczenia formatu JSONL
- Maksymalnie 50 000 żądań na plik
- Maksymalnie 200 MB na plik
- Unikalne
custom_iddla każdej linii - Wsad utworzony z pliku jest zapieczętowany: nie możesz dodać do niego później danych przez API
Jeśli Twój wsad przekracza te limity, podziel go na wiele plików i utwórz jeden wsad na plik. Nie ma limitu liczby wsadów na zespół.
Generowanie pliku JSONL w 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");
Walidacja i debugowanie
Jedna nieprawidłowa linia anuluje cały wsad: zwaliduj plik przed jego przesłaniem. Prosty skrypt pokrywa podstawowe aspekty:
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")
Kluczowe wnioski
- Format JSONL zawiera jeden obiekt JSON w każdej linii:
custom_id,method,url,body - Przesyłasz plik przez
/v1/files, a następnie wskazujesz go podczas tworzenia wsadu (input_file_id) - Maksymalnie 50 000 żądań i 200 MB na plik; powyżej tych limitów tworzy się jeden wsad na plik
- Wsad utworzony z pliku jest zapieczętowany, a jedna nieprawidłowa linia anuluje go w całości
- Zweryfikuj plik przed przesłaniem