Keturių žingsnių darbo eiga
Šiame puslapyje
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_idarbacustom_idJSONL faile) yra jūsų derinimo raktas - Pažanga skaitoma iš
stateskaitiklių; viskas apdorota, kainum_pendinglygu 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ą