Nelivaiheinen työkulku
Tällä sivulla
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_idtaicustom_idJSONL:ssä) on sovitusavaimesi - Edistyminen luetaan
state-laskureista; kaikki on käsitelty, kunnum_pendingon 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