Μορφή JSONL και μεταφόρτωση μέσω του Files API
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 2 Νοεμβρίου 2026 βάσει της τεκμηρίωσης της xAI: η έκπτωση παρτίδας (batch) είναι 20% στα επιλέξιμα μοντέλα κειμένου (όχι 50%), τα παραδείγματα ακολουθούν το REST API και το επίσημο
xai-sdk(client.batch.*· το Batch API της xAI δεν χρησιμοποιεί τη μορφή της OpenAI, επομένως το SDK της OpenAI δεν εφαρμόζεται), και το Responses API έχει προτεραιότητα έναντι του Chat Completions, το οποίο αποτελεί παρωχημένο σημείο πρόσβασης στην xAI. Πηγές: Batch API · Αναφορά REST · Τιμολόγηση Batch.
Μαζική επεξεργασία με 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..."},
# ... up to 50,000 documents per file
]
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 ανά αρχείο· πέραν αυτού, μία παρτίδα ανά αρχείο
- Μια παρτίδα που δημιουργείται από αρχείο είναι σφραγισμένη και μία άκυρη γραμμή την ακυρώνει εξ ολοκλήρου
- Επικυρώστε το αρχείο πριν το μεταφορτώσετε