Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Radni tijek u četiri koraka

Lekcija 2 od 12 Ažurirano 2. studenoga 2026. Programer
Na ovoj stranici
  1. Životni ciklus skupnog zahtjeva
  2. Korak 1: Stvaranje skupnog zahtjeva
  3. Korak 2: Dodavanje zahtjeva
  4. Korak 3: Praćenje napretka
  5. Korak 4: Dohvaćanje rezultata
  6. Radni tijek u praksi
  7. Rukovanje greškama u radnom tijeku
  8. Ključne točke

Ažurirano 2. studenoga 2026. na temelju dokumentacije xAI-ja: popust za skupne zahtjeve iznosi 20 % na odgovarajuće tekstualne modele (ne 50 %); primjeri koriste REST API i službeni xai-sdk (client.batch.*; Batch API xAI-ja ne slijedi format OpenAI-ja, stoga se SDK OpenAI-ja ne primjenjuje); a Responses API ima prednost nad Chat Completionsom, koji je kod xAI-ja zastarjela krajnja točka. Izvori: Batch API · REST referenca · Cjenik za skupne zahtjeve.

Životni ciklus skupnog zahtjeva

Svaki skupni zahtjev prolazi kroz isti ciklus: stvaranje, dodavanje zahtjeva, obrada i dohvaćanje rezultata. Razumijevanje ovog ciklusa ključno je prije nego što prijeđeš na implementaciju jer svaki korak ima svoja ograničenja i najbolje prakse.

Korak 1: Stvaranje skupnog zahtjeva

Sve počinje pozivom POST /v1/batches s jednim obaveznim poljem: nazivom skupnog zahtjeva. API vraća jedinstveni identifikator (batch_id) koji koristiš za sve naknadne operacije.

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

Odgovor također sadrži datume stvaranja i isteka skupnog zahtjeva (create_time, expire_time) te objekt state čiji su brojači još uvijek na nuli.

Korak 2: Dodavanje zahtjeva

Postoje dvije metode:

Kroz API: zahtjeve šalješ pomoću POST /v1/batches/{batch_id}/requests. Svaki poziv nosi popis zahtjeva i možeš ih nastaviti dodavati sve dok skupni zahtjev nije otkazan. Ovo je put za skupne zahtjeve koji se grade postupno.

Kroz JSONL datoteku: pripremiš datoteku koja sadrži sve tvoje zahtjeve, učitaš je putem Files API-ja, a zatim stvoriš skupni zahtjev iz te datoteke. Skupni zahtjev tada postaje zapečaćen: daljnja dodavanja nisu moguća. Ovo je put za velike količine podataka pripremljene unaprijed.

Svaki zahtjev nosi jedinstveni identifikator unutar skupnog zahtjeva: batch_request_id u API-ju ili custom_id u JSONL datoteci. Ako ga izostaviš u API-ju, xAI generira UUID; umjesto toga navedi svoj vlastiti (npr. ID iz baze podataka): on služi kao ključ za povezivanje tvojih podataka i rezultata te jamči da se zahtjev obrađuje samo jednom.

Korak 3: Praćenje napretka

Obrada počinje čim stignu zahtjevi; ne postoji korak „pokretanja“. U međuvremenu, GET /v1/batches/{batch_id} vraća objekt state i njegove brojače: num_requests (ukupno), num_pending (na čekanju), num_success (uspješni), num_error (neuspjeli) i num_cancelled (otkazani).

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

Kada num_pending padne na nulu, svi su zahtjevi obrađeni, uspješno ili ne. Periodično ispitivanje (polling) je dovoljno: nekoliko sekundi za mali testni skupni zahtjev, nekoliko minuta za veliki.

Korak 4: Dohvaćanje rezultata

Rezultati se čitaju pomoću GET /v1/batches/{batch_id}/results, bez čekanja da skupni zahtjev završi: svaki je zahtjev dostupan čim bude obrađen. Odgovor je straniciiran: limit postavlja veličinu stranice (maksimalno 1000), a vraćeni pagination_token koristi se za zahtijevanje sljedeće stranice; na posljednjoj je stranici prazan.

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

Svaki rezultat nosi batch_request_id svog zahtjeva: to ti omogućuje rekonstrukciju mapiranja između tvojih ulaznih podataka i odgovora Groka.

Radni tijek u praksi

U produkcijskom cjevovodu radni se tijek obično prevodi u dva odvojena procesa:

  • Proces slanja koji stvara skupni zahtjev, priprema i dodaje zahtjeve, a zatim pohranjuje batch_id
  • Proces dohvaćanja koji periodički provjerava brojače i preuzima rezultate čim postanu dostupni

Ova odvojenost omogućuje ti integraciju Batch API-ja u arhitekture vođene događajima ili postojeće cjevovode podataka (cron zadaci, Apache Airflow, redovi čekanja).

Rukovanje greškama u radnom tijeku

Skupni zahtjev nema globalno stanje „uspješno“ ili „neuspješno“: čitaš ga kroz svoje brojače. Neuspjeli zahtjev povećava num_error i pojavljuje se u rezultatima sa svojom porukom o grešci, bez blokiranja ostalih. Stoga moraš ispitati svaki rezultat i rukovati neuspjesima slučaj po slučaj.

Dva događaja utječu na cijeli skupni zahtjev. Prvi je otkazivanje, od tvoje strane ili od strane xAI-ja, koji to zatim objašnjava u polju cancel_by_xai_message. To se događa posebno kada je redak u JSONL datoteci neispravan. Drugi je istek (expire_time), nakon kojeg rezultati više nisu dostupni: preuzmi ih pravodobno.

Ključne točke

  • Radni tijek slijedi redoslijed: stvori (s nazivom), dodaj, prati, preuzmi
  • Identifikator zahtjeva (batch_request_id ili custom_id u JSONL-u) tvoj je ključ za povezivanje
  • Napredak se očituje iz brojača u state; sve je obrađeno kada je num_pending jednak nuli
  • Rezultati su straniciirani (limit, pagination_token) i dostupni čim budu obrađeni
  • Greške se rješavaju zahtjev po zahtjev; otkazivanje i istek utječu na cijeli skupni zahtjev