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

Luo tyhjä erä

Oppitunti 4 / 12 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Ensimmäinen vaihe: alustus
  2. Luontikutsu
  3. Python-toteutus
  4. JavaScript-toteutus
  5. Luontinopeusrajoitukset
  6. Parhaat käytännöt
  7. Keskeiset asiat

Päivitetty 2. marraskuuta 2026 xAI:n dokumentaation perusteella: eräalennus on 20 % tukikelpoisissa tekstimalleissa (ei 50 %), esimerkit käyttävät REST API:a ja virallista xai-sdk-kehityspakettia (client.batch.*; xAI:n Batch API ei käytä OpenAI:n muotoa, joten OpenAI SDK ei sovellu), ja Responses API on ensisijainen Chat Completionsin edellä, joka on xAI:lla vanhentunut päätepiste. Lähteet: Batch API · REST-viite · Erähinnoittelu.

Ensimmäinen vaihe: alustus

Erän luominen on työnkulun ensimmäinen konkreettinen toimi. POST /v1/batches -kutsu alustaa tyhjän säiliön, joka vastaanottaa myöhemmin pyyntösi. Tämä vaihe on tarkoituksellisen minimalistinen: se luo tunnisteen ja valmistelee erän palvelinpuolella.

1

POST /v1/batches

Luo nimetyn erän ja palauttaa sen batch_id:n.

2

Tallenna batch_id

Tallenna tunniste myöhempiä toimintoja varten.

3

Lisää pyynnöt

Erä on valmis vastaanottamaan pyyntöjä API:n kautta.

Luontikutsu

Pyyntörunko sisältää vain yhden pakollisen kentän, name:

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ää batch_id:n, luonti- ja vanhenemispäivämäärät sekä erälaskurit, jotka ovat edelleen nollalla (esimerkki API-viitteestä):

{
  "batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
  "name": "customer_review_analysis",
  "create_time": "2025-11-11",
  "expire_time": "2025-11-12",
  "create_api_key_id": "********-****-****-****-************",
  "cancel_time": null,
  "cancel_by_xai_message": null,
  "state": {
    "num_requests": 0,
    "num_pending": 0,
    "num_success": 0,
    "num_error": 0,
    "num_cancelled": 0
  }
}

Python-toteutus

Virallinen SDK asennetaan komennolla pip install xai-sdk (versio 1.21.0 2. marraskuuta 2026 mennessä; vaatii Python 3.10:n tai uudemman). Se lukee avaimen XAI_API_KEY-ympäristömuuttujasta:

from xai_sdk import Client

client = Client()

batch = client.batch.create(batch_name="customer_review_analysis")
batch_id = batch.batch_id
print(f"Batch created: {batch_id}")

Palautettu batch_id on eräsi yksilöllinen viite. Säilytä se muuttujassa, tiedostossa tai tietokannassa arkkitehtuuristasi riippuen.

JavaScript-toteutus

Ilman SDK:ta pelkkä fetch-kutsu REST API:hin riittää:

const response = await fetch("https://api.x.ai/v1/batches", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.XAI_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ name: "customer_review_analysis" })
});

const batch = await response.json();
console.log(`Batch created: ${batch.batch_id}`);

Luontinopeusrajoitukset

Erän luominen on rajoitettu 2 kertaan sekunnissa tiimiä kohden; itse erien määrää ei ole rajoitettu. Käytännössä et törmää tähän rajan harvoin: yleensä luot yhden erän toimintoa kohden ja lisäät siihen kaikki pyyntösi. Jos luot useita silmukassa, pidä kutsujen välillä vähintään 500 millisekunnin tauko.

Parhaat käytännöt

Nimeä erät huolellisesti: nimi on pakollinen, joten tee siitä hyödyllinen. Nimi, joka ilmoittaa tietoaineiston ja päivämäärän (customer_reviews_2026_11_02), on helppo löytää eräluettelosta ja xAI-konsolista, jonka avulla voit myös seurata eriä visuaalisesti.

Huomioi vanheneminen: expire_time kertoo, milloin erä ja sen tulokset lakkaavat olemasta saatavilla. Hakuprosessisi on suoritettava ennen tätä ajankohtaa.

Käsittele luontivirheet: tunnistusvirhe, nopeusrajoituksen ylitys tai verkkovika voi estää luonnin. Yritä ohimeneviä virheitä uudelleen kasvavalla viiveellä (eksponentiaalinen takaisin veto), mutta älä koskaan yritä uudelleen tunnistusvirheitä.

Keskeiset asiat

  • Erän luominen on POST /v1/batches, jonka ainoa pakollinen kenttä on name
  • Vastaus sisältää yksilöllisen batch_id:n, joka on säilytettävä koko työnkulun ajan
  • Pythonissa virallinen xai-sdk-kehityspaketti tarjoaa metodin client.batch.create(batch_name=...)
  • Raja on 2 luontia sekunnissa tiimiä kohden, eikä erien määrää ole rajoitettu
  • Seuraa expire_time-arvoa ja yritä uudelleen vain ohimeneviä virheitä