Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Pajp sħiħ minn tarf għal tarf

Lezzjoni 7 / 12 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Ngħaqqdu l-biċċiet
  2. Pajp sħiħ f’Python
  3. Pajp pass pass b’cURL
  4. Ġestjoni tal-iżbalji fil-produzzjoni
  5. Ottimizzazzjoni tal-ispiża
  6. Punti Ewlenin

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-sdk uffiċ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 > 0 qabel 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