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

Rajoitukset ja parhaat käytännöt

Oppitunti 12 / 12 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Sinun on tunnettava rajoitukset
  2. Nopeusrajoitukset
  3. JSONL-tiedostorajoitukset
  4. URL-osoitteiden vanheneminen
  5. Parhaat käytännöt tuotannossa
  6. Tarkistuslista ennen tuotantoon siirtoa
  7. Keskeiset asiat
  8. Testaa tietämyksesi

Päivitetty 2. marraskuuta 2026. Perustuen xAI:n dokumentaatioon: eräalennus on 20 % tukikelpoisissa tekstimalleissa, esimerkit noudattavat REST API:a ja virallista xai-sdk:ta (client.batch.*; xAI:n Batch API ei käytä OpenAI:n formaattia, 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ähinnoittelu.

Sinun on tunnettava rajoitukset

Batch API asettaa teknisiä rajoituksia, jotka sinun on otettava huomioon arkkitehtuurissasi. Niiden huomiotta jättäminen johtaa hylkäyksiin, peruutettuihin eriin tai kadonneisiin tuloksiin. Tämä oppitunti tiivistää xAI:n dokumentoimat rajoitukset ja parhaat käytännöt tuotantokäyttöön.

Nopeusrajoitukset

RajoitusArvoLaajuus
Erän luonti2 sekunnissaTiimiä kohden
Erien määräRajoittamatonTiimiä kohden
Request-add-kutsut1 000 / 30 sekuntiaLiukuva ikkuna, jaettu kaikkien tiimin erien kesken
Pyynnön koko25 MtYksittäistä pyyntöä kohden
Pyyntöjä erää kohdenTeoriassa rajoittamatonYli 100 000 pyynnöllä käsittely voi hidastua

Erän luonti: raja 2 luontia sekunnissa on harvoin ongelma, sillä yleensä luot yhden erän operaatiota kohden.

Pyyntöjen lisääminen: rajoitus koskee kutsuja, ja jokainen kutsu sisältää listan pyyntöjä. 100 pyynnön erissä tämä mahdollistaa jo yli 3 000 pyyntöä sekunnissa.

Pyynnön koko: 25 Mt:n raja vaikuttaa pääasiassa base64-koodattuja kuvia sisältäviin pyyntöihin; tekstipyyntö ylittää harvoin muutaman kilotavun.

Sitä vastoin eräpyynnöt eivät kuluta reaaliaikaisen API:n nopeusrajoituksia: suuri erä ei hidasta interaktiivista sovellustasi.

JSONL-tiedostorajoitukset

RajoitusArvo
Pyyntöjä tiedostoa kohdenEnintään 50 000
Tiedoston kokoEnintään 200 Mt
Lisäykset luonnin jälkeenEi mahdollista: erä on suljettu

Jos eräsi ylittää nämä rajat, jaa se useampaan tiedostoon ja luo yksi erä tiedostoa kohden; koostat tulokset jälkikäteen.

URL-osoitteiden vanheneminen

Allekirjoitetut URL-osoitteet kuva- ja videotuloksille vanhenevat tunnin kuluttua. Tämä on kriittisin rajoitus, joka on hallittava tuotannossa: hakuprosessisi on ladattava media välittömästi ilman manuaalista puuttumista (katso oppitunnin 9 funktio telecharger_medias). Tarkkaile erän osalta myös kenttää expire_time, jonka jälkeen tuloksiin ei ole enää pääsyä.

Parhaat käytännöt tuotannossa

Deterministiset tunnisteet

Johda pyyntötunnisteesi (batch_request_id tai custom_id JSONL:ssä) syötedatastasi. Jos joudut lähettämään erän uudelleen, sama data tuottaa samat tunnisteet, mikä helpottaa deduplikaatiota:

import hashlib


def identifiant_requete(document_id: str, operation: str) -> str:
    """Generates a deterministic request ID."""
    brut = f"{document_id}:{operation}"
    return hashlib.sha256(brut.encode()).hexdigest()[:16]

Osittaisten epäonnistumisten käsittely

Täysin käsitelty erä voi silti sisältää epäonnistuneita pyyntöjä. Tarkista aina jokainen tulos:

reussies, echouees = [], []
jeton = None
while True:
    page = client.batch.list_batch_results(
        batch_id=batch_id, limit=1000, pagination_token=jeton
    )
    reussies.extend(page.succeeded)
    echouees.extend(page.failed)
    if page.pagination_token is None:
        break
    jeton = page.pagination_token

if echouees:
    print(f"{len(echouees)} failed requests to resubmit in a new batch")

Kulujen seuranta

Jokainen erä pitää kirjaa kokonaiskustannuksistaan tickeinä (kymmenenmiljardisosa dollaria):

batch = client.batch.get(batch_id=batch_id)
print("Total cost: %.4f $" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))

REST API:n kautta jokaisen tekstipyynnön kustannus näkyy sen tuloksessa kentässä usage.cost_in_usd_ticks.

Lokit ja jäljitettävyys

Lokita jokainen operaatio, jotta voit diagnosoida ongelmia:

import logging

logger = logging.getLogger("batch_api")

logger.info("Batch created: %s", batch_id)
logger.info("File uploaded: %s, %d requests", file_id, len(documents))
logger.info("Results: %d succeeded, %d failed", len(reussies), len(echouees))

Uudelleenyritys viiveellä (Backoff)

Ohimenevien virheiden (aikakatkaisu, nopeusrajoitus, palvelinvirhe) varalta yritä uudelleen kasvavalla viiveellä:

import time


def appel_avec_retry(fonction, max_essais=3):
    for essai in range(max_essais):
        try:
            return fonction()
        except Exception as e:
            if essai == max_essais - 1:
                raise
            attente = 2 ** essai
            print(f"Retrying in {attente} s: {e}")
            time.sleep(attente)

Tarkistuslista ennen tuotantoon siirtoa

Ennen kuin otat Batch API -putken käyttöön tuotannossa, tarkista seuraavat asiat:

  • Malli hyväksyy eräkäsittelyn ja näkyy alennettujen mallien listalla, jos kustannukset ovat merkittäviä
  • Pyyntötunnisteet ovat ainutlaatuisia ja deterministisiä
  • JSONL-tiedosto on validoitu ennen latausta (yksi virheellinen rivi peruuttaa koko erän)
  • Multimodaalisten tulosten lataus on automatisoitu ja suoritetaan tunnin sisällä
  • Osittaiset epäonnistumiset havaitaan ja lähetetään uudelleen uudessa erässä
  • Tulokset haetaan ennen expire_time-ajankohtaa
  • Lokit kattavat koko työnkulun jokaisen vaiheen
  • API-avain luetaan ympäristömuuttujasta, sitä ei koskaan kovakoodata

Keskeiset asiat

  • Rajat: 2 luontia sekunnissa, 1 000 request-add-kutsua 30 sekunnissa, 25 Mt pyyntöä kohden
  • JSONL-tiedostot: enintään 50 000 pyyntöä ja 200 Mt, yksi erä tiedostoa kohden
  • Kuva- ja video-URL-osoitteet vanhenevat tunnissa: lataa ne välittömästi
  • Deterministiset tunnisteet, jokaisen tuloksen tarkistus, kulujen seuranta tickeinä
  • Lokitus, uudelleenyritys viiveellä ja enimmäisaikakatkaisu tuotannossa

Testaa tietämyksesi

Massakäsittely: Batch API ilman harhaanjohtavia kohtia.

1. Milloin Batch API on oikea valinta?

Vastaus: Suurille volyymeille, joissa ei ole reaaliaikavaatimuksia: luokittelu, rikastaminen, arvioinnit, massagenerointi. Eräpyynnöt eivät kuluta nopeusrajoituksia, ja tukikelpoiset tekstimalleet saavat 20 % alennuksen.

2. Mikä on nelivaiheinen työnkulku?

Vastaus: Luo nimetty erä, lisää siihen pyyntöjä (joko API:n kautta tai luomalla erä ladatusta JSONL-tiedostosta), seuraa sen laskureita ja hae sitten tulokset sitä mukaa kuin ne valmistuvat tai lopussa. Käsittely käynnistyy itsestään ilman erillistä käynnistysvaihetta.

3. Mitä erään voi sisällyttää?

Vastaus: Responses-pyyntöjä (suositeltu) ja Chat Completions -pyyntöjä (vanhentunut), palvelintyökaluja ja funktiokutsuja sekä kuvien ja videoiden generointia, muokkausta ja videoiden laajennuksia. Vain tukikelpoisten mallien teksti-tokenit saavat alennuksen.

4. Miten seuraat suorituksen etenemistä?

Vastaus: Erän laskureiden (num_pending, num_success, num_error…), jokaisen pyynnön tilan (pending, succeeded, failed, cancelled) ja sivutettujen tulosten kautta, jotka erottavat onnistumiset epäonnistumisista. Erä on täysin käsitelty, kun num_pending on nolla.

5. Mitkä parhaat käytännöt koskevat rajoituksia?

Vastaus: Lisää pyynnöt erissä, jaa suuret tiedostot yhdeksi eräksi tiedostoa kohden, lataa media tunnin sisällä, hae tulokset ennen expire_time-ajankohtaa ja lähetä epäonnistuneet uudelleen uudessa erässä: suunnittele erä robustina putkena, ei sokeana massalähetyksenä.

Hyvin muodostetut erät, seurattavat laskurit ja uudelleen yritetyt epäonnistumiset: Batch API muuttaa volyymin rutiiniksi parhaalla hinnalla.