Rajoitukset ja parhaat käytännöt
Tällä sivulla
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
| Rajoitus | Arvo | Laajuus |
|---|---|---|
| Erän luonti | 2 sekunnissa | Tiimiä kohden |
| Erien määrä | Rajoittamaton | Tiimiä kohden |
| Request-add-kutsut | 1 000 / 30 sekuntia | Liukuva ikkuna, jaettu kaikkien tiimin erien kesken |
| Pyynnön koko | 25 Mt | Yksittäistä pyyntöä kohden |
| Pyyntöjä erää kohden | Teoriassa rajoittamaton | Yli 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
| Rajoitus | Arvo |
|---|---|
| Pyyntöjä tiedostoa kohden | Enintään 50 000 |
| Tiedoston koko | Enintään 200 Mt |
| Lisäykset luonnin jälkeen | Ei 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.