Rianú, Stádas, agus Cealú
Ar an leathanach seo
Nuashonraithe an 2 Samhain 2026 bunaithe ar dhoiciméadú xAI: tá lascaine 20% ar mhúnlaí téacs incháilithe (ní 50%), leanann na samplaí an REST API agus an
xai-sdkoifigiúil (client.batch.*; ní hionann formáid Batch API xAI agus formáid OpenAI, mar sin ní bhaineann an OpenAI SDK leis), agus tá an Responses API chun tosaigh ar Chat Completions, atá ina phointe deiridh sinsearach ag xAI. Foinse: Batch API · REST Reference · Batch Pricing.
Bainistíocht shaolré an bhaisc
A luaithe a chuireann tú d’iarratais isteach, ní mór duit dul chun cinn an phróiseála a rianú, stádasanna a léamh, agus a fháil amach cathain agus conas baisc a chealú. Clúdaíonn an ceacht seo gach oibríocht bainistíochta atá ar fáil.
Dhá leibhéal stádais
Rianaíonn xAI an dul chun cinn ar dhá leibhéal. Níl aon stádas domhanda cosúil le “críochnaithe” nó “teipthe” ag an mbaisc féin: tá cuntair ina oibiacht state aige. Gach iarratas, áfach, tá a stádas féin aige:
| Stádas an iarratais | Brí | Gníomh |
|---|---|---|
pending | Sa scuaine | Fan |
succeeded | Próiseáilte, toradh ar fáil | Faigh an toradh |
failed | Earráid le linn próiseála | Léigh an teachtaireacht, déan iarracht arís más fiú |
cancelled | Cealaithe, mar shampla lena bhaisc | Cuir isteach arís más gá |
Déantar an baisc a phróiseáil go hiomlán nuair a thiteann an cuntar num_pending go dtí nialas. Is féidir é a chealú nó dul in éag freisin: tar éis expire_time, ní bheidh rochtain ar a thorthaí a thuilleadh.
Seiceáil na gcuntar
Tugann an glao GET /v1/batches/{batch_id} an baisc agus a chuntair ar ais:
curl "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY"
Áirítear sa fhreagra:
{
"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
}
}
Rianaíonn na cuntair seo an dul chun cinn i bhfíor-am, gan fanacht go gcríochnófar an phróiseáil. Leis an SDK, léigh iad in client.batch.get(batch_id=...).state.
Liostaigh do bhaisc
Chun baisc a aimsiú nó stair a sheiceáil:
curl "https://api.x.ai/v1/batches?limit=20" \
-H "Authorization: Bearer $XAI_API_KEY"
Tá an liosta leathanaithe de réir limit agus pagination_token. Fanann baisc ann go dtí go dtéann siad in éag. Leis an SDK, filleann client.batch.list(limit=20) liosta batches ina bhfuil name, batch_id, agus state ag gach eilimint. Tairgeann consól xAI an t-amharc céanna, i bhfoirm amhairc.
Torthaí a fháil
Is féidir leat torthaí a fháil ag am ar bith, fiú le linn próiseála:
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Iompraíonn gach toradh batch_request_id a iarratais. Feictear iarratais theipthe anseo lena dteachtaireacht; leis an SDK, scarann na hairíonna succeeded agus failed de gach leathanach iad.
Meiteashonraí iarratais a sheiceáil
Chun stádas gach iarratais a rianú:
curl "https://api.x.ai/v1/batches/$BATCH_ID/requests?limit=50" \
-H "Authorization: Bearer $XAI_API_KEY"
Tugann gach iontráil aitheantóir an iarratais, a phointe deiridh, an múnla, an stádas, agus dátaí cruthaithe agus deiridh. Is é seo an uirlis dhiagnóiseach nuair a stopann cuntar, nó chun a fhíorú cad a cuireadh leis go rathúil.
Baisc a chealú
Má theastaíonn uait próiseáil atá ar siúl a stopadh:
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID:cancel" \
-H "Authorization: Bearer $XAI_API_KEY"
Tá an cealú críochnaitheach: ní phróiseálfar iarratais atá ar feitheamh, agus ní féidir leat iarratais a chur leis an mbaisc a thuilleadh. Fanann iarratais a próiseáladh cheana féin ar fáil sna torthaí, áfach. Déan cealú má:
- Braitheann tú earráid in d’iarratais tar éis iad a chur isteach
- Níl gá leis an mbaisc a thuilleadh (athrú tosaíochta)
- Ba mhaith leat baisc cheartaithe a chur isteach arís
Leis an SDK: client.batch.cancel(batch_id=...), a fhilleann an baisc agus a chuntair ag am an chealaithe.
Straitéis polaithe
Sa táirgeadh, fan go gcríochnófar le poladh spásáilte agus moill uasta:
import time
def attendre_batch(client, batch_id, intervalle=300, delai_max=2 * 86400):
"""Fan go bpróiseálfar gach iarratas sa bhaisc."""
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")
Oireann eatramh cúpla nóiméad do bhaisc mhóra; déanann doiciméadú xAI poladh gach cúpla soicind ina shamplaí, a chlúdaíonn baisc bheaga. Agus ós rud é go bhfuil torthaí ar fáil de réir mar a thagann siad isteach, ní chuireann aon rud bac orthu a fháil le linn na feithimh.
Príomhphointí
- Léigh an baisc trína chuntair (
num_pending,num_success,num_error…); tá stádas ag gach iarratas:pending,succeeded,failed,cancelled - Tugann
GET /v1/batches/{id}an dul chun cinn,/resultsna torthaí,/requestsmionsonraí an iarratais - Tá an cealú (
POST /v1/batches/{id}:cancel) dochúlaithe, ach coinníonn sé torthaí a táirgeadh cheana féin - Déantar liostaí agus torthaí a leathnú le
limitaguspagination_token - Déan poladh gach cúpla nóiméad, le moill uasta, agus faigh torthaí roimh
expire_time