Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Neljaastmeline töövoog

Õppetund 2 / 12 Värskendatud 2. november 2026 Arendajatele
Sellel lehel
  1. Partii elutsükkel
  2. 1. samm: Partii loomine
  3. 2. samm: Päringute lisamine
  4. 3. samm: Edu jälgimine
  5. 4. samm: Tulemuste kättesaamine
  6. Töövoog praktikas
  7. Veakäsitlus töövoos
  8. Peamised punktid

Uuendatud 2. novembril 2026 vastavalt xAI dokumentatsioonile: soodustus partii töötlemisel on 20% sobivate teksti mudelite puhul (mitte 50%); näited kasutavad REST API-t ja ametlikku xai-sdk (client.batch.*; xAI partii API ei järgi OpenAI vormingut, seega OpenAI SDK ei kehti); ja Responses API-l on ülimuslikkus vestluse lõpetamise (Chat Completions) ees, mis on xAI puhul iganenud lõpp-punkt. Allikad: Partii API · REST viide · Partii hinnakiri.

Partii elutsükkel

Iga partii läbib sama tsükli: loomine, päringute lisamine, töötlemine ja tulemuste kättesaamine. Selle tsükli mõistmine on enne rakendamist hädavajalik, kuna igal etapil on oma piirangud ja parimad tavad.

1. samm: Partii loomine

Kõik algab POST /v1/batches väljakutsest, millel on üks kohustuslik väli: partii nimi. API tagastab unikaalse identifikaatori (batch_id), mida kasutad kõigis järgnevates toimingutes.

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

Vastus sisaldab ka partii loomise ja aegumise kuupäevi (create_time, expire_time) ning objekti state, mille loendurid on veel kõik nullis.

2. samm: Päringute lisamine

Selleks on kaks meetodit:

API kaudu: saadad päringud kasutades POST /v1/batches/{batch_id}/requests. Iga väljakutse kannab endas päringute loendit ja saad neid lisada seni, kuni partii on tühistamata. See on tee partiide jaoks, mida koostatakse järk-järgult.

JSONL-faili kaudu: valmistad ette faili, mis sisaldab kõiki sinu päringuid, laadid selle üles Files API kaudu ja lood seejärel partii sellest failist. Partii on seejärel suletud: lisamised pole enam võimalikud. See on tee suurte, ette valmistatud mahtude jaoks.

Iga päring kannab partiis unikaalset identifikaatorit: API puhul batch_request_id, JSONL-failis custom_id. Kui sa selle API-s ära ei märgi, genereerib xAI UUID; selle asemel anna oma identifikaator (näiteks andmebaasi ID): see toimib sobitusvõtmena sinu andmete ja tulemuste vahel ning tagab, et päringut töödeldakse ainult üks kord.

3. samm: Edu jälgimine

Töötlemine algab kohe, kui päringud saabuvad; eraldi “käivita” sammu pole. Samal ajal tagastab GET /v1/batches/{batch_id} objekti state ja selle loendurid: num_requests (kokku), num_pending (ootel), num_success (õnnestunud), num_error (ebaõnnestunud) ja num_cancelled (tühistatud).

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

Kui num_pending langeb nullini, on kõik päringud töödeldud, olenemata sellest, kas need õnnestusid või mitte. Perioodiline pärimine on piisav: väikese testpartii puhul mõni sekund, suure partii puhul mõni minut.

4. samm: Tulemuste kättesaamine

Tulemused loetakse kasutades GET /v1/batches/{batch_id}/results, ootamata partii lõppemist: iga päring on saadaval kohe, kui see on töödeldud. Vastus on pagindeeritud: limit määrab lehe suuruse (maksimum 1000) ja tagastatud pagination_tokeni kasutatakse järgmise lehe pärimiseks; viimasel lehel on see tühi.

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

Iga tulemus kannab oma päringu batch_request_id: see võimaldab sul rekonstrueerida vastavuse sinu sisendandmete ja Groki vastuste vahel.

Töövoog praktikas

Tootmiskeskkonna torustikus tõlgitakse töövoog tavaliselt kaheks eraldiseisvaks protsessiks:

  • Esitamise protsess, mis loob partii, valmistab ette ja lisab päringud ning salvestab seejärel batch_id
  • Kättesaamise protsess, mis kontrollib perioodiliselt loendureid ja laeb tulemused alla niipea, kui need on saadaval

See eraldatus võimaldab integreerida Partii API sündmustepõhistesse arhitektuuridesse või olemasolevatesse andmetorustikesse (cron-tööd, Apache Airflow, järjekorrad).

Veakäsitlus töövoos

Partiil puudub globaalne olek “õnnestunud” või “ebaõnnestunud”: seda loed selle loendurite kaudu. Ebaõnnestunud päring suurendab num_error ja ilmub tulemustesse koos veateatega, blokeerimata teisi. Seetõttu pead uurima iga tulemust eraldi ja käsitlema tõrkeid juhtumipõhiselt.

Kaks sündmust mõjutavad kogu partiid. Esimene on tühistamine, kas sinu või xAI poolt, mis selgitab seda siis väljal cancel_by_xai_message. See juhtub eriti siis, kui JSONL-faili rida on vigane. Teine on aegumine (expire_time), mille järel tulemused pole enam kättesaadavad: lae need õigeaegselt alla.

Peamised punktid

  • Töövoog järgib järjestust: loo (nimega), lisa, jälgi, haara
  • Päringu identifikaator (batch_request_id või custom_id JSONL-is) on sinu sobitusvõti
  • Edu loetakse state loenduritelt; kõik on töödeldud, kui num_pending on null
  • Tulemused on pagindeeritud (limit, pagination_token) ja saadaval töötlemise käigus
  • Vigu käsitletakse päringute kaupa; tühistamine ja aegumine mõjutavad kogu partiid