Cjeloviti end-to-end pipeline
Na ovoj stranici
Tečaj ažuriran 2. studenoga 2026. na temelju dokumentacije xAI-ja: popust za batch iznosi 20 % na kvalificirane tekstualne modele (ne 50 %), primjeri slijede REST API i službeni
xai-sdk(client.batch.*; Batch API xAI-ja ne odgovara formatu OpenAI-ja, stoga se OpenAI SDK ne primjenjuje), a Responses API ima prednost nad Chat Completions, koji je kod xAI-ja zastarjela krajnja točka. Izvori: Batch API · REST referenca · Cjenik za batch.
Sastavljanje cjeline
Prethodne lekcije obrađivale su svaki korak zasebno. Ova lekcija spaja ih u cjeloviti pipeline, od pripreme podataka do obrade rezultata. Na kraju ćeš imati skriptu koju možeš prilagoditi svom slučaju upotrebe.
Cjeloviti Python pipeline
import json
import time
from xai_sdk import Client
client = Client() # ključ se čita iz XAI_API_KEY
# --- Korak 1: priprema podataka ---
documents = [
{"id": f"doc-{i}", "text": f"Sadržaj dokumenta {i}..."}
for i in range(100)
]
# --- Korak 2: zapisivanje JSONL datoteke ---
with open("batch_requests.jsonl", "w", encoding="utf-8") as f:
for doc in documents:
ligne = {
"custom_id": doc["id"],
"method": "POST",
"url": "/v1/responses",
"body": {
"model": "grok-4.3",
"input": [
{"role": "system", "content": "Sažmi u dvije rečenice."},
{"role": "user", "content": doc["text"]},
],
"max_output_tokens": 200,
},
}
f.write(json.dumps(ligne, ensure_ascii=False) + "\n")
# --- Korak 3: učitavanje datoteke ---
with open("batch_requests.jsonl", "rb") as f:
fichier = client.files.upload(f, filename="batch_requests.jsonl")
# --- Korak 4: stvaranje batcha iz datoteke (sada je zapečaćena) ---
batch = client.batch.create(batch_name="resumes_documents", input_file_id=fichier.id)
print(f"Batch stvoren: {batch.batch_id}")
# --- Korak 5: čekanje završetka obrade ---
while True:
batch = client.batch.get(batch_id=batch.batch_id)
etat = batch.state
if batch.cancel_by_xai_message:
raise RuntimeError(f"Batch otkazao xAI: {batch.cancel_by_xai_message}")
if etat.num_requests > 0 and etat.num_pending == 0:
break
print(f"{etat.num_success + etat.num_error}/{etat.num_requests} obrađenih zahtjeva")
time.sleep(300) # svakih 5 minuta
# --- Korak 6: dohvaćanje rezultata, stranica po stranica ---
resultats, echecs = {}, []
jeton = None
while True:
page = client.batch.list_batch_results(
batch_id=batch.batch_id, limit=100, pagination_token=jeton
)
for r in page.succeeded:
resultats[r.batch_request_id] = r.response.content
echecs.extend(page.failed)
if page.pagination_token is None:
break
jeton = page.pagination_token
with open("batch_results.json", "w", encoding="utf-8") as f:
json.dump(resultats, f, ensure_ascii=False, indent=2)
print(f"{len(resultats)} rezultata, {len(echecs)} neuspjeha")
print("Ukupni trošak: $%.4f" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Tri su detalja ključna. Uvjet zaustavljanja zahtijeva num_requests > 0 jer se batch stvoren iz datoteke čita u pozadini: odmah nakon stvaranja, njegovi brojači mogu još uvijek biti nula. Polje cancel_by_xai_message signalizira otkazivanje od strane xAI-ja, primjerice zbog neispravnog retka. Trošak je izražen u tickovima, deset-milijarditim dijelovima dolara.
cURL pipeline korak po korak
Ako više voliš naredbeni redak, evo ekvivalenta u cURL-u (koristeći jq za čitanje odgovora):
# 1. Učitavanje JSONL datoteke
FILE_ID=$(curl -s -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F file="@batch_requests.jsonl" | jq -r '.id')
echo "Datoteka: $FILE_ID"
# 2. Stvaranje batcha iz datoteke
BATCH_ID=$(curl -s -X POST https://api.x.ai/v1/batches \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"name\": \"resumes_documents\", \"input_file_id\": \"$FILE_ID\"}" | jq -r '.batch_id')
echo "Batch: $BATCH_ID"
# 3. Čitanje brojača
curl -s "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY" | jq '.state'
# 4. Dohvaćanje prve stranice rezultata
curl -s "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY" > results-page-1.json
Naredne stranice dohvaćaš dodavanjem &pagination_token=… s vrijednošću koju vraća prethodna stranica.
Rukovanje greškama u produkciji
Robustan pipeline razlikuje tri obitelji grešaka:
Greške pri podnošenju: učitavanje datoteke ili stvaranje batcha ne uspije. Prolazne greške (istek vremena, ograničenje stope, greška poslužitelja) ponovi s rastućim kašnjenjem: 1 s, 2 s, 4 s, 8 s.
Greške u obradi: neki zahtjevi unutar batcha ne uspiju. Pojavljuju se u page.failed sa svojom porukom; ponovno ih podnesi, i samo njih, u novom batchu.
Istek vremena i istek valjanosti: prozor od 24 sata je indikativan, a ne zajamčen. Ono što je nemilosrdno jest istek valjanosti (expire_time): nakon tog trenutka rezultati više nisu dostupni. Dohvati ih kako pristižu, umjesto svih odjednom na kraju.
# Neuspjeli zahtjevi: identificiraj ih za ponovno podnošenje u novom batchu
for r in echecs:
print(f"Neuspjeh: {r.batch_request_id} — {r.error_message}")
a_relancer = {r.batch_request_id for r in echecs}
Optimizacija troškova
Uštede se akumuliraju kroz četiri poluge. Izbor modela je prva i daleko najmoćnija: po standardnoj tarifi od 2. studenoga 2026., grok-4.3 košta 1,25 USD po milijunu ulaznih tokena i 2,50 USD za izlazne, naspram 2 USD i 6 USD za grok-4.7 (prompti ispod 200.000 tokena). Za klasifikaciju ili kratku ekstrakciju, lakši model često suffice, a popust od 20 % za batch vrijedi za oba. Duljina odgovora je sljedeća: max_output_tokens sprječava plaćanje nepotrebno dugih izlaza—za klasifikaciju je dovoljno nekoliko tokena. Prompti: uklanjanje deset tokena iz prompta koji se ponavlja 50.000 puta štedi 500.000 ulaznih tokena. Konačno, predmemorija (cache): xAI automatski predmemorira identične početke zahtjeva, a popust za batch vrijedi i za tokene poslužene iz predmemorije; stoga zajedničke upute stavi na početak svakog zahtjeva, prije varijabilnog dijela.
Ključne točke
- Cjeloviti pipeline obuhvaća šest koraka: priprema, JSONL, učitavanje, stvaranje, nadzor, dohvaćanje
- Batch iz datoteke čita se u pozadini: pričekaj
num_requests > 0prije zaključka da je završen - Rukuj s tri obitelji grešaka: podnošenje, obrada, istek vremena i valjanosti
- Dohvati i spremi rezultate kako pristižu, prije
expire_time - Izbor modela, duljina izlaza, kratki prompti i zajednički prefiksi maksimiziraju uštede