Salt la conținutul principal
Română— Alege o limbă
Meniu

Urmărire, stare și anulare

Lecția 11 din 12 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Gestionarea ciclului de viață al lotului
  2. Două niveluri de stare
  3. Verificarea contoarelor
  4. Listarea loturilor dumneavoastră
  5. Preluarea rezultatelor
  6. Verificarea metadatelor cererii
  7. Anularea unui lot
  8. Strategia de interogare (Polling)
  9. Puncte cheie

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 cerereSemnificațieAcțiune
pendingÎn coadă de așteptareAșteptați
succeededProcesată, rezultat disponibilPreluare rezultat
failedEroare în timpul procesăriiCitiți mesajul, reîncercați dacă este util
cancelledAnulată, de exemplu împreună cu lotul săuRetrimiteț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, /results rezultatele, /requests detaliile cererii
  • Anularea (POST /v1/batches/{id}:cancel) este ireversibilă, dar păstrează rezultatele deja produse
  • Listele și rezultatele se paginează cu limit și pagination_token
  • Interogați la intervale de câteva minute, cu o întârziere maximă, și preluați înainte de expire_time