Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Keturių žingsnių darbo eiga

Paskaita 2 iš 12 Atnaujinta 2026 m. lapkričio 2 d. Kūrėjas
Šiame puslapyje
  1. Paketo gyvavimo ciklas
  2. 1 žingsnis: Paketo sukūrimas
  3. 2 žingsnis: Užklausų pridėjimas
  4. 3 žingsnis: Eigos stebėjimas
  5. 4 žingsnis: Rezultatų gavimas
  6. Darbo eiga praktikoje
  7. Klaidų tvarkymas darbo eigoje
  8. Svarbiausi punktai

Atnaujinta 2026 m. lapkričio 2 d. pagal xAI dokumentaciją: nuolaida paketams yra 20 % tinkamiems teksto modeliams (ne 50 %); pavyzdžiuose naudojama REST API ir oficialus xai-sdk (client.batch.*; xAI paketų API nesilaiko „OpenAI“ formato, todėl „OpenAI“ SDK netinka); „Responses“ API turi pirmenybę prieš „Chat Completions“, kuris xAI sistemoje yra pasenusi galutinė sąsaja. Šaltiniai: Paketų API · REST nuorodos · Paketų kainodara.

Paketo gyvavimo ciklas

Kiekvienas paketas vyksta tuo pačiu ciklu: sukūrimas, užklausų pridėjimas, apdorojimas, rezultatų gavimas. Prieš pereidamas prie įgyvendinimo, privalai suprasti šį ciklą, nes kiekvienas žingsnis turi savo apribojimus ir geriausią praktiką.

1 žingsnis: Paketo sukūrimas

Viskas prasideda nuo POST /v1/batches užklausos, kurioje yra vienas privalomas laukas: paketo pavadinimas. API grąžina unikalų identifikatorių (batch_id), kurį naudosite visoms tolesnėms operacijoms.

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

Atsakyme taip pat pateikiami paketo sukūrimo ir galiojimo pabaigos laikai (create_time, expire_time) bei state objektas, kurio skaitikliai vis dar yra nuliniai.

2 žingsnis: Užklausų pridėjimas

Yra du būdai:

Per API: siunčiate užklausas naudodami POST /v1/batches/{batch_id}/requests. Kiekvienas kvietimas perduoda užklausų sąrašą, ir galite jas pridėti tol, kol paketas nėra atšauktas. Tai kelias paketams, kuriamiems palaipsniui.

Per JSONL failą: paruošiate failą su visomis savo užklausomis, įkeliate jį per Files API, o tada sukuriate paketą iš to failo. Tuomet paketas yra užplombuojamas: daugiau nieko pridėti nebegalima. Tai kelias dideliems iš anksto paruoštiems duomenų kiekiams.

Kiekviena užklausa turi unikalų identifikatorių paketo viduje: batch_request_id naudojant API arba custom_id JSONL faile. Jei API atveju jo nenurodysite, xAI sugeneruos UUID; vietoj to pateikite savo (pvz., duomenų bazės ID): tai tarnauja kaip derinimo raktas tarp jūsų duomenų ir rezultatų bei garantuoja, kad užklausa bus apdorota tik vieną kartą.

3 žingsnis: Eigos stebėjimas

Apdorojimas prasideda iškart, kai tik gaunamos užklausos; atskiro „pradėti“ žingsnio nėra. Tuo tarpu GET /v1/batches/{batch_id} grąžina state objektą ir jo skaitiklius: num_requests (iš viso), num_pending (laukiančių), num_success (sėkmingų), num_error (nepavykusių) ir num_cancelled (atšauktų).

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

Kai num_pending nukrenta iki nulio, visos užklausos yra apdorotos – nesvarbu, sėkmingai ar ne. Pakanka periodinio apklausimo: mažam bandomajam paketui – kelios sekundės, dideliam – kelios minutės.

4 žingsnis: Rezultatų gavimas

Rezultatai nuskaityti galima naudojant GET /v1/batches/{batch_id}/results, nelaukiant, kol paketas bus baigtas: kiekviena užklausa pasiekiama iškart, kai tik ji apdorojama. Atsakymas yra puslapiuojamas: limit nustato puslapio dydį (daugiausia 1 000), o grąžinamas pagination_token naudojamas kitam puslapiui gauti; paskutiniame puslapyje jis būna tuščias.

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

Kiekviename rezultate yra atitinkamos užklausos batch_request_id: tai leidžia atkurti ryšį tarp jūsų įvesties duomenų ir Grok atsakymų.

Darbo eiga praktikoje

Gamybinėje aplinkoje ši darbo eiga dažniausiai išskaidoma į du atskirus procesus:

  • Pateikimo procesas, kuris sukuria paketą, paruošia ir prideda užklausas, tada išsaugo batch_id
  • Gavimo procesas, kuris periodiškai tikrina skaitiklius ir atsisiunčia rezultatus, kai tik jie tampa prieinami

Šis atskyrimas leidžia integruoti Paketų API į įvykiais grindžiamas architektūras arba esamas duomenų pipelines (cron užduotis, Apache Airflow, eiles).

Klaidų tvarkymas darbo eigoje

Paketas neturi bendros „pavyko“ arba „nepavyko“ būsenos: ją skaitote per skaitiklius. Nepavykusi užklausa padidina num_error ir atsiranda rezultatuose su savo klaidos pranešimu, nestabdydama kitų. Todėl turite išnagrinėti kiekvieną rezultatą ir tvarkyti nesėkmes atskirai.

Du įvykiai paveikia visą paketą. Pirmasis yra atšaukimas – jūsų arba xAI iniciatyva, tuomet priežastis paaiškinama lauke cancel_by_xai_message. Tai ypač nutinka, kai JSONL faile yra neteisinga eilutė. Kitas įvykis – galiojimo pabaiga (expire_time), po kurios rezultatai tampa nepasiekiami: gaukite juos laiku.

Svarbiausi punktai

  • Darbo eiga vyksta tokia tvarka: sukurti (su pavadinimu), pridėti, stebėti, gauti
  • Užklausos identifikatorius (batch_request_id arba custom_id JSONL faile) yra jūsų derinimo raktas
  • Pažanga skaitoma iš state skaitiklių; viskas apdorota, kai num_pending lygu nuliui
  • Rezultatai yra puslapiuojami (limit, pagination_token) ir pasiekiami apdorojimo metu
  • Klaidos tvarkomos užklausa po užklausos; atšaukimas ir galiojimo pabaiga paveikia visą paketą