Sledenje, stanje in preklic
Na tej strani
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 zahteve | Pomen | Ukrep |
|---|---|---|
pending | V čakalni vrsti | Počakaj |
succeeded | Obdelano, rezultat na voljo | Pridobi rezultat |
failed | Napaka med obdelavo | Preberi sporočilo, ponovi, če je smiselno |
cancelled | Preklicano, na primer s svojim paketom | Ponovno 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,/resultsrezultate,/requestspodrobnosti zahteve- Preklic (
POST /v1/batches/{id}:cancel) je nepovraten, vendar ohrani že proizvedene rezultate - Seznami in rezultati uporabljajo paginacijo z
limitinpagination_token - Izvajaj poizvedbe v intervalih nekaj minut, z največjim zamikom, in pridobi rezultate pred
expire_time