Dodajanje zahtevkov v JSON
Na tej strani
Posodobljeno 2. novembra 2026 na podlagi dokumentacije xAI: popust za paketne obdelave znaša 20 % za ustrezne besedilne modele (ne 50 %), primeri sledijo REST API-ju in uradnemu paketu
xai-sdk(client.batch.*; paketni API xAI ne uporablja formata OpenAI, zato SDK OpenAI ne velja), API Responses pa ima prednost pred Chat Completions, ki je pri xAI zastarela končna točka. Viri: Batch API · REST Reference · Batch Pricing.
Dodajanje prek API-ja
Ko je paket ustvarjen, mu zahtevke dodaš z POST /v1/batches/{batch_id}/requests. Vsak klic prenese seznam zahtevkov, končno točko pa lahko kličeš poljubno pogosto, dokler paket ni preklican. Ta pristop deluje za pakete, ki jih gradiš postopoma.
Struktura zahtevka
Telo klica vsebuje polje batch_requests. Vsak element povezuje identifikator (batch_request_id) z samim zahtevkom, ki je shranjen pod ključem, ki ustreza njegovi vrsti – responses za API Responses:
{
"batch_requests": [
{
"batch_request_id": "avis-001",
"batch_request": {
"responses": {
"model": "grok-4.3",
"input": [
{"role": "system", "content": "Classify the sentiment: positive, negative, or neutral."},
{"role": "user", "content": "The product exceeded my expectations!"}
]
}
}
}
]
}
batch_request_id: Tvoj identifikator, edinstven znotraj paketa. To je ključ, ki povezuje zahtevek z njegovim rezultatom; če ga izpustiš, xAI samodejno ustvari UUID.batch_request: Zahtevek pod ključem, ki ustreza njegovi vrsti; referenca API-ja dokumentira tudichat_get_completionza format Chat Completions.
Za slike in videoposnetke uporabi SDK (lekcija 9) ali datoteko JSONL (naslednja lekcija).
Zahtevek cURL
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID/requests" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"batch_requests": [
{
"batch_request_id": "article-42",
"batch_request": {
"responses": {
"model": "grok-4.3",
"input": [
{"role": "user", "content": "Classify this text: positive, neutral, or negative."}
]
}
}
}
]
}'
Dodajanje s Python SDK-jem
S SDK-jem vsak zahtevek sestaviš kot običajen pogovor, mu dodeliš batch_request_id, nato pa jih dodaš v sklopih:
from xai_sdk import Client
from xai_sdk.chat import system, user
client = Client()
documents = [
{"id": "doc-1", "text": "First document to analyze..."},
{"id": "doc-2", "text": "Second document to analyze..."},
{"id": "doc-3", "text": "Third document to analyze..."},
]
batch_id = "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8"
requests = []
for doc in documents:
chat = client.chat.create(model="grok-4.3", batch_request_id=doc["id"])
chat.append(system("Summarize the document in two sentences."))
chat.append(user(doc["text"]))
requests.append(chat)
# Dodajanje v sklopih po 100: en klic API-ja na sklop
for i in range(0, len(requests), 100):
client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])
Dokumentacija ne določa največjega števila zahtevkov na klic; zmerni velikosti sklopov preprosto omejita količino podatkov, ki jih je treba ponovno poslati v primerom omrežne napake.
Omejitve hitrosti pri dodajanju
Ekipa lahko izvede do 1.000 klicev za dodajanje vsakih 30 sekund v drsečem oknu, ki je skupno za vse njene pakete. Omejitev velja za klice, ne za zahtevke: s sklopi po 100 zahtevkov to že omogoča več kot 3.000 zahtevkov na sekundo. Pomembnejši sta dve drugi meji:
- Največ 25 MB na posamezen zahtevek, kar zadeva predvsem slike, kodirane v base64.
- Pri več kot 100.000 zahtevkih v paketu lahko xAI upočasni obdelavo, da ohrani stabilnost storitve.
Kdaj uporabiti dodajanje prek API-ja
Dodajanje prek API-ja uporabiš, kadar je fleksibilnost pomembnejša od vnaprejšnje priprave. Postane naravna izbira, ko paket gradiš postopoma: zahtevki, ki prispevajo iz čakalne vrste, se dodajo sproti, medtem ko bi datoteka JSONL zahtevala poznavanje vseh podatkov vnaprej – in bi paket zaprla. To je tudi prava pot za prototipiranje, da preizkusiš celoten delovni tok s petimi zahtevki pred razširitvijo, ter za heterogene pakete.
Preverjanje veljavnosti zahtevkov
Preveri kodo stanja vsakega klica za dodajanje: napaka v tej fazi pomeni, da sklop ni bil shranjen in ga moraš ponovno poslati. Zahtevek lahko kasneje odpove tudi med obdelavo; takrat se pojavi v rezultatih s svojim sporočilom o napaki. Model, ki ne sprejema paketne obdelave, je zavrnjen s sporočilom not supported for batch processing: pred zagonom velikega paketa preveri ustreznost na strani modela.
Ključne ugotovitve
- Dodajanje poteka prek
POST /v1/batches/{id}/requestss seznamombatch_requests. - Vsak zahtevek vsebuje edinstven
batch_request_idin svojo vsebino pod ključem, ki ustreza njegovi vrsti (responses,chat_get_completion). - SDK gradi zahtevke z
client.chat.create(..., batch_request_id=...)in jih doda zclient.batch.add. - Omejitev za ekipo znaša 1.000 klicev za dodajanje na 30 sekund; vsak klic lahko prenese veliko zahtevkov.
- Za razliko od datoteke JSONL dodajanje prek API-ja pušča paket odprt za nove dodatke.