Pajp sħiħ minn tarf għal tarf
F'din il-paġna
Kors aġġornat fit-2 ta’ Novembru 2026 abbażi tad-dokumentazzjoni ta’ xAI: l-iskont tal-batch huwa 20% fuq mudelli tat-test eliġibbli (mhux 50%), l-eżempji jsegwu l-API REST u l-
xai-sdkuffiċjali (client.batch.*; l-API tal-Batch ta’ xAI ma taqbilx mal-format ta’ OpenAI, allura l-SDK ta’ OpenAI ma japplikax), u l-API tar-Risposti tieħu preċedenza fuq Chat Completions, endpoint antikwat f’xAI. Sorsi: Batch API · REST Reference · Batch Pricing.
Ngħaqqdu l-biċċiet
Il-lezzjonijiet preċedenti koprew kull pass b’mod iżolat. Din il-lezzjoni tgħaqqadhom f’pajp sħiħ, mit-tħejjija tad-data sal-ipproċessar tar-riżultati. Fl-aħħar ikollok skript li tista’ tadatta għall-każ ta’ użu tiegħek.
Pajp sħiħ f’Python
import json
import time
from xai_sdk import Client
client = Client() # iċ-ċavetta tinqara minn XAI_API_KEY
# --- Pass 1: tħejjija tad-data ---
documents = [
{"id": f"doc-{i}", "text": f"Kontenut tad-dokument {i}..."}
for i in range(100)
]
# --- Pass 2: kitba tal-fajl 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": "Agħmel sommarju f'żewġ sentenzi."},
{"role": "user", "content": doc["text"]},
],
"max_output_tokens": 200,
},
}
f.write(json.dumps(ligne, ensure_ascii=False) + "\n")
# --- Pass 3: ittella' l-fajl ---
with open("batch_requests.jsonl", "rb") as f:
fichier = client.files.upload(f, filename="batch_requests.jsonl")
# --- Pass 4: oħloq il-batch mill-fajl (issa huwa ssillat) ---
batch = client.batch.create(batch_name="resumes_documents", input_file_id=fichier.id)
print(f"Batch maħluq: {batch.batch_id}")
# --- Pass 5: stenna sakemm jintemm l-ipproċessar ---
while True:
batch = client.batch.get(batch_id=batch.batch_id)
etat = batch.state
if batch.cancel_by_xai_message:
raise RuntimeError(f"Batch ikkanċellat minn 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} talbiet ipproċessati")
time.sleep(300) # kull 5 minuti
# --- Pass 6: irkupra r-riżultati, paġna b'paġna ---
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)} riżultati, {len(echecs)} fallimenti")
print("Spiża totali: $%.4f" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Hemm tliet dettalji importanti. Il-kundizzjoni ta’ waqfien teħtieġ num_requests > 0 għax batch maħluq minn fajl jinqara fl-isfond: eżatt wara l-ħolqien, il-kontituri tiegħu jistgħu jkunu għadhom żero kollha. Il-kamp cancel_by_xai_message jindika kanċellazzjoni minn xAI, pereżempju minħabba linja mhux valida. U l-ispiża hija espressa f’ticks, għaxra biljun parti ta’ dollaru.
Pajp pass pass b’cURL
Jekk tippreferi l-linja tal-kmand, hawnhekk hemm l-ekwivalenti b’cURL (tuża jq biex taqra r-risposti):
# 1. Ittella' l-fajl 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 "Fajl: $FILE_ID"
# 2. Oħloq il-batch mill-fajl
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. Aqra l-kontituri
curl -s "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY" | jq '.state'
# 4. Irkupra l-ewwel paġna tar-riżultati
curl -s "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY" > results-page-1.json
Ikseb il-paġni sussegwenti billi żżid &pagination_token=… bil-valur irritornat mill-paġna ta’ qabel.
Ġestjoni tal-iżbalji fil-produzzjoni
Pajp robust jagħmel distinzjoni bejn tliet familji ta’ żbalji:
Żbalji ta’ sottomissjoni: it-tlugħ tal-fajl jew il-ħolqien tal-batch ifalli. Erġa’ pprova għal żbalji tranżitorji (time-out, limitu ta’ rata, żball tas-server) b’dewmien li jiżdied: 1 s, 2 s, 4 s, 8 s.
Żbalji ta’ ipproċessar: xi talbati jfallu fil-batch. Dawn jidhru f’page.failed bil-messaġġ tagħhom; erġa’ ibgħathom, u biss lilhom, f’batch ġdid.
Time-out u skadenza: it-tieqa ta’ 24 siegħa hija indikattiva, mhux garantita. Dak li ma jaħfirx huwa l-iskadenza (expire_time): wara dan il-punt, ir-riżultati ma jkunux aċċessibbli aktar. Irkuprahom hekk kif jaslu minflok kollha fl-aħħar.
# Talbati falluti: identifika biex terġa' tibgħathom f'batch ġdid
for r in echecs:
print(f"Falliment: {r.batch_request_id} — {r.error_message}")
a_relancer = {r.batch_request_id for r in echecs}
Ottimizzazzjoni tal-ispiża
L-iffrankar jakkumula fuq erba’ lievi. L-għażla tal-mudell tiġi l-ewwel, bil-bosta l-aktar qawwija: bir-rata standard tat-2 ta’ Novembru 2026, grok-4.3 jiswa $1.25 għal kull miljun token tal-input u $2.50 għall-output, meta mqabbel ma’ $2 u $6 għal grok-4.7 (prompts taħt 200,000 token). Għall-klassifikazzjoni jew estrazzjoni qasira, il-mudell eħfef spiss ikun biżżejjed, u l-iskont tal-batch ta’ 20% japplika għat-tnejn. It-tul tar-risposta jiġi wara: max_output_tokens jipprevjeni li tħallas għal outputs twal mingħajr bżonn—għall-klassifikazzjoni, ftit tokens biżżejjed. Prompts: li tneħħi għaxar tokens minn prompt ripetut 50,000 darba tiffranka 500,000 token tal-input. Fl-aħħar, il-cache: xAI awtomatikament jikkaxkja (cache) biduiet identiċi tat-talbiet, u l-iskont tal-batch japplika wkoll għat-tokens moqdija mill-cache; allura poġġi struzzjonijiet komuni fil-bidu ta’ kull talba, qabel il-parti li tinbidel.
Punti Ewlenin
- Pajp sħiħ ikopri sitt passi: tħejjija, JSONL, tlugħ, ħolqien, monitoraġġ, rkupru
- Batch minn fajl jinqara fl-isfond: stenna għal
num_requests > 0qabel ma tikkonkludi li ntemm - Immaniġġja t-tliet familji ta’ żbalji: sottomissjoni, ipproċessar, time-out u skadenza
- Irkupra u salva r-riżultati hekk kif jaslu, qabel
expire_time - L-għażla tal-mudell, it-tul tal-output, prompts qosra, u prefissi komuni jimmassimizzaw l-iffrankar