Pridėti užklausas JSON formatu
Šiame puslapyje
Atnaujinta 2026 m. lapkričio 2 d. pagal xAI dokumentaciją: nuolaida didelės apimties užklausoms (batch) yra 20 % tinkamiems teksto modeliams (ne 50 %), pavyzdžiai atitinka REST API ir oficialųjį
xai-sdk(client.batch.*; xAI Batch API nenaudoja OpenAI formato, todėl OpenAI SDK netinka), o Responses API turi viršenybę prieš Chat Completions, kuris xAI sistemoje yra pasenusi sąsaja. Šaltiniai: Batch API · REST nuoroda · Batch kainodara.
Pridėjimas per API
Sukūrus didelės apimties užklausą (batch), pridėti prašymus į ją galima naudojant POST /v1/batches/{batch_id}/requests. Kiekvienas kvietimas siunčia sąrašą užklausų, o galutinį tašką gali kviesti tiek kartų, kiek reikia, kol batch nėra atšauktas. Šis būdas tinka batchams, kuriuos kuriate palaipsniui.
Užklausos struktūra
Kvietimo kūne yra batch_requests masyvas. Kiekvienas elementas susieja identifikatorių (batch_request_id) su pačia užklausa, saugoma pagal jos tipo raktą – responses skirta Responses API:
{
"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: Jūsų identifikatorius, unikalus batcho ribose. Tai raktas, sujungiantis užklausą su jos rezultatu; jei jo nėra, xAI sugeneruoja UUID.batch_request: Užklausa, įdėta pagal jos tipo raktą; API nuorodoje taip pat dokumentuojamaschat_get_completionChat Completions formatui.
Vaizdams ir vaizdo įrašams naudokite SDK (9 pamoka) arba JSONL failą (kitoje pamokoje).
cURL užklausa
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."}
]
}
}
}
]
}'
Pridėjimas naudojant Python SDK
Naudojant SDK, kiekviena užklausa konstruojama kaip standartinis pokalbis, jai priskiriamas batch_request_id, o tada jos pridėjamos grupėmis:
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)
# Pridėti grupėmis po 100: vienas API kvietimas kiekvienai grupei
for i in range(0, len(requests), 100):
client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])
Dokumentacijoje nenurodytas maksimalus užklausų skaičius vienam kvietimui; saikingo dydžio grupės tiesiog apriboja duomenų kiekį, kurį tektų siųsti iš naujo įvykus tinklo sutrikimui.
Pridėjimo greičio apribojimai
Komanda gali atlikti iki 1 000 pridėjimo kvietimų kas 30 sekundžių; ši riba taikoma slankiajam langui, bendram visiems jos batchams. Ribojimas galioja kvietimams, o ne užklausoms: naudojant 100 užklausų grupes, tai jau leidžia apdoroti daugiau nei 3 000 užklausų per sekundę. Svarbesnės yra dvi kitos ribos:
- 25 MB maksimalus dydis vienai individualiai užklausai (tai daugiausia liečia base64 koduotus vaizdus);
- Viršijus 100 000 užklausų batche, xAI gali sulėtinti apdorojimą, kad išlaikytų tarnybos stabilumą.
Kada naudoti pridėjimą per API
Pridėjimas per API tinka, kai lankstumas svarbesnis už išankstinį paruošimą. Tai natūralus pasirinkimas, kai batchas kuriamas palaipsniui: iš eilės gaunamos užklausos pridėjamos joms atvykstant, tuo tarpu JSONL failas reikalautų iš anksto žinoti viską ir uždarytų batchą. Tai taip pat tinkamas kelias prototipų kūrimui – norint išbandyti visą darbo eigą su penkiomis užklausomis prieš didinant mastelį – ir heterogeniniams batchams kurti.
Užklausų validavimas
Tikrinkite kiekvieno pridėjimo kvietimo būsenos kodą: klaida šiame etape reiškia, kad grupė nebuvo išsaugota, ir ją reikia siųsti iš naujo. Užklausa gali nepavykti ir vėliau, apdorojimo metu; tuomet rezultatuose ji atsiras su savo klaidos pranešimu. Modelis, kuris nepriima batcho, bus atmestas su pranešimu not supported for batch processing: prieš paleisdami didelį batchą, modelio puslapyje patikrinkite jo tinkamumą.
Svarbiausi punktai
- Pridėjimas vykdomas per
POST /v1/batches/{id}/requests, naudojantbatch_requestssąrašą; - Kiekviena užklausa turi unikalų
batch_request_idir savo turinį pagal tipo raktą (responses,chat_get_completion); - SDK sukuria užklausas naudodamas
client.chat.create(..., batch_request_id=...)ir prideda jas suclient.batch.add; - Komandos riba – 1 000 pridėjimo kvietimų per 30 sekundžių, kiekvienas kvietimas gali turėti daug užklausų;
- Skirtingai nei JSONL failo atveju, pridėjimas per API palieka batchą atvirą naujiems papildymams.