Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Il-format JSONL u t-tlugħ permezz tal-API tal-Fajls

Lezzjoni 6 / 12 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Ipproċessar bil-kwantità b’JSONL
  2. Struttura tal-fajl JSONL
  3. Iġġenera fajl JSONL f’Python
  4. Tlugħ permezz tal-API tal-Fajls
  5. Oħloq il-batch mill-fajl
  6. Limiti tal-format JSONL
  7. Iġġenera fajl JSONL f’JavaScript
  8. Validazzjoni u dijbukkar
  9. Punti Ewlenin

Aġġornat fit-2 ta’ Novembru, 2026 abbażi tad-dokumentazzjoni ta’ xAI: l-iskont għall-batches huwa ta’ 20% fuq mudelli tat-test eliġibbli (mhux 50%), l-eżempji jsegwu l-API REST u l-xai-sdk uffiċjali (client.batch.*; l-API tal-Batch ta’ xAI ma tużax il-format ta’ OpenAI, allura l-SDK ta’ OpenAI ma japplikax), u l-API tar-Risposti għandha preċedenza fuq Chat Completions, li huwa endpoint antikwat f’xAI. Sorsi: Batch API · Referenza REST · Prezzijiet tal-Batch.

Ipproċessar bil-kwantità b’JSONL

Għal volumi kbar imħejjija minn qabel, fajl JSONL huwa l-aktar rotta sempliċi. Tikteb it-talbiet kollha tiegħek f’fajl, ittella’ permezz tal-API tal-Fajls, imbagħad toħloq il-batch minn dak il-fajl. Fajl wieħed jista’ jżomm sa 50,000 talba.

Struttura tal-fajl JSONL

Fajl JSONL (JSON Lines) fih oġġett JSON wieħed kull linja. Kull linja tirrappreżenta talba sħiħa b’erba’ oqsma:

{"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: identifikatur uniku fil-fajl; isir il-batch_request_id fir-riżultati
  • method: dejjem "POST"
  • url: l-endpoint fil-mira, wieħed mis-segħa aċċettati
  • body: il-korp tat-talba, li jaqbel mar-referenza tal-API għal dak l-endpoint

Kull linja trid tkun JSON validu u awtosuffiċjenti: l-ebda virgola li tifred, l-ebda parentesi li tgħaqqad. L-endpoints jistgħu jitħalltu fl-istess fajl; kull talba tiġi rruttata indipendentement.

Iġġenera fajl JSONL f’Python

import json

documents = [
    {"id": "doc-001", "text": "First article to summarize..."},
    {"id": "doc-002", "text": "Second article to summarize..."},
    # ... sa 50,000 dokument kull fajl
]

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

Tlugħ permezz tal-API tal-Fajls

Ttella’ l-fajl permezz tal-endpoint /v1/files, mingħajr ebda parametru ieħor:

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

Bl-SDK ta’ 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}")

Oħloq il-batch mill-fajl

Il-fajl ma jiġix miżjud ma’ batch eżistenti: tispeċifikah fil-ħin tal-ħolqien b’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}")

Il-fajl imbagħad jinqara fl-isfond. Jekk sa linja waħda tkun invalida, il-batch jitħassar b’messaġġ ta’ żball. It-traċċar u l-irkupru tar-riżultati mbagħad jaħdmu eżattament bħal għal batch sottomess permezz tal-API.

Limiti tal-format JSONL

  • Massimu ta’ 50,000 talba kull fajl
  • Massimu ta’ 200 MB kull fajl
  • custom_id uniku kull linja
  • Batch maħluq minn fajl huwa issiġillat: ma tistax iżid miegħu aktar tard permezz tal-API

Jekk il-batch tiegħek taqbeż dawn il-limiti, aqsmu f’diversi fajls u oħloq batch wieħed kull fajl. M’hemm l-ebda limitu fuq in-numru ta’ batches kull tim.

Iġġenera fajl JSONL f’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");

Validazzjoni u dijbukkar

Linja waħda invalida tħassar il-batch kollu: ivvalida l-fajl qabel ma ttellgħu. Skript sempliċi jkopri l-essenzjali:

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

Punti Ewlenin

  • Il-format JSONL fih oġġett JSON wieħed kull linja: custom_id, method, url, body
  • Ittella’ l-fajl permezz ta’ /v1/files, imbagħad ispeċifikah meta toħloq il-batch (input_file_id)
  • Massimu ta’ 50,000 talba u 200 MB kull fajl; lil hinn minn hekk, batch wieħed kull fajl
  • Batch maħluq minn fajl huwa ssiġillat, u linja waħda invalida tħassru kompletament
  • Ivvalida l-fajl qabel ma ttellgħu