Päringute lisamine JSON-formaadis
Sellel lehel
Uuendatud 2. novembril 2026 xAI dokumentatsiooni põhjal: soodustus partii töötlemisel on 20% sobivate teksti mudelite puhul (mitte 50%), näited järgivad REST API-t ja ametlikku
xai-sdk(client.batch.*; xAI partii API ei kasuta OpenAI formaati, OpenAI SDK ei kehti) ning Responses API-l on ülimuslik positsioon võrreldes Chat Completionsiga, mis on xAI-s iganenud lõpp-punkt. Allikad: Batch API · REST Reference · Batch Pricing.
Lisamine API kaudu
Kui partii on loodud, lisad sellele päringuid kasutades POST /v1/batches/{batch_id}/requests. Iga väljakutse sisaldab päringute loendit ja saad seda lõpp-punkti kutsuda nii mitu korda kui vaja, seni kuni partii on tühistamata. See lähenemine sobib järk-järgult üles ehitatavate partiide jaoks.
Päringu struktuur
Päringu keha sisaldab massiivi batch_requests. Iga element seob identifikaatori (batch_request_id) konkreetse päringuga, mis salvestatakse selle tüübile vastava võtme alla – Responses API puhul on selleks 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: Sinu enda määratud identifikaator, mis peab olema partii sees unikaalne. See on võti, mis seob päringu selle tulemusega; kui see puudub, genereerib xAI UUID.batch_request: Päring ise, paigutatud selle tüübile vastava võtme alla; API referentsdokumentatsioon kirjeldab kachat_get_completionChat Completions formaadi jaoks.
Piltide ja videote puhul kasuta SDK-d (õppetund 9) või JSONL-faili (järgmine õppetund).
cURL päring
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."}
]
}
}
}
]
}'
Lisamine Python SDK-ga
SDK-d kasutades ehitad iga päringu nagu tavalise vestluse, määrad sellele batch_request_id ja lisad need seejärel tükkidena:
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)
# Lisa tükkidena (100 kaupa): üks API väljakutse tüki kohta
for i in range(0, len(requests), 100):
client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])
Dokumentatsioon ei sätesta maksimaalset päringute arvu ühe väljakutse kohta; mõõdukate tükkide kasutamine piirab lihtsalt andmete hulka, mida tuleb võrguprobleemide korral uuesti saata.
Lisamise kiiruse piirangud
Meeskond saab teha kuni 1000 lisamise väljakutset iga 30 sekundi järel, kasutades libisevat akent, mis kehtib kõigile tema partiidele ühiselt. Piirang kehtib väljakutsete, mitte päringute endi kohta: 100-päringuliste tükkide korral võimaldab see juba rohkem kui 3000 päringut sekundis. Olulisemad on kaks muud piiri:
- Maksimaalselt 25 MB ühe päringu kohta, mis puudutab peamiselt base64-kodeeringus pilte.
- Kui partis on üle 100 000 päringu, võib xAI töötlemist aeglustada, et säilitada teenuse stabiilsus.
Millal kasutada API kaudu lisamist
API kaudu lisamine on sobiv alati, kui paindlikkus on olulisem kui ettevalmistus alguses. See on loomulik valik, kui partii ehitatakse järk-järgult: järjekorrast saabuvad päringud lisatakse kohe saabumisel, samas kui JSONL-fail eeldaks kõigi andmete ette teadmist – ja sulgeks partii. See on ka õige tee prototüüpimiseks, et testida kogu töövoogu viie päringuga enne suuremahulist kasutuselevõttu, ning heterogeensete partiide jaoks.
Päringu valideerimine
Kontrolli iga lisamise väljakutse olekukoodi: viga selles etapis tähendab, et tükk ei salvestunud ja sa pead selle uuesti saatma. Päring võib ebaõnnestuda ka hiljem, töötlemise käigus; sel juhul ilmub see tulemustesse koos veateatega. Mudel, mis partii töötlemist ei toeta, lükatakse tagasi sõnumiga not supported for batch processing: kontrolli mudeli sobivust mudeli lehel enne suure partii käivitamist.
Peamised punktid
- Lisamine toimub läbi
POST /v1/batches/{id}/requests, kasutades loenditbatch_requests. - Iga päring sisaldab unikaalset
batch_request_idja selle sisu tüübile vastava võtme all (responses,chat_get_completion). - SDK ehitab päringud funktsiooniga
client.chat.create(..., batch_request_id=...)ja lisab need funktsioonigaclient.batch.add. - Piirang on meeskonnale 1000 lisamise väljakutset 30 sekundi jooksul; iga väljakutse võib sisaldada palju päringuid.
- Erinevalt JSONL-failist jätab API kaudu lisamise partii uute lisamiste jaoks avatuks.