Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Seuranta, tila ja peruutus

Oppitunti 11 / 12 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Erän elinkaaren hallinta
  2. Kaksi tasoa tiloja
  3. Tarkista laskurit
  4. Listaa eräsi
  5. Nouda tulokset
  6. Tarkista pyynnön metadata
  7. Peruuta erä
  8. Kyselystrategia (Polling)
  9. Keskeiset asiat

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 tilaMerkitysToimenpide
pendingJonossaOdota
succeededKäsitelty, tulos saatavillaNouda tulos
failedVirhe käsittelyn aikanaLue viesti, yritä uudelleen jos hyödyllistä
cancelledPeruutettu, esimerkiksi eränsä mukanaLä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, /results tulokset ja /requests pyynnön yksityiskohdat
  • Peruutus (POST /v1/batches/{id}:cancel) on peruuttamaton, mutta säilyttää jo tuotetut tulokset
  • Listat ja tulokset sivutetaan limit- ja pagination_token-parametreilla
  • Tee kyselyjä muutaman minuutin välein asettaen enimmäisviive, ja nouda tulokset ennen expire_time-ajankohtaa