Visiškas end-to-end vamzdynas
Šiame puslapyje
Kursas atnaujintas 2026 m. lapkričio 2 d. pagal xAI dokumentaciją: nuolaida partijoms (batch) yra 20 % tinkamiems teksto modeliams (ne 50 %), pavyzdžiai naudoja REST API ir oficialųjį
xai-sdk(client.batch.*; xAI partijų API neatitinka OpenAI formato, todėl OpenAI SDK netinka), o Responses API turi viršenybę prieš Chat Completions, kuris xAI sistemoje yra pasenusi galutinė sąsaja. Šaltiniai: Partijų API · REST nuorodos · Partijų kainodara.
Detalių surinkimas
Ankstesnėse pamokose kiekvienas žingsnis buvo nagrinėjamas atskirai. Šioje pamokoje juos sujungsime į vientisą vamzdyną – nuo duomenų paruošimo iki rezultatų apdorojimo. Pabaigoje turėsi scenarijų, kurį galėsi pritaikyti savo poreikiams.
Visas Python vamzdynas
import json
import time
from xai_sdk import Client
client = Client() # raktas nuskaitytas iš XAI_API_KEY
# --- 1 žingsnis: duomenų paruošimas ---
documents = [
{"id": f"doc-{i}", "text": f"Dokumento turinys {i}..."}
for i in range(100)
]
# --- 2 žingsnis: JSONL failo rašymas ---
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": "Apibendrinkite dviem sakiniais."},
{"role": "user", "content": doc["text"]},
],
"max_output_tokens": 200,
},
}
f.write(json.dumps(ligne, ensure_ascii=False) + "\n")
# --- 3 žingsnis: failo įkėlimas ---
with open("batch_requests.jsonl", "rb") as f:
fichier = client.files.upload(f, filename="batch_requests.jsonl")
# --- 4 žingsnis: partijos sukūrimas iš failo (dabar ji užfiksuota) ---
batch = client.batch.create(batch_name="resumes_documents", input_file_id=fichier.id)
print(f"Partija sukurta: {batch.batch_id}")
# --- 5 žingsnis: laukiama, kol apdorojimas baigsis ---
while True:
batch = client.batch.get(batch_id=batch.batch_id)
etat = batch.state
if batch.cancel_by_xai_message:
raise RuntimeError(f"Partiją atšaukė 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} užklausų apdorota")
time.sleep(300) # kas 5 minutes
# --- 6 žingsnis: rezultatų gavimas puslapis po puslapio ---
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)} rezultatai, {len(echecs)} nesėkmės")
print("Bendra kaina: $%.4f" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Svarbūs trys dalykai. Sustabdymo sąlyga reikalauja num_requests > 0, nes iš failo sukurta partija skaitoma fone: iškart po sukūrimo jos skaitikliai vis dar gali būti lygūs nuliui. Laukas cancel_by_xai_message signalizuoja apie xAI atšaukimą, pavyzdžiui, dėl neteisingos eilutės. Kaina išreiškiama tikais (ticks) – dešimta milijardąja dolerio dalimi.
Žingsnis po žingsnio cURL vamzdynas
Jei teiki pirmenybę komandų eilutei, štai cURL ekvivalentas (naudojant jq atsakymams nuskaityti):
# 1. Įkeliamas JSONL failas
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 "Failas: $FILE_ID"
# 2. Sukuriama partija iš failo
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 "Partija: $BATCH_ID"
# 3. Skaitomi skaitikliai
curl -s "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY" | jq '.state'
# 4. Gaunamas pirmasis rezultatų puslapis
curl -s "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY" > results-page-1.json
Tolesnius puslapius gauk pridėdamas &pagination_token=… su ankstesnio puslapio grąžinta reikšme.
Klaidų valdymas gamyboje
Patikimas vamzdynas išskiria tris klaidų šeimas:
Pateikimo klaidos: nepavyksta įkelti failo arba sukurti partijos. Laikinas klaidas (laiko limito viršijimas, dažnio ribojimas, serverio klaida) kartokite didėjančiu delsos intervalu: 1 s, 2 s, 4 s, 8 s.
Apdorojimo klaidos: kai kurios partijos užklausos nepavyksta. Jos atsiranda page.failed su savo pranešimu; pateik jas iš naujo, ir tik jas, naujoje partijoje.
Laiko limitai ir galiojimo pabaiga: 24 valandų langas yra orientacinis, o ne garantuotas. Negailestingas yra galiojimo laikas (expire_time): po šio momento rezultatai tampa nepasiekiami. Gauk juos pasirodžius, o ne visus kartu pačioje pabaigoje.
# Nepavykusios užklausos: identifikuokite jas pakartotiniam pateikimui naujoje partijoje
for r in echecs:
print(f"Nesėkmė: {r.batch_request_id} — {r.error_message}")
a_relancer = {r.batch_request_id for r in echecs}
Išlaidų optimizavimas
Sutaupymai kaupiasi naudojant keturis svertus. Modelio pasirinkimas yra pirmas ir toli gražu galingiausias: pagal standartinį tarifą 2026 m. lapkričio 2 d., grok-4.3 kainuoja 1,25 USD už milijoną įvesties tokenų ir 2,50 USD už išvesties, palyginti su 2 USD ir 6 USD už grok-4.7 (kai užuominos trumpesnės nei 200 000 tokenų). Klasifikacijai arba trumpam duomenų išgavimui dažnai pakanka lengvesnio modelio, o 20 % partijų nuolaida taikoma abiems. Atsakymo ilgis eina antras: max_output_tokens neleidžia mokėti už nereikalingai ilgus atsakymus – klasifikacijai pakanka kelių tokenų. Užuominos: pašalinus dešimt tokenų iš užuominos, kartojamos 50 000 kartų, sutaupoma 500 000 įvesties tokenų. Galiausiai, talpykla: xAI automatiškai talpina į atmintį identiškas užklausų pradžias, o partijų nuolaida taikoma ir iš talpyklos pateiktiems tokenams; todėl bendras instrukcijas dėkite kiekvienos užklausos pradžioje, prieš kintamąją dalį.
Svarbiausi punktai
- Visas vamzdynas apima šešis žingsnius: paruošimas, JSONL, įkėlimas, kūrimas, stebėsena, gavimas
- Partija iš failo skaitoma fone: prieš darant išvadą, kad ji baigta, palauk, kol
num_requests > 0 - Valdyk tris klaidų šeimas: pateikimo, apdorojimo, laiko limito ir galiojimo pabaigos
- Gauk ir išsaugok rezultatus jiems pasirodžius, prieš pasibaigiant
expire_time - Modelio pasirinkimas, išvesties ilgis, trumpos užuominos ir bendri priešdėliai maksimaliai padidina sutaupymus