Salt la conținutul principal
Română— Alege o limbă
Meniu

Format JSONL și încărcare prin API-ul Files

Lecția 6 din 12 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Procesare în masă cu JSONL
  2. Structura fișierului JSONL
  3. Generarea unui fișier JSONL în Python
  4. Încărcare prin API-ul Files
  5. Crearea lotului din fișier
  6. Limitele formatului JSONL
  7. Generarea unui fișier JSONL în JavaScript
  8. Validare și depanare
  9. Puncte cheie

Actualizat la 2 noiembrie 2026 pe baza documentației xAI: reducerea pentru loturi este de 20% la modelele de text eligibile (nu 50%), exemplele urmează API-ul REST și SDK-ul oficial xai-sdk (client.batch.*; API-ul Batch al xAI nu folosește formatul OpenAI, deci SDK-ul OpenAI nu se aplică), iar API-ul Responses are prioritate față de Chat Completions, un endpoint moștenit la xAI. Surse: Batch API · Referință REST · Prețuri Batch.

Procesare în masă cu JSONL

Pentru volume mari pregătite în avans, un fișier JSONL reprezintă cea mai simplă soluție. Scrieți toate cererile într-un fișier, îl încărcați prin API-ul Files, apoi creați lotul pe baza acelui fișier. Un singur fișier poate conține până la 50.000 de cereri.

Structura fișierului JSONL

Un fișier JSONL (JSON Lines) conține un obiect JSON pe fiecare linie. Fiecare linie reprezintă o cerere completă cu patru câmpuri:

{"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: un identificator unic în cadrul fișierului; devine batch_request_id în rezultate
  • method: întotdeauna "POST"
  • url: endpoint-ul țintă, unul dintre cele șapte acceptate
  • body: corpul cererii, corespunzător referinței API pentru acel endpoint

Fiecare linie trebuie să fie un JSON valid și autonom: fără virgulă de separare, fără paranteze de încadrare. Endpoint-urile pot fi amestecate în același fișier; fiecare cerere este dirijată independent.

Generarea unui fișier JSONL în Python

import json

documents = [
    {"id": "doc-001", "text": "First article to summarize..."},
    {"id": "doc-002", "text": "Second article to summarize..."},
    # ... până la 50.000 de documente per fișier
]

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")

Încărcare prin API-ul Files

Încărcați fișierul prin endpoint-ul /v1/files, fără alți parametri:

curl -X POST https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F file="@batch_requests.jsonl"

Cu SDK-ul Python:

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}")

Crearea lotului din fișier

Fișierul nu este adăugat unui lot existent: îl specificați la momentul creării cu 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}")

Fișierul este apoi citit în fundal. Dacă chiar și o singură linie este invalidă, lotul este anulat cu un mesaj de eroare. Urmărirea și recuperarea rezultatelor funcționează exact ca pentru un lot trimis prin API.

Limitele formatului JSONL

  • Maxim 50.000 de cereri per fișier
  • Maxim 200 MB per fișier
  • Un custom_id unic pe linie
  • Un lot creat dintr-un fișier este sigilat: nu îi puteți adăuga elemente ulterior prin API

Dacă lotul dumneavoastră depășește aceste limite, divizați-l în mai multe fișiere și creați câte un lot per fișier. Nu există o limită a numărului de loturi per echipă.

Generarea unui fișier JSONL în 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");

Validare și depanare

O singură linie invalidă anulează întregul lot: validați fișierul înainte de a-l încărca. Un script simplu acoperă esențialul:

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")

Puncte cheie

  • Formatul JSONL conține un obiect JSON pe linie: custom_id, method, url, body
  • Încărcați fișierul prin /v1/files, apoi îl specificați la crearea lotului (input_file_id)
  • Maxim 50.000 de cereri și 200 MB per fișier; dincolo de aceste limite, creați câte un lot per fișier
  • Un lot creat dintr-un fișier este sigilat, iar o singură linie invalidă îl anulează în totalitate
  • Validați fișierul înainte de încărcare