Delovni tok v štirih korakih
Na tej strani
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_idalicustom_idv JSONL) je tvoj ključ za ujemanje - Napredek se bere iz števcov v predmetu
state; vse je obdelano, ko jenum_pendingenak 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