Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Delovni tok v štirih korakih

Lekcija 2 od 12 Posodobljeno 2. november 2026 Razvijalec
Na tej strani
  1. Življenjski cikel paketne obdelave
  2. 1. korak: Ustvari paketno obdelavo
  3. 2. korak: Dodaj zahteve
  4. 3. korak: Spremljaj napredek
  5. 4. korak: Pridobi rezultate
  6. Delovni tok v praksi
  7. Obravnava napak v delovnem toku
  8. Ključne ugotovitve

Posodobljeno 2. novembra 2026 na podlagi dokumentacije xAI: popust za paketne obdelave znaša 20 % za ustrezne besedilne modele (ne 50 %); primeri uporabljajo REST API in uradni xai-sdk (client.batch.*; paketni API xAI ne sledi formatu OpenAI, zato paket SDK za OpenAI ni uporaben); in API Responses ima prednost pred Chat Completions, ki je pri xAI zastarela končna točka. Viri: Batch API · REST reference · Batch pricing.

Življenjski cikel paketne obdelave

Vsaka paketna obdelava sledi istemu ciklu: ustvari, dodaj zahteve, obdelaj, pridobi rezultate. Razumevanje tega cikla je ključno, preden preideš na implementacijo, saj ima vsak korak svoje omejitve in najboljše prakse.

1. korak: Ustvari paketno obdelavo

Vse se začne s klicem POST /v1/batches, ki zahteva eno obvezno polje: ime paketne obdelave. API vrne edinstven identifikator (batch_id), ki ga uporabiš za vse nadaljnje 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 vsebuje tudi datuma ustvarjanja in poteka veljavnosti paketne obdelave (create_time, expire_time) ter predmet state, katerega števci so še vedno nastavljeni na nič.

2. korak: Dodaj zahteve

Na voljo sta dve metodi:

Prek API-ja: zahteve pošlješ s klicem POST /v1/batches/{batch_id}/requests. Vsak klic prenese seznam zahtev in dodajaš jih lahko tako dolgo, dokler paketna obdelava ni preklicana. To je pot za paketne obdelave, ki jih gradiš postopoma.

Prek datoteke JSONL: pripraviš datoteko, ki vsebuje vse tvoje zahteve, jo naložiš prek API-ja Files, nato pa iz te datoteke ustvariš paketno obdelavo. Paketna obdelava je nato zaklenjena: dodajanje ni več mogoče. To je pot za velike količine podatkov, pripravljenih vnaprej.

Vsaka zahteva nosi edinstven identifikator znotraj paketne obdelave: batch_request_id v API-ju ali custom_id v datoteki JSONL. Če ga v API-ju izpustiš, xAI samodejno ustvari UUID; namesto tega dodeli svojega (npr. ID iz baze podatkov): služi kot ključ za ujemanje med tvojimi podatki in rezultati ter zagotavlja, da je zahteva obdelana le enkrat.

3. korak: Spremljaj napredek

Obdelava se začne takoj, ko prispejo zahteve; ločen korak “začni” ne obstaja. Medtem klic GET /v1/batches/{batch_id} vrne predmet state in njegove števce: num_requests (skupno), num_pending (v čakanju), num_success (uspešne), num_error (neuspešne) in num_cancelled (preklicane).

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

Ko num_pending pade na nič, so vse zahteve obdelane, uspešno ali ne. Dovolj je periodično preverjanje (polling): nekaj sekund za majhno testno paketno obdelavo, nekaj minut za veliko paketno obdelavo.

4. korak: Pridobi rezultate

Rezultate bereš s klicem GET /v1/batches/{batch_id}/results, brez čakanja, da se paketna obdelava konča: vsaka zahteva je na voljo takoj, ko je obdelana. Odgovor je paginiran: limit določa velikost strani (največ 1.000), vrnjeni pagination_token pa se uporabi za zahtevo naslednje strani; na zadnji strani je prazen.

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

Vsak rezultat nosi batch_request_id svoje zahteve: to ti omogoča rekonstrukcijo preslikave med tvojimi vhodnimi podatki in odgovori modela Grok.

Delovni tok v praksi

V produkcijskem okolju se delovni tok običajno prevede v dva ločena procesa:

  • Proces predložitve, ki ustvari paketno obdelavo, pripravi in doda zahteve ter shrani batch_id
  • Proces pridobivanja, ki periodično preverja števce in prenaša rezultate, ko postanejo na voljo

Ta ločitev ti omogoča integracijo paketnega API-ja v arhitekture, gonjene z dogodki, ali v obstoječe podatkovne cevovode (opravila cron, Apache Airflow, čakalne vrste).

Obravnava napak v delovnem toku

Paketna obdelava nima globalnega stanja “uspešno” ali “neuspešno”: stanje razbereš prek njenih števcov. Neuspešna zahteva poveča num_error in se pojavi v rezultatih s svojim sporočilom o napaki, ne da bi blokirala druge. Zato moraš pregledati vsak rezultat posebej in obravnavati napake primer za primerom.

Dva dogodka vplivata na celotno paketno obdelavo. Prvi je preklic, ki ga izvedeš ti ali xAI, kar je nato pojasnjeno v polju cancel_by_xai_message. Do tega pride zlasti, ko je vrstica v datoteki JSONL neveljavna. Drugi dogodek je potek veljavnosti (expire_time), po katerem rezultati niso več dostopni: zato jih pravočasno pridobi.

Ključne ugotovitve

  • Delovni tok sledi zaporedju: ustvari (z imenom), dodaj, spremljaj, pridobi
  • Identifikator zahteve (batch_request_id ali custom_id v JSONL) je tvoj ključ za ujemanje
  • Napredek se bere iz števcov v predmetu state; vse je obdelano, ko je num_pending enak nič
  • Rezultati so paginirani (limit, pagination_token) in na voljo sproti, ko so obdelani
  • Napake se obravnavajo zahteva za zahtevo; preklic in potek veljavnosti vplivata na celotno paketno obdelavo