Jälgimine, olek ja tühistamine
Sellel lehel
Uuendatud 2. novembril 2026 xAI dokumentatsiooni põhjal: soodustus pakettidele on 20% sobivate teksti mudelite puhul (mitte 50%), näited järgivad REST API-t ja ametlikku
xai-sdk-d (client.batch.*; xAI paketi API ei ühti OpenAI vorminguga, seega OpenAI SDK ei kehti) ning Responses API-l on vestluse lõpetamise (Chat Completions) ees ülimuslikkus, mis on xAI puhul iganenud lõpp-punkt. Allikad: Batch API · REST Reference · Batch Pricing.
Paketi elutsükli haldamine
Kui oled oma päringud esitanud, pead jälgima töötlemise edenemist, lugema olekuid ning teadma, millal ja kuidas paketti tühistada. See tund käsitleb kõiki saadaolevaid haldustoiminguid.
Kaks oleku taset
xAI jälgib edenemist kahel tasandil. Paketil endal puudub globaalne olek nagu „valmis“ või „ebaõnnestunud“: see sisaldab loendureid oma state objektis. Igal päringul on aga oma olek:
| Päringu olek | Tähendus | Tegevus |
|---|---|---|
pending | Järjekorras | Oota |
succeeded | Töödeldud, tulemus saadaval | Haara tulemus |
failed | Viga töötlemisel | Loe sõnumit, proovi uuesti, kui on mõtet |
cancelled | Tühistatud, näiteks koos paketiga | Esita vajadusel uuesti |
Pakett on täielikult töödeldud, kui selle num_pending loendur langeb nullini. Selle saab ka tühistada või see aegub: pärast expire_time ei ole selle tulemused enam kättesaadavad.
Loendurite kontrollimine
GET /v1/batches/{batch_id} päring tagastab paketi ja selle loendurid:
curl "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY"
Vastus sisaldab:
{
"batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
"name": "analyse_avis_clients",
"state": {
"num_requests": 500,
"num_pending": 155,
"num_success": 342,
"num_error": 3,
"num_cancelled": 0
}
}
Need loendurid jälgivad edenemist reaalajas, ootamata töötlemise lõppu. SDK-d kasutades loed neid avaldisest client.batch.get(batch_id=...).state.
Oma pakettide loetlemine
Paketi leidmiseks või ajaloo kontrollimiseks:
curl "https://api.x.ai/v1/batches?limit=20" \
-H "Authorization: Bearer $XAI_API_KEY"
Loend on lehekülgedeks jagatud parameetrite limit ja pagination_token abil. Paketid püsivad seal kuni aegumiseni. SDK-d kasutades tagastab client.batch.list(limit=20) batches loendi, kus iga element kannab oma name, batch_id ja state. xAI konsool pakub sama vaadet visuaalsel kujul.
Tulemuste hankimine
Saad tulemusi hankida igal ajal, isegi töötlemise käigus:
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Iga tulemus kannab oma päringu batch_request_id. Ebaõnnestunud päringud ilmuvad sinna koos oma sõnumiga; SDK-d kasutades eraldavad need iga lehe succeeded ja failed omadused.
Päringu metaandmete kontrollimine
Iga päringu oleku jälgimiseks:
curl "https://api.x.ai/v1/batches/$BATCH_ID/requests?limit=50" \
-H "Authorization: Bearer $XAI_API_KEY"
Iga kirje annab päringu identifikaatori, selle lõpp-punkti, mudeli, oleku ning loomise ja lõpetamise kuupäevad. See on diagnostikavahend, kui loendur peatub, või selleks, et kontrollida, mis edukalt lisati.
Paketi tühistamine
Kui pead käimasoleva töötlemise peatama:
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID:cancel" \
-H "Authorization: Bearer $XAI_API_KEY"
Tühistamine on lõplik: ootel päringuid ei töödelda ja sa ei saa enam paketti uusi päringuid lisada. Juba töödeldud päringud jäävad siiski tulemustes kättesaadavaks. Tühista, kui:
- Avastasid oma päringutes vea pärast esitamist
- Pakett pole enam vajalik (prioriteedi muutus)
- Soovid esitada parandatud paketi uuesti
SDK-d kasutades: client.batch.cancel(batch_id=...), mis tagastab paketi ja selle loendurid tühistamise hetkel.
Küsitlusstrateegia
Tootmiskeskkonnas oota lõpetamist harvenevate küsitluste ja maksimaalse viiteajaga:
import time
def attendre_batch(client, batch_id, intervalle=300, delai_max=2 * 86400):
"""Wait until all requests in the batch are processed."""
debut = time.monotonic()
while time.monotonic() - debut < delai_max:
batch = client.batch.get(batch_id=batch_id)
etat = batch.state
if batch.cancel_by_xai_message:
raise RuntimeError(f"Canceled by xAI: {batch.cancel_by_xai_message}")
if etat.num_requests > 0 and etat.num_pending == 0:
return batch
print(f"{etat.num_success} succeeded, {etat.num_error} failed, "
f"{etat.num_pending} pending out of {etat.num_requests}")
time.sleep(intervalle)
raise TimeoutError(f"Batch not finished after {delai_max} s")
Mõneminutiline intervall sobib suurtele pakettidele; xAI dokumentatsioon küsitleb oma näidetes iga paari sekundi tagant, mis hõlmab väikeseid pakette. Kuna tulemused on saadaval nende laekumisel, ei takista miski neid oote ajal hankimast.
Peamised punktid
- Loe paketti selle loendurite põhjal (
num_pending,num_success,num_error…); igal päringul on oma olek:pending,succeeded,failed,cancelled GET /v1/batches/{id}annab edenemise,/resultstulemused,/requestspäringu üksikasjad- Tühistamine (
POST /v1/batches/{id}:cancel) on pöördumatu, kuid säilitab juba loodud tulemused - Loendid ja tulemused leheküljeldatakse
limitjapagination_tokenabil - Küsitle mõneminutiliste intervallidega, määrates maksimaalse viiteaja, ja haara andmed enne
expire_time