Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Sledenje, stanje in preklic

Lekcija 11 od 12 Posodobljeno 2. november 2026 Razvijalec
Na tej strani
  1. Upravljanje življenjskega cikla paketa
  2. Dve ravni stanja
  3. Preverjanje števcov
  4. Izpis tvojih paketov
  5. Pridobivanje rezultatov
  6. Preverjanje metapodatkov zahteve
  7. Preklic paketa
  8. Strategija anketiranja (Polling)
  9. Ključne ugotovitve

Posodobljeno 2. novembra 2026 na podlagi dokumentacije xAI: popust za paketne obdelave znaša 20 % za ustrezne besedilne modele (ne 50 %), primeri sledijo REST API-ju in uradnemu paketu xai-sdk (client.batch.*; paketni API xAI se ne ujema s formatom OpenAI, zato paket SDK OpenAI ne velja), API Responses pa ima prednost pred Chat Completions, ki je pri xAI zastarela končna točka. Viri: Batch API · REST Reference · Batch Pricing.

Upravljanje življenjskega cikla paketa

Ko pošlješ svoje zahteve, moraš spremljati napredek obdelave, brati stanja in vedeti, kdaj ter kako preklicati paket. Ta lekcija pokriva vse razpoložljive operacije upravljanja.

Dve ravni stanja

xAI spremlja napredek na dveh ravneh. Sam paket nima globalnega stanja, kot sta „končano” ali „neuspešno”: v svojem predmetu state vsebuje števce. Vsaka zahteva pa ima svoje lastno stanje:

Stanje zahtevePomenUkrep
pendingV čakalni vrstiPočakaj
succeededObdelano, rezultat na voljoPridobi rezultat
failedNapaka med obdelavoPreberi sporočilo, ponovi, če je smiselno
cancelledPreklicano, na primer s svojim paketomPonovno pošlji, če je potrebno

Paket je v celoti obdelan, ko se njegov števec num_pending zniža na nič. Lahko ga tudi prekličeš ali pa poteče: po času expire_time njegovi rezultati niso več dostopni.

Preverjanje števcov

Klic GET /v1/batches/{batch_id} vrne paket in njegove števce:

curl "https://api.x.ai/v1/batches/$BATCH_ID" \
  -H "Authorization: Bearer $XAI_API_KEY"

Odgovor vključuje:

{
  "batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
  "name": "analyse_avis_clients",
  "state": {
    "num_requests": 500,
    "num_pending": 155,
    "num_success": 342,
    "num_error": 3,
    "num_cancelled": 0
  }
}

Ti števci spremljajo napredek v realnem času, brez čakanja na konec obdelave. S paketom SDK jih prebereš v client.batch.get(batch_id=...).state.

Izpis tvojih paketov

Če želiš najti paket ali preveriti zgodovino:

curl "https://api.x.ai/v1/batches?limit=20" \
  -H "Authorization: Bearer $XAI_API_KEY"

Seznam je omejen s parametroma limit in pagination_token. Paketi ostanejo tam do poteka. S paketom SDK client.batch.list(limit=20) vrne seznam batches, kjer vsak element nosi svoje ime name, batch_id in state. Konzola xAI ponuja enak pogled, v vizualni obliki.

Pridobivanje rezultatov

Rezultate lahko pridobiš kadarkoli, tudi med obdelavo:

curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
  -H "Authorization: Bearer $XAI_API_KEY"

Vsak rezultat nosi batch_request_id svoje zahteve. Neuspele zahteve se tam pojavijo s svojim sporočilom; s paketom SDK jih ločita lastnosti succeeded in failed vsake strani.

Preverjanje metapodatkov zahteve

Za sledenje stanju vsake zahteve:

curl "https://api.x.ai/v1/batches/$BATCH_ID/requests?limit=50" \
  -H "Authorization: Bearer $XAI_API_KEY"

Vsak vnos poda identifikator zahteve, njeno končno točko, model, stanje ter datuma ustvarjanja in zaključka. To je diagnostično orodje, ko se števec ustavi, ali za preverjanje, kaj je bilo uspešno dodano.

Preklic paketa

Če moraš ustaviti obdelavo v teku:

curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID:cancel" \
  -H "Authorization: Bearer $XAI_API_KEY"

Preklic je dokončen: zahteve na čakanju ne bodo obdelane in zahtev paketu ne moreš več dodajati. Zahteve, ki so bile že obdelane, pa ostanejo na voljo v rezultatih. Prekliči, če:

  • Si po oddaji zaznal napako v svojih zahtevah
  • Paket ni več potreben (sprememba prioritet)
  • Želiš ponovno poslati popravljen paket

S paketom SDK: client.batch.cancel(batch_id=...), ki vrne paket in njegove števce v času preklica.

Strategija anketiranja (Polling)

V produkcijskem okolju počakaj na zaključek z razmaknjenim anketiranjem in največjim zamikom:

import time


def attendre_batch(client, batch_id, intervalle=300, delai_max=2 * 86400):
    """Wait until all requests in the batch are processed."""
    debut = time.monotonic()
    while time.monotonic() - debut < delai_max:
        batch = client.batch.get(batch_id=batch_id)
        etat = batch.state
        if batch.cancel_by_xai_message:
            raise RuntimeError(f"Canceled by xAI: {batch.cancel_by_xai_message}")
        if etat.num_requests > 0 and etat.num_pending == 0:
            return batch
        print(f"{etat.num_success} succeeded, {etat.num_error} failed, "
              f"{etat.num_pending} pending out of {etat.num_requests}")
        time.sleep(intervalle)
    raise TimeoutError(f"Batch not finished after {delai_max} s")

Interval nekaj minut ustreza velikim paketom; dokumentacija xAI v svojih primerih, ki pokrivajo majhne pakete, izvaja poizvedbe vsakih nekaj sekund. Ker so rezultati na voljo, ko prispejo, ti nič ne preprečuje, da jih pridobiš med čakanjem.

Ključne ugotovitve

  • Paket beri po njegovih števcih (num_pending, num_success, num_error…); vsaka zahteva ima svoje stanje: pending, succeeded, failed, cancelled
  • GET /v1/batches/{id} poda napredek, /results rezultate, /requests podrobnosti zahteve
  • Preklic (POST /v1/batches/{id}:cancel) je nepovraten, vendar ohrani že proizvedene rezultate
  • Seznami in rezultati uporabljajo paginacijo z limit in pagination_token
  • Izvajaj poizvedbe v intervalih nekaj minut, z največjim zamikom, in pridobi rezultate pred expire_time