Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Μορφή JSONL και μεταφόρτωση μέσω του Files API

Μάθημα 6 / 12 Ενημερώθηκε 2 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Μαζική επεξεργασία με JSONL
  2. Δομή αρχείου JSONL
  3. Δημιουργία αρχείου JSONL σε Python
  4. Μεταφόρτωση μέσω του Files API
  5. Δημιουργία της παρτίδας από το αρχείο
  6. Όρια μορφής JSONL
  7. Δημιουργία αρχείου JSONL σε JavaScript
  8. Επικύρωση και αποσφαλμάτωση
  9. Βασικά σημεία

Ενημερώθηκε στις 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 ανά αρχείο· πέραν αυτού, μία παρτίδα ανά αρχείο
  • Μια παρτίδα που δημιουργείται από αρχείο είναι σφραγισμένη και μία άκυρη γραμμή την ακυρώνει εξ ολοκλήρου
  • Επικυρώστε το αρχείο πριν το μεταφορτώσετε