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

Luo eräajo, seuraa tilaa ja lataa tulokset

Oppitunti 3 / 16 Päivitetty 3. marraskuuta 2026 Edistynyt
Tällä sivulla
  1. JSONL-tiedostosta tuloksiin: koko elinkaari
  2. Eräajon luominen
  3. Eräajon tilat
  4. Edistymisen seuranta
  5. Tulosten lataaminen
  6. Ajojesi luettelointi ja hallinta
  7. End-to-end-työnkulku
  8. Keskeiset asiat

Päivitetty 3. marraskuuta 2026: Lisäys 3.11.: files.download palauttaa HTTP-vastauksen (httpx2.Response); lue sen sisältö metodilla .read() ennen kuin kutsut .decode():ta. Upload odottaa parametria muodossa file={"file_name": …, "content": …}. API-avainta ei enää kovakoodata.

JSONL-tiedostosta tuloksiin: koko elinkaari

JSONL-tiedostosi on valmisteltu ja ladattu, ja sinulla on file_id. Seuraava vaihe on muuttaa tämä lepäävä tiedosto käyttökelpoisiksi tuloksiksi: luo eräajo, seuraa sen etenemistä minuuttien tai tuntien aikana, ja nouda sekä täsmäytä vastaukset. Tämä oppitunti käy läpi koko Python-koodin ketjun siinä järjestyksessä, jossa kirjoitat sen.

Eräajon luominen

Luominen vaatii vain yhden kutsun. Määrität lähdetiedoston, mallin ja kohdepäätepisteen:

from mistralai.client import Mistral
import time

client = Mistral(api_key="your-api-key")

# Create the batch job
job = client.batch.jobs.create(
    input_files=[batch_file.id],   # ID of the uploaded file
    model="mistral-small-latest",
    endpoint="/v1/chat/completions",
    metadata={"project": "document-analysis", "version": "1.0"}
)

print(f"Job created: {job.id}")
print(f"Initial status: {job.status}")

Jokainen parametri ansaitsee huomion:

  • input_files – Luettelo ladatuista tiedostotunnuksista. Voit välittää useita tiedostoja samaan ajoon.
  • model – Käytettävä Mistral-malli. Yhtä eräajoa kohden vain yksi malli.
  • endpoint – Kohde-API-päätepiste (sen on vastattava JSONL-tiedostosi body-muotoa).
  • metadata – Valinnainen sanakirja mukautettuja metatietoja varten, joiden avulla järjestät ja haet ajojasi.

Yhden mallin rajoite yhtä ajoa kohden määrittää työn jakamista: jos haluat verrata kahta mallia samassa aineistossa, lähetä kaksi erillistä ajoa, jotka viittaavat samaan tiedostoon. Mitä tulee metatietoihin, ne voivat vaikuttaa merkityksettömiltä, kunnes historiassasi on kolmekymmentä ajoa; yllä oleva projekti/versio-pari antaa sinun löytää kyseenalaista dataa tuottaneen eräajon kolmessa sekunnissa.

Eräajon tilat

Eräajo liikkuu elinkaarensa aikana useiden tilojen kautta:

TilaKuvaus
QUEUEDJonossa, ei vielä käynnistynyt
RUNNINGKäsittely käynnissä
SUCCESSSuoritettu onnistuneesti
FAILEDKäsittely epäonnistui
TIMEOUT_EXCEEDEDSuorituksen aikakatkaisu ylitetty
CANCELLATION_REQUESTEDPeruutus pyydetty
CANCELLEDPeruutettu

Näistä seitsemästä tilasta neljä ovat lopullisia: SUCCESS, FAILED, TIMEOUT_EXCEEDED ja CANCELLED. Tämä ero ohjaa seurantasilmukkaa: niin kauan kuin tila ei ole tässä joukossa, ajo on edelleen käynnissä ja sinun on odotettava. CANCELLATION_REQUESTED ei erityisesti ole pysähtynyt tila, vaan siirtymätila; koodi, joka kohtelee sitä lopullisena, poistuisi silmukasta liian aikaisin.

Edistymisen seuranta

Alla oleva kyselymalli (polling) tiivistää tämän logiikan tarkasti, ja siinä on enimmäiskeston varmistus estämään unohdetun skriptin pyörimisen loputtomiin:

def wait_for_batch(client, job_id, poll_interval=10, max_wait=3600):
    """Wait for a batch job to complete using polling."""
    elapsed = 0
    terminal_states = {"SUCCESS", "FAILED", "TIMEOUT_EXCEEDED", "CANCELLED"}

    while elapsed < max_wait:
        job = client.batch.jobs.get(job_id=job_id)
        print(f"[{elapsed}s] Status: {job.status}")

        if job.status in terminal_states:
            return job

        time.sleep(poll_interval)
        elapsed += poll_interval

    raise TimeoutError(f"Job {job_id} still running after {max_wait}s")

# Usage
completed_job = wait_for_batch(client, job.id)
print(f"Final result: {completed_job.status}")

Kymmenen sekunnin väli toimii muutaman minuutin kestävälle eräajolle; yön yli pyörivälle ajolle, joka käsittelee satoja tuhansia rivejä, kasvata väli minuuttiin tai enemmän. Suurempi kyselytarkkuus ei tuo siinä lisäarvoa, vaan kerryttää vain tarpeettomia API-kutsuja.

Tulosten lataaminen

Kun tila muuttuu SUCCESS-tilaksi, ajo paljastaa output_file-tiedoston, jonka lataat ja jäsennät rivi kerrallaan:

import json

if completed_job.status == "SUCCESS":
    # Get the output file ID
    output_file_id = completed_job.output_file

    # Download the content
    result_data = client.files.download(file_id=output_file_id)

    # Parse JSONL results
    results = {}
    for line in result_data.read().decode("utf-8").strip().split("\n"):
        entry = json.loads(line)
        custom_id = entry["custom_id"]
        response = entry["response"]
        results[custom_id] = response

    # Show an example
    for cid, resp in list(results.items())[:3]:
        content = resp["body"]["choices"][0]["message"]["content"]
        print(f"\n--- {cid} ---")
        print(content[:200])

Tulostiedosto on myös JSONL-muodossa, ja jokainen rivi sisältää alkuperäisen custom_id:n sekä mallin täydellisen vastauksen. Tässä edellisen oppitunnin nimeämisvaiva tuottaa hedelmää: indeksointi custom_id:n perusteella sanakirjaan riittää täsmäyttämään vastaukset lähdedokumentteihisi riippumatta siitä, missä järjestyksessä ne palautuvat. Kolmen ensimmäisen merkinnän näyttäminen katkaistuna 200 merkkiin on hyödyllinen sanity check ennen kuin alat kirjoittaa tietokantaasi.

Ajojesi luettelointi ja hallinta

Voit suodattaa ajoluetteloa tilan perusteella, jolloin näet milloin tahansa, mitä tililläsi on todella käynnissä:

# List all currently running jobs
running_jobs = client.batch.jobs.list(status="RUNNING")
for j in running_jobs.data:
    print(f"Job {j.id} - Model: {j.model} - Created: {j.created_at}")

Ja kun ajo venyy liian pitkäksi tai huomaat kehotteessa virheen lähetyksen jälkeen, peruutus estää turhan käsittelyn maksamisen:

# Cancel a job that is taking too long
client.batch.jobs.cancel(job_id="job-abc123")

Peruutus on asynkroninen: tila siirtyy ensin arvoon CANCELLATION_REQUESTED ja sitten arvoon CANCELLED, kun pysäytys on voimassa. Älä pidä resurssia vapautuneena välittömästi kutsun paluun jälkeen.

End-to-end-työnkulku

Yhdistettynä nämä neljä vaihetta muodostavat lyhyen skriptin, jonka voit sijoittaa suoraan ajastimeen:

from mistralai.client import Mistral
import json
import os
import time

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# 1. Upload the file
with open("batch_requests.jsonl", "rb") as f:
    batch_file = client.files.upload(
        file={"file_name": "batch_requests.jsonl", "content": f},
        purpose="batch"
    )

# 2. Create the job
job = client.batch.jobs.create(
    input_files=[batch_file.id],
    model="mistral-small-latest",
    endpoint="/v1/chat/completions"
)

# 3. Wait for completion
completed = wait_for_batch(client, job.id)

# 4. Download and parse results
if completed.status == "SUCCESS":
    data = client.files.download(file_id=completed.output_file)
    for line in data.read().decode("utf-8").strip().split("\n"):
        entry = json.loads(line)
        print(f"{entry['custom_id']}: OK")
else:
    print(f"Batch failed: {completed.status}")

Uudelleenkäytä tämä runko omassa aineistossasi vain kymmenellä rivillä: validoitat koko ketjun muutamassa minuutissa ennen kuin sitoudut koko volyymiin.

Keskeiset asiat

  • Luo eräajo komennolla client.batch.jobs.create() määrittämällä tiedosto, malli ja päätepiste
  • Seitsemän mahdollista tilaa, mukaan lukien kolme lopullista: SUCCESS, FAILED, CANCELLED
  • Kysely (polling) tietyin väliajoin on standardimalli edistymisen seurantaan
  • Tulokset ovat JSONL-muodossa ja linkitetty pyyntöihin custom_id:n kautta
  • Voit luetella, tarkastella ja peruuttaa ajojasi milloin tahansa