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

Fluss ta' xogħol f'erba' passi

Lezzjoni 2 / 12 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Iċ-ċiklu ta’ ħajja ta’ batch
  2. Pass 1: Oħloq batch
  3. Pass 2: Żid it-talbiet
  4. Pass 3: Immonitorja l-progress
  5. Pass 4: Irkupera r-riżultati
  6. Il-fluss ta’ xogħol fil-prattika
  7. Ġestjoni tal-iżbalji fil-fluss ta’ xogħol
  8. Punti Ewlenin

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-sdk uffiċ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, jew custom_id f’JSONL) huwa ċ-ċavetta ta’ tqabbil tiegħek
  • Il-progress jinqara mill-kontaturi ta’ state; kollox jiġi pproċessat meta num_pending ikun ż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