Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Traċċar, Status u Kanċellazzjoni

Lezzjoni 11 / 12 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Immaniġġja ċ-ċiklu tal-ħajja tal-batch
  2. Żewġ livelli ta’ status
  3. Iċċekkja l-kontaturi
  4. Elenska l-batches tiegħek
  5. Irkupra r-riżultati
  6. Iċċekkja l-metadejta tat-talba
  7. Ikkansella batch
  8. Strateġija ta’ polling
  9. Punti Ewlenin

Aġġornat fit-2 ta’ Novembru 2026 abbażi tad-dokumentazzjoni ta’ xAI: l-iskont tal-batch huwa 20% fuq mudelli tat-test eliġibbli (mhux 50%), l-eżempji jsegwu l-API REST u l-xai-sdk uffiċjali (client.batch.*; l-API tal-Batch ta’ xAI ma taqbilx mal-format ta’ OpenAI, allura l-SDK ta’ OpenAI ma japplikax), u l-API tar-Risposti tieħu preċedenza fuq Chat Completions, li huwa endpoint antikwat f’xAI. Sorsi: Batch API · REST Reference · Batch Pricing.

Immaniġġja ċ-ċiklu tal-ħajja tal-batch

Ladarba tibgħat it-talbiet tiegħek, trid issegwi l-progress tal-ipproċessar, taqra l-istatus u tkun taf meta u kif tikkanċella batch. Din il-lezzjoni tkopri l-operazzjonijiet kollha ta’ ġestjoni disponibbli.

Żewġ livelli ta’ status

xAI issegwi l-progress fuq żewġ livelli. Il-batch innifsu m’għandux status globali bħal “completed” jew “failed”: iġorr kontaturi fl-oġġett state tiegħu. Kull talba, madankollu, għandha l-istatus tagħha stess:

Status tat-talbaTifsiraAzzjoni
pendingFil-kjuStenna
succeededIpproċessata, riżultat disponibbliIrkupra r-riżultat
failedŻball waqt l-ipproċessarAqra l-messaġġ, erġa’ pprova jekk utli
cancelledKanċellata, pereżempju mal-batch tagħhaIbghħat mill-ġdid jekk meħtieġ

Il-batch jiġi pproċessat kompletament meta l-kontatur num_pending tiegħu jinżel għal żero. Jista’ wkoll jiġi kanċellat jew jiskadi: wara expire_time, ir-riżultati tiegħu ma jkunux aċċessibbli aktar.

Iċċekkja l-kontaturi

Is-sejħa GET /v1/batches/{batch_id} tirritorna l-batch u l-kontaturi tiegħu:

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

Ir-rispons jinkludi:

{
  "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
  }
}

Dawn il-kontaturi isegwu l-progress f’ħin reali, mingħajr ma tistenna li l-ipproċessar jintemm. Bl-SDK, aqrahom f’client.batch.get(batch_id=...).state.

Elenska l-batches tiegħek

Biex issib batch jew tiċċekkja l-istorja:

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

Il-lista hija paġinata permezz ta’ limit u pagination_token. Il-batches jibqgħu hemm sakemm jiskadu. Bl-SDK, client.batch.list(limit=20) tirritorna lista ta’ batches fejn kull element iġorr il-name, batch_id u state tiegħu. Il-konsowl ta’ xAI joffri l-istess viżjoni, f’forma viżwali.

Irkupra r-riżultati

Tista’ tirkupra r-riżultati fi kwalunkwe ħin, anke waqt l-ipproċessar:

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

Kull riżultat iġorr il-batch_request_id tat-talba tiegħu. It-talbiet falluti jidhru hemmhekk bil-messaġġ tagħhom; bl-SDK, il-proprjetajiet succeeded u failed ta’ kull paġna jisseparawhom.

Iċċekkja l-metadejta tat-talba

Biex issegwi l-istatus ta’ kull talba:

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

Kull dħul jagħti l-identifikatur tat-talba, l-endpoint tiegħu, il-mudell, l-istatus, u d-dati tal-ħolqien u t-tmiem. Dan huwa l-għodda dijanjostika meta kontatur jieqaf, jew biex tivverifika x’inżied b’suċċess.

Ikkansella batch

Jekk għandek bżonn twaqqaf l-ipproċessar li għaddej:

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

Il-kanċellazzjoni hija finali: it-talbiet pendenti ma jiġux ipproċessati, u ma tistax iżżid talbiet oħra mal-batch. It-talbiet diġà pproċessati, madankollu, jibqgħu disponibbli fir-riżultati. Ikkansella jekk:

  • Skoprejt żball fit-talbiet tiegħek wara s-sottomissjoni
  • Il-batch m’għadux meħtieġ (bidla fil-prijorità)
  • Trid tibgħat mill-ġdid batch ikkoreġut

Bl-SDK: client.batch.cancel(batch_id=...), li tirritorna l-batch u l-kontaturi tiegħu fil-mument tal-kanċellazzjoni.

Strateġija ta’ polling

Fil-produzzjoni, stenna t-tlestija b’polling spazjat u dewmien massimu:

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")

Intervall ta’ ftit minuti jixraq għal batches kbar; id-dokumentazzjoni ta’ xAI tagħmel polling kull ftit sekondi fl-eżempji tagħha, li jkopru batches żgħar. U peress li r-riżultati huma disponibbli hekk kif jaslu, xejn ma jipprevjenik milli tirkuprahom waqt l-istennija.

Punti Ewlenin

  • Aqra l-batch mill-kontaturi tiegħu (num_pending, num_success, num_error…); kull talba għandha l-istatus tagħha: pending, succeeded, failed, cancelled
  • GET /v1/batches/{id} jagħti l-progress, /results ir-riżultati, /requests id-dettall tat-talba
  • Il-kanċellazzjoni (POST /v1/batches/{id}:cancel) hija irreversibbli, iżda żżomm ir-riżultati diġà prodotti
  • Il-listi u r-riżultati huma paġinati b’limit u pagination_token
  • Agħmel polling f’intervalli ta’ ftit minuti, b’dewmien massimu, u irkupra qabel expire_time