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

Lisää pyyntöjä JSON-muodossa

Oppitunti 5 / 12 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Lisääminen API:n kautta
  2. Pyynnön rakenne
  3. cURL-pyyntö
  4. Lisääminen Python SDK:lla
  5. Lisäämisen nopeusrajoitukset
  6. Milloin käyttää API-lisäystä
  7. Pyynnön validointi
  8. Keskeiset asiat

Päivitetty 2. marraskuuta 2026 xAI:n dokumentaation perusteella: eräalennus on 20 % kelvollisissa tekstimalleissa (ei 50 %), esimerkit noudattavat REST API:a ja virallista xai-sdk:tä (client.batch.*; xAI:n erä-API ei käytä OpenAI-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 Reference · Batch Pricing.

Lisääminen API:n kautta

Kun erä on luotu, lisäät siihen pyyntöjä osoitteeseen POST /v1/batches/{batch_id}/requests. Jokainen kutsu sisältää listan pyyntöjä, ja voit kutsua päätepistettä niin monta kertaa kuin tarvitaan, kunhan erää ei ole peruutettu. Tämä lähestymistapa toimii vähitellen rakennetuille erille.

Pyynnön rakenne

Kutsun runko sisältää batch_requests-taulukon. Jokainen alkio yhdistää tunnisteen (batch_request_id) itse pyyntöön, joka tallennetaan sen tyypin mukaiseen avaimeen – responses Responses API:ta varten:

{
  "batch_requests": [
    {
      "batch_request_id": "avis-001",
      "batch_request": {
        "responses": {
          "model": "grok-4.3",
          "input": [
            {"role": "system", "content": "Classify the sentiment: positive, negative, or neutral."},
            {"role": "user", "content": "The product exceeded my expectations!"}
          ]
        }
      }
    }
  ]
}
  • batch_request_id: Oma tunnisteesi, joka on yksilöllinen erän sisällä. Tämä on avain, joka yhdistää pyynnön sen tulokseen; jos se puuttuu, xAI luo UUID:n.
  • batch_request: Pyyntö sen tyypin mukaisessa avaimessa; API-viite dokumentoi myös chat_get_completion-avaimen Chat Completions -muotoa varten.

Käytä kuvia ja videoita varten SDK:ta (oppitunti 9) tai JSONL-tiedostoa (seuraava oppitunti).

cURL-pyyntö

curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID/requests" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_requests": [
      {
        "batch_request_id": "article-42",
        "batch_request": {
          "responses": {
            "model": "grok-4.3",
            "input": [
              {"role": "user", "content": "Classify this text: positive, neutral, or negative."}
            ]
          }
        }
      }
    ]
  }'

Lisääminen Python SDK:lla

SDK:n avulla jokainen pyyntö rakennetaan kuten tavallinen keskustelu, sille määritetään batch_request_id, ja sen jälkeen ne lisätään osissa:

from xai_sdk import Client
from xai_sdk.chat import system, user

client = Client()

documents = [
    {"id": "doc-1", "text": "First document to analyze..."},
    {"id": "doc-2", "text": "Second document to analyze..."},
    {"id": "doc-3", "text": "Third document to analyze..."},
]

batch_id = "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8"

requests = []
for doc in documents:
    chat = client.chat.create(model="grok-4.3", batch_request_id=doc["id"])
    chat.append(system("Summarize the document in two sentences."))
    chat.append(user(doc["text"]))
    requests.append(chat)

# Lisää 100 pyynnön erissä: yksi API-kutsu per erä
for i in range(0, len(requests), 100):
    client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])

Dokumentaatio ei määritä enimmäismäärää pyynnöille kutsua kohden; kohtuulliset eräkoot rajoittavat vain sitä määrää, joka joudutaan lähettämään uudelleen verkkohäiriön sattuessa.

Lisäämisen nopeusrajoitukset

Tiimi voi tehdä enintään 1 000 lisäyskutsua jokaista 30 sekuntia kohden liukuvassa ikkunassa, joka on yhteinen kaikille sen erille. Raja koskee kutsuja, ei pyyntöjä: 100 pyynnön erillä tämä mahdollistaa jo yli 3 000 pyyntöä sekunnissa. Kaksi muuta rajaa ovat tärkeämpiä:

  • 25 Mt enimmäiskoko yksittäistä pyyntöä kohden, mikä koskee pääasiassa base64-koodattuja kuvia
  • Yli 100 000 pyynnön jälkeen erässä xAI voi hidastaa käsittelyä palvelun vakauden säilyttämiseksi

Milloin käyttää API-lisäystä

API-lisäys toimii aina, kun joustavuus on tärkeämpää kuin etukäteisvalmistelu. Siitä tulee luonteva valinta, kun erä rakennetaan vähitellen: jonosta saapuvat pyynnöt lisätään sitä mukaa kun ne tulevat, kun taas JSONL-tiedosto vaatisi kaiken tiedon etukäteen – ja sulkisi erän. Se on myös reitti prototyyppaukseen, jotta voit testata koko työnkulun viidellä pyynnöllä ennen skaalaamista, sekä heterogeenisille erille.

Pyynnön validointi

Tarkista jokaisen lisäyskutsun tilakoodi: virhe tässä vaiheessa tarkoittaa, että erää ei tallennettu, ja sinun on lähetettävä se uudelleen. Pyyntö voi myös epäonnistua myöhemmin käsittelyn aikana; tällöin se näkyy tuloksissa virheilmoituksineen. Malli, joka ei hyväksy erää, hylätään viestillä not supported for batch processing: tarkista kelpoisuus mallisivulta ennen suuren erän käynnistämistä.

Keskeiset asiat

  • Lisäys tapahtuu osoitteeseen POST /v1/batches/{id}/requests käyttäen batch_requests-listaa
  • Jokainen pyyntö sisältää yksilöllisen batch_request_id:n ja sen sisällön tyypin mukaisessa avaimessa (responses, chat_get_completion)
  • SDK rakentaa pyynnöt komennolla client.chat.create(..., batch_request_id=...) ja lisää ne komennolla client.batch.add
  • Raja on 1 000 lisäyskutsua 30 sekunnissa tiimiä kohden; jokainen kutsu voi sisältää useita pyyntöjä
  • Toisin kuin JSONL-tiedosto, API-lisäys jättää erän auki uusille lisäyksille