Sreabhadh oibre ceithre chéim
Ar an leathanach seo
Nuashonraithe an 2 Samhain, 2026 bunaithe ar dhoiciméadú xAI: tá lascaine 20% ar fáil ar mhúnlaí téacs incháilithe (ní 50%); úsáideann na samplaí an REST API agus an
xai-sdkoifigiúil (client.batch.*; ní leanann Batch API xAI formáid OpenAI, mar sin ní bhaineann an OpenAI SDK leis); agus tá an tResponses API chun tosaigh ar Chat Completions, atá ina phointe deiridh leagtha amach ag xAI. Foinse: Batch API · Tagairt REST · Praghsáil Batch.
Timthriall saoil baisce
Leanann gach baisc an timthriall céanna: cruthaigh, cuir iarratais leis, próiseáil, faigh torthaí. Tá sé ríthábhachtach an timthriall seo a thuiscint sula ndéanann tú cur chun feidhme, toisc go bhfuil srianta agus dea-chleachtais ar leith ag baint le gach céim.
Céim 1: Baisc a chruthú
Tosaíonn gach rud le glao POST /v1/batches, le réimse amháin éigeantach: ainm na baisce. Filleann an API aitheantóir uathúil (batch_id) a úsáideann tú do gach oibríocht ina dhiaidh sin.
curl -X POST https://api.x.ai/v1/batches \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "customer_review_analysis"}'
Tá dátaí cruthaithe agus éaga na baisce (create_time, expire_time) sa fhreagra freisin, chomh maith le réad state a bhfuil a chuid comhaireamh go léir fós ag nialas.
Céim 2: Iarratais a chur leis
Tá dhá mhodh ann:
Tríd an API: seolann tú iarratais le POST /v1/batches/{batch_id}/requests. Iompraíonn gach glao liosta iarratas, agus is féidir leat iad a chur leis fad is nach bhfuil an bhaisc cealaithe. Seo an bealach do bhaisceanna a thógtar de réir a chéile.
Tríd comhad JSONL: ullmhaíonn tú comhad ina bhfuil do chuid iarratas go léir, uaslódálann tú é tríd an Files API, agus ansin cruthaíonn tú an bhaisc ón gcomhad sin. Ansin, tá an bhaisc séalaite: ní féidir aon rud eile a chur leis. Seo an bealach do thoirt mhór ullmhaithe roimh ré.
Iompraíonn gach iarratas aitheantóir uathúil laistigh den bhaisc: batch_request_id san API, custom_id sa chomhad JSONL. Má fhágann tú ar lár é san API, gineann xAI UUID; tabhair do cheann féin ina ionad (ID bunachair sonraí, mar shampla): feidhmíonn sé mar eochair meaitseála idir do chuid sonraí agus na torthaí, agus ráthaíonn sé nach bpróiseáiltear iarratas ach uair amháin.
Céim 3: Dul chun cinn a mhonatóiriú
Tosaíonn an phróiseáil chomh luath agus a thagann iarratais isteach; níl aon chéim “tosaigh” ann. I rith an ama sin, filleann GET /v1/batches/{batch_id} an réad state agus a chuid comhaireamh: num_requests (iomlán), num_pending (ar feitheamh), num_success (rathúil), num_error (teipthe), agus num_cancelled (cealaithe).
curl https://api.x.ai/v1/batches/$BATCH_ID \
-H "Authorization: Bearer $XAI_API_KEY"
Nuair a thiteann num_pending go nialas, tá gach iarratas próiseáilte, cibé acu go rathúil nó nach ea. Is leor polú tréimhsiúil: cúpla soicind do bhaisc tástála beag, cúpla nóiméad do bhaisc mhór.
Céim 4: Torthaí a fháil
Léitear torthaí le GET /v1/batches/{batch_id}/results, gan fanacht go gcríochnaíonn an bhaisc: tá gach iarratas ar fáil chomh luath agus a phróiseáiltear é. Tá an fhreagra leathanaithe: socraíonn limit méid an leathanaigh (1,000 ar a mhéad), agus úsáidtear an pagination_token a fhilltear chun an chéad leathanach eile a iarradh; tá sé folamh ar an leathanach deireanach.
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: ligeann sé seo duit an mhapáil idir do chuid sonraí ionchuir agus freagraí Grok a athchruthú.
An sreabhadh oibre i gcleachtas
I bpíblíne táirgeachta, aistrítear an sreabhadh oibre go hiondúil ina dhá phróiseas ar leith:
- Próiseas cur isteach a chruthaíonn an bhaisc, a ullmhaíonn agus a chuireann iarratais leis, agus a stórálann an
batch_id - Próiseas aisghabhála a sheiceálann na comhaireamh go tréimhsiúil agus a íoslódálann torthaí de réir mar a bhíonn siad ar fáil
Ligeann an deighilt seo duit an Batch API a chomhtháthú in ailtireachtaí tiomáinte ag imeachtaí nó i bpíblíní sonraí atá ann cheana (postais cron, Apache Airflow, ciúnna).
Láimhseáil earráidí sa sreabhadh oibre
Níl staid “rathúil” ná “teipthe” ghlobálach ag baisc: léann tú í trína cuid comhaireamh. Méadaíonn iarratas teipthe num_error agus feictear é sna torthaí lena theachtaireacht earráide, gan bac a chur ar chinn eile. Dá bhrí sin, ní mór duit gach toradh a scrúdú agus teipeanna a láimhseáil ó chás go cás.
Tá dhá imeacht a théann i bhfeidhm ar an mbaisc iomlán. Is é an chéad cheann cealú, agatsa nó ag xAI, a mhíníonn sé ansin sa réimse cancel_by_xai_message. Tarlaíonn sé seo go háirithe nuair atá líne i gcomhad JSONL neamhbhailí. Is é an ceann eile éag (expire_time), agus ina dhiaidh sin ní bhíonn torthaí inrochtana a thuilleadh: faigh iad go pras.
Príomhphointí
- Leanann an sreabhadh oibre an t-ord: cruthaigh (le hainm), cuir leis, monatóirigh, faigh
- Is é an t-aitheantóir iarratais (
batch_request_id, nócustom_idi JSONL) do eochair meaitseála - Léitear an dul chun cinn ó na comhaireamh
state; próiseáiltear gach rud nuair atánum_pendingcothrom le nialas - Tá torthaí leathanaithe (
limit,pagination_token) agus ar fáil de réir mar a phróiseáiltear iad - Déantar earráidí a láimhseáil iarratas ar iarratas; téann cealú agus éag i bhfeidhm ar an mbaisc iomlán