Seuranta, tila ja peruutus
Tällä sivulla
Päivitetty 2. marraskuuta 2026 xAI:n dokumentaation perusteella: alennus eräajosta on 20 % kelvollisissa tekstimalleissa (ei 50 %), esimerkit noudattavat REST API:a ja virallista
xai-sdk:ta (client.batch.*; xAI:n erä-API ei vastaa OpenAI:n muotoa, joten OpenAI SDK ei sovellu), ja Responses API on ensisijainen Chat Completionsiin nähden, joka on xAI:lla vanhentunut päätepiste. Lähteet: Batch API · REST Reference · Batch Pricing.
Erän elinkaaren hallinta
Kun olet lähettänyt pyyntösi, sinun on seurattava käsittelyn edistymistä, luettava tiloja ja tiedettävä, milloin ja miten erä voidaan peruuttaa. Tämä oppitunti kattaa kaikki käytettävissä olevat hallintatoiminnot.
Kaksi tasoa tiloja
xAI seuraa edistymistä kahdella tasolla. Erällä itsellään ei ole yleistä tilaa kuten “valmis” tai “epäonnistunut”: se sisältää laskureita state-objektissaan. Jokaisella pyynnöllä on kuitenkin oma tilansa:
| Pyynnön tila | Merkitys | Toimenpide |
|---|---|---|
pending | Jonossa | Odota |
succeeded | Käsitelty, tulos saatavilla | Nouda tulos |
failed | Virhe käsittelyn aikana | Lue viesti, yritä uudelleen jos hyödyllistä |
cancelled | Peruutettu, esimerkiksi eränsä mukana | Lähetä uudelleen tarvittaessa |
Erä on täysin käsitelty, kun sen num_pending-laskuri laskee nollaan. Se voidaan myös peruuttaa tai se voi vanhentua: expire_time-ajan jälkeen sen tulokset eivät ole enää saatavilla.
Tarkista laskurit
GET /v1/batches/{batch_id}-kutsu palauttaa erän ja sen laskurit:
curl "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY"
Vastaus sisältää:
{
"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
}
}
Nämä laskurit seuraavat edistymistä reaaliajassa odottamatta käsittelyn valmistumista. SDK:ta käyttäessäsi luet ne kohdasta client.batch.get(batch_id=...).state.
Listaa eräsi
Löytääksesi erän tai tarkistaaksesi historian:
curl "https://api.x.ai/v1/batches?limit=20" \
-H "Authorization: Bearer $XAI_API_KEY"
Lista on sivutettu limit- ja pagination_token-parametrien avulla. Erät pysyvät listalla vanhenemiseensa saakka. SDK:ta käyttäen client.batch.list(limit=20) palauttaa batches-listan, jossa jokainen alkio sisältää sen name, batch_id ja state. xAI-konsoli tarjoaa saman näkymän visuaalisessa muodossa.
Nouda tulokset
Voit noutaa tulokset milloin tahansa, jopa käsittelyn aikana:
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Jokainen tulos sisältää pyyntönsä batch_request_id:n. Epäonnistuneet pyynnöt näkyvät tässä viesteineen; SDK:ta käytettäessä jokaisen sivun succeeded- ja failed-ominaisuudet erottavat ne toisistaan.
Tarkista pyynnön metadata
Seurataksesi kunkin pyynnön tilaa:
curl "https://api.x.ai/v1/batches/$BATCH_ID/requests?limit=50" \
-H "Authorization: Bearer $XAI_API_KEY"
Jokainen merkintä antaa pyynnön tunnisteen, sen päätepisteen, mallin, tilan sekä luonti- ja päättymispäivät. Tämä on diagnostiikkatyökalu, kun laskuri jumittuu, tai varmistettaessa, mitä on onnistuneesti lisätty.
Peruuta erä
Jos sinun on pysäytettävä käynnissä oleva käsittely:
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID:cancel" \
-H "Authorization: Bearer $XAI_API_KEY"
Peruutus on lopullinen: odottavia pyyntöjä ei käsitellä, etkä voi enää lisätä pyyntöjä erään. Jo käsitellyt pyynnöt ovat kuitenkin edelleen saatavilla tuloksissa. Peruuta, jos:
- Huomasit virheen pyynnöissäsi lähetyksen jälkeen
- Erää ei enää tarvita (prioriteettimuutos)
- Haluat lähettää korjatun erän uudelleen
SDK:ta käyttäen: client.batch.cancel(batch_id=...), joka palauttaa erän ja sen laskurit peruutushetkellä.
Kyselystrategia (Polling)
Tuotantoympäristössä odota valmistumista harvennetulla kyselyllä ja enimmäisviiveellä:
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")
Muutaman minuutin väli sopii suurille erille; xAI:n dokumentaatio käyttää esimerkeissään muutaman sekunnin kyselyväliä, mikä kattaa pienet erät. Koska tulokset ovat saatavilla sitä mukaa kuin ne valmistuvat, mikään ei estä niiden noutamista odotuksen aikana.
Keskeiset asiat
- Lue erä sen laskureiden perusteella (
num_pending,num_success,num_error…); jokaisella pyynnöllä on oma tilansa:pending,succeeded,failed,cancelled GET /v1/batches/{id}antaa edistymisen,/resultstulokset ja/requestspyynnön yksityiskohdat- Peruutus (
POST /v1/batches/{id}:cancel) on peruuttamaton, mutta säilyttää jo tuotetut tulokset - Listat ja tulokset sivutetaan
limit- japagination_token-parametreilla - Tee kyselyjä muutaman minuutin välein asettaen enimmäisviive, ja nouda tulokset ennen
expire_time-ajankohtaa