Putki päästä päähän
Tällä sivulla
Kurssi päivitetty 2. marraskuuta 2026 xAI:n dokumentaation perusteella: alennus eräajosta on 20 % tukikelpoisissa tekstimalleissa (ei 50 %), esimerkit noudattavat REST API:a ja virallista
xai-sdk:ää (client.batch.*; xAI:n erä-API ei vastaa OpenAI:n muotoa, joten OpenAI SDK ei toimi), ja Responses API on ensisijainen Chat Completionsin sijaan, joka on xAI:lla vanhentunut päätepiste. Lähteet: Batch API · REST Reference · Batch Pricing.
Palasten kokoaminen
Aiemmissa tunneissa käsiteltiin jokaista vaihetta erillään. Tässä tunnissa koostat niistä kokonaisen putken datan valmistelusta tulosten käsittelyyn. Lopputuloksena on skripti, jonka voit mukauttaa omaan käyttötarkoitukseesi.
Täydellinen Python-putki
import json
import time
from xai_sdk import Client
client = Client() # avain luetaan XAI_API_KEY-ympäristömuuttujasta
# --- Vaihe 1: valmista data ---
documents = [
{"id": f"doc-{i}", "text": f"Dokumentin sisältö {i}..."}
for i in range(100)
]
# --- Vaihe 2: kirjoita JSONL-tiedosto ---
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": "Tee yhteenveto kahdella lauseella."},
{"role": "user", "content": doc["text"]},
],
"max_output_tokens": 200,
},
}
f.write(json.dumps(ligne, ensure_ascii=False) + "\n")
# --- Vaihe 3: lähetä tiedosto ---
with open("batch_requests.jsonl", "rb") as f:
fichier = client.files.upload(f, filename="batch_requests.jsonl")
# --- Vaihe 4: luo erä tiedostosta (se on nyt lukittu) ---
batch = client.batch.create(batch_name="resumes_documents", input_file_id=fichier.id)
print(f"Erä luotu: {batch.batch_id}")
# --- Vaihe 5: odota käsittelyn valmistumista ---
while True:
batch = client.batch.get(batch_id=batch.batch_id)
etat = batch.state
if batch.cancel_by_xai_message:
raise RuntimeError(f"xAI peruutti erän: {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} pyyntöä käsitelty")
time.sleep(300) # joka 5. minuutti
# --- Vaihe 6: nouda tulokset sivu kerrallaan ---
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)} tulosta, {len(echecs)} epäonnistumista")
print("Kokonaiskustannus: $%.4f" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Kolme yksityiskohtaa on erityisen tärkeitä. Pysäytysehto vaatii num_requests > 0, koska tiedostosta luettu erä luetaan taustalla: heti luonnin jälkeen sen laskurit voivat olla vielä nollia. Kenttä cancel_by_xai_message ilmoittaa xAI:n tekemästä peruutuksesta, esimerkiksi virheellisen rivin vuoksi. Kustannus ilmaistaan tickeinä, jotka ovat dollarin kymmenenmiljardisosa.
cURL-putki vaiheittain
Jos suosit komentoriviä, tässä on cURL-vastaavuus (käyttäen jq:ta vastausten lukemiseen):
# 1. Lähetä JSONL-tiedosto
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 "Tiedosto: $FILE_ID"
# 2. Luo erä tiedostosta
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 "Erä: $BATCH_ID"
# 3. Lue laskurit
curl -s "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY" | jq '.state'
# 4. Nouda ensimmäinen sivu tuloksista
curl -s "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY" > results-page-1.json
Hae seuraavat sivut lisäämällä &pagination_token=… edelliseltä sivulta palautetulla arvolla.
Virheenkäsittely tuotannossa
Vankka putki erottaa kolme virheryhmää:
Lähetysvirheet: tiedoston lähetys tai erän luonti epäonnistuu. Yritä uudelleen ohimeneviä virheitä (aikakatkaisu, nopeusrajoitus, palvelinvirhe) kasvavalla viiveellä: 1 s, 2 s, 4 s, 8 s.
Käsittelyvirheet: jotkin pyynnöt epäonnistuvat erän sisällä. Ne näkyvät kohdassa page.failed viesteineen; lähetä ne uudelleen, ja vain ne, uudessa erässä.
Aikakatkaisut ja vanheneminen: 24 tunnin ikkuna on suuntaa antava, ei takuu. Armoton raja on vanheneminen (expire_time): tämän jälkeen tuloksia ei voi enää käyttää. Nouda ne sitä mukaa kun ne valmistuvat äläkä kaikki kerralla lopussa.
# Epäonnistuneet pyynnöt: tunnista ne uudelleenlähetykseen uudessa erässä
for r in echecs:
print(f"Epäonnistuminen: {r.batch_request_id} — {r.error_message}")
a_relancer = {r.batch_request_id for r in echecs}
Kustannusten optimointi
Säästöt kertyvät neljän vivun kautta. Mallin valinta on ensimmäinen ja ylivoimaisesti tehokkain: 2. marraskuuta 2026 normaalihinnalla grok-4.3 maksaa 1,25 $ miljoonalta syöttetokeniltä ja 2,50 $ tulostetokeniltä, kun taas grok-4.7 maksaa 2 $ ja 6 $ (kehotteet alle 200 000 tokenia). Luokitteluun tai lyhyeen tiedonpoimintaan kevyempi malli riittää usein, ja 20 %:n eräalennus koskee molempia. Vastauksen pituus on seuraava: max_output_tokens estää maksamasta tarpeettoman pitkistä tulosteista; luokitteluun riittää muutama token. Kehotteet: kymmenen tokenin poistaminen kehotteesta, toistettuna 50 000 kertaa, säästää 500 000 syöttetokeniä. Lopuksi välimuisti: xAI välimuistaa automaattisesti pyyntöjen identtiset alut, ja eräalennus koskee myös välimuistista haettuja tokeneita; sijoita siis yhteiset ohjeet jokaisen pyynnön alkuun ennen muuttuvaa osaa.
Keskeiset asiat
- Täydellinen putki kattaa kuusi vaihetta: valmistelu, JSONL, lähetys, luonti, seuranta, nouto
- Tiedostosta luettu erä luetaan taustalla: odota arvoa
num_requests > 0ennen kuin päättelet sen valmistuneen - Käsittele kolme virheryhmää: lähetys, käsittely, aikakatkaisu ja vanheneminen
- Nouda ja tallenna tulokset sitä mukaa kun ne saapuvat, ennen
expire_time-rajaa - Mallin valinta, tulosteen pituus, lyhyet kehotteet ja yhteiset etuliitteet maksimoivat säästöt