Премини към основното съдържание
Български— Изберете език
Меню

Формат JSONL и качване чрез Files API

Урок 6 от 12 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Пакетна обработка с JSONL
  2. Структура на JSONL файла
  3. Генериране на JSONL файл в Python
  4. Качване чрез Files API
  5. Създаване на пакетната задача от файла
  6. Ограничения на формата JSONL
  7. Генериране на JSONL файл в JavaScript
  8. Валидиране и отстраняване на грешки
  9. Ключови изводи

Обновено на 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 на файл; при надвишаване създавайте по една пакетна задача за файл
  • Пакетна задача, създадена от файл, е заключена и един невалиден ред я анулира изцяло
  • Валидирайте файла преди качване