Celoten end-to-end cevovod
Na tej strani
Posodobitev tečaja 2. novembra 2026 na podlagi dokumentacije xAI: popust za paketne obdelave znaša 20 % za upravičene besedilne modele (ne 50 %), primeri sledijo REST API-ju in uradnemu paketu
xai-sdk(client.batch.*; paketni API xAI se ne ujema s formatom OpenAI, zato paket SDK OpenAI ne deluje), API Responses pa ima prednost pred Chat Completions, ki je pri xAI zastarela končna točka. Viri: Batch API · REST Reference · Batch Pricing.
Sestavljanje koščkov
Prejšnje lekcije so obravnavale vsak korak posebej. Ta lekcija jih združi v celoten cevovod, od priprave podatkov do obdelave rezultatov. Na koncu boš dobil skripto, ki jo lahko prilagodiš svojemu primeru uporabe.
Celoten cevovod v Pythonu
import json
import time
from xai_sdk import Client
client = Client() # ključ prebran iz XAI_API_KEY
# --- 1. korak: priprava podatkov ---
documents = [
{"id": f"doc-{i}", "text": f"Vsebina dokumenta {i}..."}
for i in range(100)
]
# --- 2. korak: zapis datoteke JSONL ---
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": "Povzemi v dveh stavkih."},
{"role": "user", "content": doc["text"]},
],
"max_output_tokens": 200,
},
}
f.write(json.dumps(ligne, ensure_ascii=False) + "\n")
# --- 3. korak: prenos datoteke ---
with open("batch_requests.jsonl", "rb") as f:
fichier = client.files.upload(f, filename="batch_requests.jsonl")
# --- 4. korak: ustvarjanje paketa iz datoteke (zdaj je zaklenjen) ---
batch = client.batch.create(batch_name="resumes_documents", input_file_id=fichier.id)
print(f"Paket ustvarjen: {batch.batch_id}")
# --- 5. korak: čakanje na konec obdelave ---
while True:
batch = client.batch.get(batch_id=batch.batch_id)
etat = batch.state
if batch.cancel_by_xai_message:
raise RuntimeError(f"Paket je preklical 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} obdelanih zahtevkov")
time.sleep(300) # vsakih 5 minut
# --- 6. korak: pridobivanje rezultatov, stran za stranjo ---
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)} rezultatov, {len(echecs)} napak")
print("Skupni strošek: $%.4f" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Pomembne so tri podrobnosti. Pogoj zaustavitve zahteva num_requests > 0, ker se paket, ustvarjen iz datoteke, bere v ozadju: takoj po ustvarjanju so njegovi števci lahko še vedno ničelni. Polje cancel_by_xai_message signalizira preklic s strani xAI, na primer zaradi neveljavne vrstice. Stroški so izraženi v tikih, to je desetmilijardinkah dolarja.
Cevovod s cURL, korak za korakom
Če raje uporabljaš ukazno vrstico, je tu enakovredna različica s cURL (z uporabo jq za branje odgovorov):
# 1. Prenos datoteke JSONL
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. Ustvarjanje paketa 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 "Paket: $BATCH_ID"
# 3. Branje števcov
curl -s "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY" | jq '.state'
# 4. Pridobivanje prve strani rezultatov
curl -s "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY" > results-page-1.json
Naslednje strani dobiš z dodajanjem &pagination_token=… z vrednostjo, ki jo vrne prejšnja stran.
Obravnava napak v proizvodnem okolju
Zanesljiv cevovod razlikuje tri družine napak:
Napake pri oddaji: prenos datoteke ali ustvarjanje paketa ne uspe. Prehodne napake (časovni iztek, omejitev hitrosti, napaka strežnika) ponovi z naraščajočim zamikom: 1 s, 2 s, 4 s, 8 s.
Napake med obdelavo: nekateri zahtevki znotraj paketa ne uspejo. Pojavijo se v page.failed s svojim sporočilom; ponovno jih oddaj, in samo njih, v novem paketu.
Časovni izteki in potek veljavnosti: 24-urno okno je okvirno, ne zagotovljeno. Neusmiljen je potek veljavnosti (expire_time): po tem trenutku rezultati niso več dostopni. Pridobi jih sproti, namesto da čakaš na vse naenkrat na koncu.
# Neuspeli zahtevki: identificiraj jih za ponovno oddajo v novem paketu
for r in echecs:
print(f"Neuspeh: {r.batch_request_id} — {r.error_message}")
a_relancer = {r.batch_request_id for r in echecs}
Optimizacija stroškov
Prihranki se seštevajo prek štirih vzvodov. Izbira modela je prva in daleč najmočnejša: po standardni tarifi z dne 2. novembra 2026 grok-4.3 stane 1,25 $ na milijon vhodnih žetonov in 2,50 $ za izhodne, v nasprotju z 2 $ in 6 $ za grok-4.7 (pozivi pod 200.000 žetoni). Za klasifikacijo ali kratko ekstrakcijo pogosto zadostuje lažji model, 20-odstotni popust za paketne obdelave pa velja za oba. Nato sledi dolžina odgovora: max_output_tokens preprečuje plačevanje nepotrebno dolgih izhodov; za klasifikacijo zadostuje nekaj žetonov. Pozivi: odstranitev desetih žetonov iz poziva, ponovljenega 50.000-krat, prihrani 500.000 vhodnih žetonov. Nazadnje, predpomnilnik: xAI samodejno predpomni identične začetke zahtevkov, popust za paketne obdelave pa velja tudi za žetone, servirane iz predpomnilnika; zato skupna navodila postavi na začetek vsakega zahtevka, pred spremenljivi del.
Ključne ugotovitve
- Celoten cevovod zajema šest korakov: priprava, JSONL, prenos, ustvarjanje, nadzor, pridobivanje
- Paket iz datoteke se bere v ozadju: preden sklepaš, da je končan, počakaj, da bo
num_requests > 0 - Obravnavaj tri družine napak: oddaja, obdelava, časovni iztek in potek veljavnosti
- Rezultate pridobi in shrani sproti, preden poteče
expire_time - Izbira modela, dolžina izhoda, kratki pozivi in skupne predpone maksimirajo prihranke