Urmărire, stare și anulare
Pe această pagină
Actualizat la 2 noiembrie 2026 pe baza documentației xAI: reducerea pentru loturi este de 20% la modelele de text eligibile (nu 50%), exemplele respectă API-ul REST și SDK-ul oficial
xai-sdk(client.batch.*; API-ul Batch de la xAI nu corespunde formatului OpenAI, deci SDK-ul OpenAI nu se aplică), iar API-ul Responses are prioritate față de Chat Completions, un punct final moștenit la xAI. Surse: Batch API · REST Reference · Batch Pricing.
Gestionarea ciclului de viață al lotului
Odată ce ați trimis cererile, trebuie să urmăriți progresul procesării, să citiți stările și să știți când și cum să anulați un lot. Această lecție acoperă toate operațiunile de gestionare disponibile.
Două niveluri de stare
xAI urmărește progresul la două niveluri. Lotul în sine nu are o stare globală precum „finalizat“ sau „eșuat“: acesta conține contoare în obiectul său state. Fiecare cerere, însă, are propria stare:
| Stare cerere | Semnificație | Acțiune |
|---|---|---|
pending | În coadă de așteptare | Așteptați |
succeeded | Procesată, rezultat disponibil | Preluare rezultat |
failed | Eroare în timpul procesării | Citiți mesajul, reîncercați dacă este util |
cancelled | Anulată, de exemplu împreună cu lotul său | Retrimiteți dacă este necesar |
Lotul este procesat complet atunci când contorul său num_pending scade la zero. Acesta poate fi, de asemenea, anulat sau poate expira: după expire_time, rezultatele sale nu mai sunt accesibile.
Verificarea contoarelor
Apelul GET /v1/batches/{batch_id} returnează lotul și contoarele sale:
curl "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY"
Răspunsul include:
{
"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
}
}
Aceste contoare urmăresc progresul în timp real, fără a aștepta finalizarea procesării. Cu SDK-ul, le citiți în client.batch.get(batch_id=...).state.
Listarea loturilor dumneavoastră
Pentru a găsi un lot sau a verifica istoricul:
curl "https://api.x.ai/v1/batches?limit=20" \
-H "Authorization: Bearer $XAI_API_KEY"
Lista este paginată prin limit și pagination_token. Loturile rămân acolo până la expirare. Cu SDK-ul, client.batch.list(limit=20) returnează o listă batches unde fiecare element conține name, batch_id și state. Consola xAI oferă aceeași vizualizare, sub formă grafică.
Preluarea rezultatelor
Puteți prelua rezultatele în orice moment, chiar și în timpul procesării:
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Fiecare rezultat conține batch_request_id al cererii sale. Cererile eșuate apar acolo împreună cu mesajul lor; cu SDK-ul, proprietățile succeeded și failed ale fiecărei pagini le separă.
Verificarea metadatelor cererii
Pentru a urmări starea fiecărei cereri:
curl "https://api.x.ai/v1/batches/$BATCH_ID/requests?limit=50" \
-H "Authorization: Bearer $XAI_API_KEY"
Fiecare intrare oferă identificatorul cererii, punctul său final, modelul, starea, precum și datele de creare și de încheiere. Acesta este instrumentul de diagnosticare atunci când un contor se blochează sau pentru a verifica ce a fost adăugat cu succes.
Anularea unui lot
Dacă trebuie să opriți procesarea în curs:
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID:cancel" \
-H "Authorization: Bearer $XAI_API_KEY"
Anularea este definitivă: cererile în așteptare nu vor fi procesate și nu mai puteți adăuga cereri la lot. Cererile deja procesate, totuși, rămân disponibile în rezultate. Anulați dacă:
- Ați detectat o eroare în cererile dumneavoastră după trimitere
- Lotul nu mai este necesar (schimbare de prioritate)
- Doriți să retrimiteți un lot corectat
Cu SDK-ul: client.batch.cancel(batch_id=...), care returnează lotul și contoarele sale la momentul anulării.
Strategia de interogare (Polling)
În producție, așteptați finalizarea prin interogări spațiate și o întârziere maximă:
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")
Un interval de câteva minute este potrivit pentru loturi mari; documentația xAI interoghează la fiecare câteva secunde în exemplele sale, care acoperă loturi mici. Și deoarece rezultatele sunt disponibile pe măsură ce sosesc, nimic nu vă împiedică să le preluați în timpul așteptării.
Puncte cheie
- Citiți lotul prin contoarele sale (
num_pending,num_success,num_error…); fiecare cerere are propria stare:pending,succeeded,failed,cancelled GET /v1/batches/{id}oferă progresul,/resultsrezultatele,/requestsdetaliile cererii- Anularea (
POST /v1/batches/{id}:cancel) este ireversibilă, dar păstrează rezultatele deja produse - Listele și rezultatele se paginează cu
limitșipagination_token - Interogați la intervale de câteva minute, cu o întârziere maximă, și preluați înainte de
expire_time