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

Nelivaiheinen työkulku

Oppitunti 2 / 12 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Eräajon elinkaari
  2. Vaihe 1: Eräajon luominen
  3. Vaihe 2: Pyyntöjen lisääminen
  4. Vaihe 3: Edistymisen seuranta
  5. Vaihe 4: Tulosten hakeminen
  6. Työkulku käytännössä
  7. Virheenkäsittely työkulussa
  8. Keskeiset asiat

Päivitetty 2. marraskuuta 2026 xAI:n dokumentaation perusteella: alennus eräajosta on 20 % kelvollisissa tekstimalleissa (ei 50 %); esimerkit käyttävät REST API:a ja virallista xai-sdk:ta (client.batch.*; xAI:n Batch API ei noudata 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-viite · Eräajojen hinnoittelu.

Eräajon elinkaari

Jokainen eräajo noudattaa samaa sykliä: luominen, pyyntöjen lisääminen, käsittely ja tulosten hakeminen. Tämän syklin ymmärtäminen on välttämätöntä ennen toteutukseen siirtymistä, sillä jokaisella vaiheella on omat rajoituksensa ja parhaat käytäntönsä.

Vaihe 1: Eräajon luominen

Kaikki alkaa POST /v1/batches -kutsulla, jossa on yksi pakollinen kenttä: eräajon nimi. API palauttaa yksilöllisen tunnisteen (batch_id), jota käytät kaikissa myöhemmissä toiminnoissa.

curl -X POST https://api.x.ai/v1/batches \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "customer_review_analysis"}'

Vastaus sisältää myös eräajon luomis- ja vanhenemisajankohdat (create_time, expire_time) sekä state-objektin, jonka laskurit ovat kaikki vielä nollalla.

Vaihe 2: Pyyntöjen lisääminen

Käytössä on kaksi menetelmää:

API:n kautta: lähetät pyynnöt osoitteeseen POST /v1/batches/{batch_id}/requests. Jokainen kutsu sisältää listan pyyntöjä, ja voit jatkaa niiden lisäämistä niin kauan kuin eräajoa ei ole peruutettu. Tämä on reitti eräajoille, jotka rakennetaan vähitellen.

JSONL-tiedoston kautta: valmistelet tiedoston, joka sisältää kaikki pyyntösi, lataat sen Files API:n kautta ja luot eräajon tämän tiedoston pohjalta. Tämän jälkeen eräajo suljetaan: lisäykset eivät ole enää mahdollisia. Tämä on reitti etukäteen valmistelluille suurille volyymeille.

Jokainen pyyntö sisältää yksilöllisen tunnisteen eräajon sisällä: batch_request_id API:ssa tai custom_id JSONL-tiedostossa. Jos jätät sen pois API-kutsussa, xAI generoi UUID:n; anna sen sijaan oma tunnisteesi (esimerkiksi tietokannan ID). Se toimii sovitusavaimena datasi ja tulosten välillä sekä takaa, että pyyntö käsitellään vain kerran.

Vaihe 3: Edistymisen seuranta

Käsittely alkaa heti, kun pyyntöjä saapuu; erillistä “käynnistä”-vaihetta ei ole. Sillä välin GET /v1/batches/{batch_id} palauttaa state-objektin ja sen laskurit: num_requests (yhteensä), num_pending (odottaa), num_success (onnistuneet), num_error (epäonnistuneet) ja num_cancelled (peruutetut).

curl https://api.x.ai/v1/batches/$BATCH_ID \
  -H "Authorization: Bearer $XAI_API_KEY"

Kun num_pending laskee nollaan, kaikki pyynnöt on käsitelty, onnistuivatpa ne tai eivät. Säännöllinen kysely (polling) riittää: muutama sekunti pienelle testierälle, muutama minuutti suurelle erälle.

Vaihe 4: Tulosten hakeminen

Tulokset luetaan komennolla GET /v1/batches/{batch_id}/results odottamatta eräajon valmistumista: jokainen pyyntö on saatavilla heti, kun se on käsitelty. Vastaus on sivutettu: limit määrittää sivun koon (enintään 1 000), ja palautettua pagination_token-arvoa käytetään seuraavan sivun pyytämiseen; se on tyhjä viimeisellä sivulla.

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: tämän avulla voit rekonstruoida syöttödatasi ja Grokin vastausten välisen mappingin.

Työkulku käytännössä

Tuotantoputkistossa työkulku toteutetaan yleensä kahtena erillisenä prosessina:

  • Lähetysprosessi, joka luo eräajon, valmistelee ja lisää pyynnöt sekä tallentaa batch_id:n
  • Hakuprosessi, joka tarkistaa säännöllisesti laskurit ja lataa tulokset sitä mukaa, kun niitä valmistuu

Tämä erottelu mahdollistaa Batch API:n integroinnin tapahtumapohjaisiin arkkitehtuureihin tai olemassa oleviin dataputkistoihin (cron-tehtävät, Apache Airflow, jonot).

Virheenkäsittely työkulussa

Eräajolla ei ole yleistä “onnistui” tai “epäonnistui” -tilaa: luet sen laskureiden kautta. Epäonnistunut pyyntö kasvattaa num_error-laskuria ja näkyy tuloksissa virheilmoituksineen estämättä muita pyyntöjä. Sinun on siis tarkasteltava jokaista tulosta ja käsiteltävä epäonnistumiset tapauskohtaisesti.

Kaksi tapahtumaa vaikuttaa koko eräajoon. Ensimmäinen on peruutus, jonka teet sinä tai xAI, joka selittää tämän kentässä cancel_by_xai_message. Tämä tapahtuu erityisesti, jos JSONL-tiedoston rivi on virheellinen. Toinen on vanheneminen (expire_time), jonka jälkeen tulokset eivät ole enää saatavilla: hae ne viipymättä.

Keskeiset asiat

  • Työkulku etenee järjestyksessä: luo (nimellä), lisää, seuraa, hae
  • Pyynnön tunniste (batch_request_id tai custom_id JSONL:ssä) on sovitusavaimesi
  • Edistyminen luetaan state-laskureista; kaikki on käsitelty, kun num_pending on nolla
  • Tulokset on sivutettu (limit, pagination_token) ja ne ovat saatavilla käsittelyn edetessä
  • Virheet käsitellään pyyntökohtaisesti; peruutus ja vanheneminen vaikuttavat koko eräajoon