Fluss ta' xogħol f'erba' passi
F'din il-paġna
Aġġornat fit-2 ta’ Novembru, 2026 abbażi tad-dokumentazzjoni ta’ xAI: l-iskont għall-batches huwa ta’ 20% fuq mudelli ta’ test eliġibbli (mhux 50%); l-eżempji jużaw l-API REST u l-
xai-sdkuffiċjali (client.batch.*; l-API tal-Batch ta’ xAI ma ssegwix il-format ta’ OpenAI, għalhekk l-SDK ta’ OpenAI ma tapplikax); u l-API tar-Risposti għandha preċedenza fuq Chat Completions, li huwa endpoint antikwat f’xAI. Sorsi: Batch API · Referenza REST · Prezzijiet tal-Batch.
Iċ-ċiklu ta’ ħajja ta’ batch
Kull batch isegwi l-istess ċiklu: oħloq, żid talbiet, ipproċessa, irkupera r-riżultati. Huwa essenzjali li tifhem dan iċ-ċiklu qabel ma tgħaddi għall-implimentazzjoni, għax kull pass għandu r-restrizzjonijiet u l-aħjar prattiki tiegħu.
Pass 1: Oħloq batch
Kollox jibda b’sejħa POST /v1/batches, b’qasam wieħed meħtieġ: l-isem tal-batch. L-API tirritorna identifikatur uniku (batch_id) li tuża għall-operazzjonijiet kollha sussegwenti.
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"}'
Ir-rispons fih ukoll id-dati tal-ħolqien u tal-iskadenza tal-batch (create_time, expire_time) u oġġett state li l-kontaturi tiegħu kollha għadhom żero.
Pass 2: Żid it-talbiet
Hemm żewġ metodi:
Permezz tal-API: tibgħat it-talbiet b’POST /v1/batches/{batch_id}/requests. Kull sejħa ġġib lista ta’ talbiet, u tista’ tkompli żżidhom sakemm il-batch ma jiġix ikkanċellat. Din hija t-triq għal batches mibnija b’mod inkrementali.
Permezz ta’ fajl JSONL: tħejji fajl li fih it-talbiet kollha tiegħek, ittellgħu permezz tal-API tal-Fajls, imbagħad toħloq il-batch minn dak il-fajl. Il-batch imbagħad jiġi issiġillat: m’għadx possibbli li żżid iktar. Din hija t-triq għal volumi kbar imħejjija minn qabel.
Kull talba ġġib identifikatur uniku fil-batch: batch_request_id fl-API, custom_id fil-fajl JSONL. Jekk tonqos fl-API, xAI tiġġenera UUID; agħti tiegħek minflok (ID ta’ database, pereżempju): dan iservi bħala ċ-ċavetta ta’ tqabbil bejn id-data tiegħek u r-riżultati, u jiggarantixxi li talba tiġi pproċessata darba biss.
Pass 3: Immonitorja l-progress
L-ipproċessar jibda hekk kif jaslu t-talbiet; m’hemm l-ebda pass ta’ “bidu”. Frattant, GET /v1/batches/{batch_id} jirritorna l-oġġett state u l-kontaturi tiegħu: num_requests (total), num_pending (pendenti), num_success (suċċess), num_error (falluti), u num_cancelled (ikkanċellati).
curl https://api.x.ai/v1/batches/$BATCH_ID \
-H "Authorization: Bearer $XAI_API_KEY"
Meta num_pending jinżel għal żero, it-talbiet kollha ġew ipproċessati, kemm jekk b’suċċess kif ukoll jekk le. Il-polling perjodiku huwa biżżejjed: ftit sekondi għal batch żgħir ta’ test, ftit minuti għal batch kbir.
Pass 4: Irkupera r-riżultati
Ir-riżultati jinqraw b’GET /v1/batches/{batch_id}/results, mingħajr ma tistenna li l-batch jispiċċa: kull talba tkun disponibbli hekk kif tiġi pproċessata. Ir-rispons huwa paġinat: limit jistabbilixxi d-daqs tal-paġna (massimu 1,000), u t-pagination_token irritornat jintuża biex tintalab il-paġna li jmiss; ikun vojt fl-aħħar paġna.
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: dan jippermettilek terġa’ tibni l-mapping bejn id-data tal-input tiegħek u r-risposti ta’ Grok.
Il-fluss ta’ xogħol fil-prattika
F’pipeline tal-produzzjoni, il-fluss ta’ xogħol ġeneralment jittraduċi f’żewġ proċessi separati:
- Proċess ta’ sottomissjoni li joħloq il-batch, iħejji u jżid it-talbiet, imbagħad jaħżen il-
batch_id - Proċess ta’ rkupru li perjodikament jiċċekkja l-kontaturi u jniżżel ir-riżultati hekk kif isiru disponibbli
Din is-separazzjoni tippermettilek tintegra l-API tal-Batch f’arkitetturi mmexxija minn avvenimenti jew f’pipelines tad-data eżistenti (cron jobs, Apache Airflow, queues).
Ġestjoni tal-iżbalji fil-fluss ta’ xogħol
Batch m’għandux stat globali ta’ “suċċess” jew “falliment”: taqrah permezz tal-kontaturi tiegħu. Talba falluta tiżdied mal-num_error u tidher fir-riżultati bil-messaġġ tal-iżball tagħha, mingħajr ma timblokka l-oħrajn. Għalhekk, trid teżamina kull riżultat u tittratta l-fallimenti każ b’każ.
Żewġ avvenimenti jaffettwaw il-batch kollu. L-ewwel huwa l-kanċellazzjoni, minnek jew minn xAI, li mbagħad tispjegaha fil-qasam cancel_by_xai_message. Dan iseħħ b’mod partikolari meta linja f’fajl JSONL tkun invalida. L-ieħor huwa l-iskadenza (expire_time), wara liema r-riżultati ma jkunux aċċessibbli iktar: irkuprahom malajr.
Punti Ewlenin
- Il-fluss ta’ xogħol isegwi l-ordni: oħloq (b’isem), żid, immonitorja, irkupera
- L-identifikatur tat-talba (
batch_request_id, jewcustom_idf’JSONL) huwa ċ-ċavetta ta’ tqabbil tiegħek - Il-progress jinqara mill-kontaturi ta’
state; kollox jiġi pproċessat metanum_pendingikun żero - Ir-riżultati huma paġinati (
limit,pagination_token) u disponibbli hekk kif jiġu pproċessati - L-iżbalji jiġu ttrattati talba b’talba; il-kanċellazzjoni u l-iskadenza jaffettwaw il-batch kollu