Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Jälgimine, olek ja tühistamine

Õppetund 11 / 12 Värskendatud 2. november 2026 Arendajatele
Sellel lehel
  1. Paketi elutsükli haldamine
  2. Kaks oleku taset
  3. Loendurite kontrollimine
  4. Oma pakettide loetlemine
  5. Tulemuste hankimine
  6. Päringu metaandmete kontrollimine
  7. Paketi tühistamine
  8. Küsitlusstrateegia
  9. Peamised punktid

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 olekTähendusTegevus
pendingJärjekorrasOota
succeededTöödeldud, tulemus saadavalHaara tulemus
failedViga töötlemiselLoe sõnumit, proovi uuesti, kui on mõtet
cancelledTühistatud, näiteks koos paketigaEsita 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, /results tulemused, /requests päringu üksikasjad
  • Tühistamine (POST /v1/batches/{id}:cancel) on pöördumatu, kuid säilitab juba loodud tulemused
  • Loendid ja tulemused leheküljeldatakse limit ja pagination_token abil
  • Küsitle mõneminutiliste intervallidega, määrates maksimaalse viiteaja, ja haara andmed enne expire_time