Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Formáid JSONL agus uaslódáil tríd an API Comhad

Ceacht 6 as 12 Nuashonraithe 2 Samhain 2026 Forbróir
Ar an leathanach seo
  1. Próiseáil mhórchóir le JSONL
  2. Struchtúr comhaid JSONL
  3. Comhad JSONL a ghiniúint i bPython
  4. Uaslódáil tríd an API Comhad
  5. An bhaisc a chruthú ón gcomhad
  6. Teorainneacha formáide JSONL
  7. Comhad JSONL a ghiniúint i JavaScript
  8. Bailíochtú agus dífhabhtú
  9. Príomhphointí

Nuashonraithe an 2 Samhain, 2026 bunaithe ar dhoiciméadú xAI: tá lascaine 20% ar mhúnlaí téacs incháilithe (ní 50%), leanann na samplaí an REST API agus an xai-sdk oifigiúil (client.batch.*; ní úsáideann API Baisc xAI formáid OpenAI, mar sin ní bhaineann an SDK OpenAI leis), agus tá tosaíocht ag an API Freagraí thar Chríochnú Comhrá, pointe deiridh oidhreachta ag xAI. Foinse: API Baisc · Tagairt REST · Praghsáil Baisc.

Próiseáil mhórchóir le JSONL

Do mhéideanna móra ullmhaithe roimh ré, is é comhad JSONL an bealach is simplí. Scríobhann tú do chuid iarratas go léir isteach i gcomhad, uaslódálann tú é tríd an API Comhad, agus ansin cruthaíonn tú an bhaisc ón gcomhad sin. Is féidir le comhad amháin suas le 50,000 iarratas a choinneáil.

Struchtúr comhaid JSONL

Cuimsíonn comhad JSONL (JSON Lines) oibiacht JSON amháin in aghaidh na líne. Léiríonn gach líne iarratas iomlán le ceithre réimse:

{"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: aitheantóir uathúil laistigh den chomhad; éiríonn sé ina batch_request_id sna torthaí
  • method: i gcónaí "POST"
  • url: an pointe deiridh sprioc, ceann amháin de na seacht gcinn a nglactar leo
  • body: corp an iarratais, ag teacht leis an tagairt API don phointe deiridh sin

Caithfidh gach líne a bheith ina JSON bailí, féin-leordhóthanach: gan camóg scartha, gan lúibín faoi iamh. Is féidir pointí deiridh a mheascadh sa chomhad céanna; seoltar gach iarratas go neamhspleách.

Comhad JSONL a ghiniúint i bPython

import json

documents = [
    {"id": "doc-001", "text": "First article to summarize..."},
    {"id": "doc-002", "text": "Second article to summarize..."},
    # ... suas le 50,000 doiciméad in aghaidh an chomhaid
]

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

Uaslódáil tríd an API Comhad

Uaslódálann tú an comhad tríd an bpointe deiridh /v1/files, gan aon pharaiméadair eile:

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

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

An bhaisc a chruthú ón gcomhad

Ní chuirtear an comhad le baisc atá ann cheana: sonraíonn tú é ag am an chruthaithe le 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}")

Léitear an comhad sa chúlra ansin. Má tá líne amháin míbhailí fiú, cealaítear an bhaisc le teachtaireacht earráide. Oibríonn rianú agus faighteas na dtorthaí díreach mar a dhéanann siad do bhaisc a chuirtear isteach tríd an API.

Teorainneacha formáide JSONL

  • Uasmhéid 50,000 iarratas in aghaidh an chomhaid
  • Uasmhéid 200 MB in aghaidh an chomhaid
  • custom_id uathúil in aghaidh na líne
  • Tá baisc a chruthaítear ó chomhad séalaite: ní féidir leat aon rud a chur leis ina dhiaidh sin tríd an API

Má sháraíonn do bhaisc na teorainneacha seo, roinn ina chomhaid iolracha é agus cruthaigh baisc amháin in aghaidh gach comhaid. Níl aon teorainn ar líon na mbaisc in aghaidh na foirne.

Comhad JSONL a ghiniúint i 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");

Bailíochtú agus dífhabhtú

Cealaíonn líne amháin neamhbhailí an bhaisc iomlán: bailíochtaigh an comhad sula n-uaslódálann tú é. Clúdaíonn script shimplí na bunriachtanais:

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

Príomhphointí

  • Cuimsíonn an fhormáid JSONL oibiacht JSON amháin in aghaidh na líne: custom_id, method, url, body
  • Uaslódálann tú an comhad tríd /v1/files, agus ansin sonraíonn tú é agus tú ag cruthú na baisce (input_file_id)
  • Uasmhéid 50,000 iarratas agus 200 MB in aghaidh an chomhaid; thairis sin, baisc amháin in aghaidh gach comhaid
  • Tá baisc a chruthaítear ó chomhad séalaite, agus cealaíonn líne amháin neamhbhailí í go hiomlán
  • Bailíochtaigh an comhad sula n-uaslódálann tú é