Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Putki päästä päähän

Oppitunti 7 / 12 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Palasten kokoaminen
  2. Täydellinen Python-putki
  3. cURL-putki vaiheittain
  4. Virheenkäsittely tuotannossa
  5. Kustannusten optimointi
  6. Keskeiset asiat

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 > 0 ennen 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