Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

JSONL formāts un augšupielāde, izmantojot Files API

Nodarbība 6 no 12 Atjaunota 2026. gada 2. novembris Programmētājs
Šajā lapā
  1. Masveida apstrāde ar JSONL
  2. JSONL faila struktūra
  3. JSONL faila ģenerēšana Python valodā
  4. Augšupielāde, izmantojot Files API
  5. Partijas izveide no faila
  6. JSONL formāta ierobežojumi
  7. JSONL faila ģenerēšana JavaScript valodā
  8. Validācija un atkļūdošana
  9. Galvenās atziņas

Atjaunināts 2026. gada 2. novembrī, pamatojoties uz xAI dokumentāciju: atlaide par partijas apstrādi ir 20% atbilstošajiem teksta modeļiem (nevis 50%), piemēri atbilst REST API un oficiālajam xai-sdk (client.batch.*; xAI partijas API neizmanto OpenAI formātu, tāpēc OpenAI SDK nav piemērojams), un Responses API ir prioritārs pār Chat Completions, kas xAI vidē ir novecojis galapunkts. Avoti: Batch API · REST atsauce · Partijas cenu politika.

Masveida apstrāde ar JSONL

Lieliem iepriekš sagatavotiem datu apjomiem JSONL fails ir vienkāršākais risinājums. Tu ieraksti visus savus pieprasījumus failā, augšupielādē to, izmantojot Files API, un pēc tam izveido partiju no šī faila. Vienā failā var būt līdz 50 000 pieprasījumu.

JSONL faila struktūra

JSONL (JSON Lines) fails satur vienu JSON objektu katrā rindā. Katra rinda reprezentē pilnīgu pieprasījumu ar četriem laukiem:

{"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: unikāls identifikators faila ietvaros; rezultātos tas kļūst par batch_request_id
  • method: vienmēr "POST"
  • url: mērķa galapunkts, viens no septiņiem pieņemtajiem
  • body: pieprasījuma ķermenis, kas atbilst šī galapunkta API atsaucei

Katrai rindai jābūt derīgam, pašpietiekamam JSON: bez atdalošām komatām, bez ietverošām iekavām. Galapunktus vienā failā var jaukt; katrs pieprasījums tiek maršrutēts neatkarīgi.

JSONL faila ģenerēšana Python valodā

import json

documents = [
    {"id": "doc-001", "text": "First article to summarize..."},
    {"id": "doc-002", "text": "Second article to summarize..."},
    # ... līdz 50 000 dokumentu vienā failā
]

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

Augšupielāde, izmantojot Files API

Tu augšupielādē failu, izmantojot /v1/files galapunktu, bez citiem parametriem:

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

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

Partijas izveide no faila

Fails netiek pievienots esošai partijai: tu to norādi izveides brīdī, izmantojot 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}")

Pēc tam fails tiek nolasīts fona režīmā. Ja pat viena rinda ir nederīga, partija tiek atcelta ar kļūdas ziņojumu. Rezultātu izsekošana un iegūšana pēc tam darbojas tieši tāpat kā partijai, kas iesniegta caur API.

JSONL formāta ierobežojumi

  • Maksimums 50 000 pieprasījumu vienā failā
  • Maksimums 200 MB vienā failā
  • Unikāls custom_id katrā rindā
  • No faila izveidota partija ir noslēgta: tai vēlāk nevari neko pievienot caur API

Ja tava partija pārsniedz šos ierobežojumus, sadali to vairākos failos un izveido vienu partiju katram failam. Nav ierobežojumu partiju skaitam vienā komandā.

JSONL faila ģenerēšana JavaScript valodā

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

Validācija un atkļūdošana

Viena nederīga rinda atceļ visu partiju: validē failu pirms augšupielādes. Vienkāršs skripts aptver būtiskāko:

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

Galvenās atziņas

  • JSONL formāts satur vienu JSON objektu katrā rindā: custom_id, method, url, body
  • Tu augšupielādē failu caur /v1/files un pēc tam norādi to, izveidojot partiju (input_file_id)
  • Maksimums 50 000 pieprasījumu un 200 MB vienā failā; pārsniedzot šos limitus, veido vienu partiju katram failam
  • No faila izveidota partija ir noslēgta, un viena nederīga rinda to atceļ pilnībā
  • Validē failu pirms augšupielādes