Batch feladat létrehozása, állapotának nyomon követése és az eredmények letöltése
Ezen az oldalon
Frissítve: 2026. november 3.: Kiegészítés november 3-ra: a
files.downloadegy HTTP-választ (httpx2.Response) ad vissza; olvasd el a tartalmát a.read()metódussal, mielőtt meghívnád a.decode()-ot. A feltöltés (upload) a következő formátumot várja:file={"file_name": …, "content": …}. Az API-kulcs már nincs beégetve a kódba.
JSONL fájltól az eredményekig: A teljes életciklus
A JSONL fájlod előkészítve és feltöltve, a file_id pedig a kezedben van. A következő lépés ennek a szunnyadó fájlnak az átalakítása használható eredményekké: hozd létre a batch feladatot, kövesd nyomon a haladását a percekig vagy órákig tartó feldolgozás alatt, majd kérd le és egyeztesd a válaszokat. Ez a lecke végigvezet a teljes Python kódon pontosan abban a sorrendben, ahogy megírod majd.
Batch feladat létrehozása
A létrehozáshoz egyetlen hívás szükséges. Megadod a forrásfájlt, a modellt és a cél végpontot:
from mistralai.client import Mistral
import time
client = Mistral(api_key="your-api-key")
# Batch feladat létrehozása
job = client.batch.jobs.create(
input_files=[batch_file.id], # A feltöltött fájl azonosítója
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}")
Minden paraméter megérdemel egy megjegyzést:
input_files– A feltöltött fájlazonosítók listája. Több fájlt is átadhatsz egyetlen feladatnak.model– A használandó Mistral modell. Batch feladatonként csak egy modell használható.endpoint– A cél API-végpont (meg kell egyeznie a JSONL-ben lévőbodyformátumával).metadata– Egy opcionális szótár egyedi metaadatokkal, amelyekkel rendszerezheted és később visszakeresheted a feladataidat.
A feladatonkénti egy-modell korlátozás meghatározza, hogyan oszd szét a munkát: ha két modellt akarsz összehasonlítani ugyanazon a korpuszon, küldj be két különálló feladatot, amelyek ugyanarra a fájlra mutatnak. Ami a metaadatokat illeti, jelentéktelennek tűnhet mindaddig, amíg nincs harminc feladat a történetedben; a fenti projekt/verzió párosítás ekkor lehetővé teszi, hogy három másodperc alatt megtaláld azt a batchot, amelyik kérdőjeles adatokat produkált.
Batch feladat állapotai
Egy batch feladat több állapoton megy keresztül az életciklusa során:
| Állapot | Leírás |
|---|---|
QUEUED | Sorba állítva, még nem indult el |
RUNNING | Feldolgozás folyamatban |
SUCCESS | Sikeresen befejeződött |
FAILED | A feldolgozás meghiúsult |
TIMEOUT_EXCEEDED | A végrehajtási időtúllépés megtörtént |
CANCELLATION_REQUESTED | Megszakítás kérve |
CANCELLED | Megszakítva |
Ebből a hét állapotból négy végleges (terminális): SUCCESS, FAILED, TIMEOUT_EXCEEDED és CANCELLED. Ez a megkülönböztetés vezérli a figyelő ciklust: amíg az állapot nincs ebben a halmazban, a feladat még él, és várnod kell. A CANCELLATION_REQUESTED különösen nem egy leállt állapot, hanem egy átmeneti; az a kód, amely ezt véglegesnek kezeli, túl korán lépne ki a ciklusból.
Haladás nyomon követése
Az alábbi polling (szavazgatás) minta pontosan ezt a logikát zárja magába, egy maximális időtartamú biztonsági korláttal, hogy megakadályozza egy elfelejtett script végtelen futását:
def wait_for_batch(client, job_id, poll_interval=10, max_wait=3600):
"""Várakozás egy batch feladat befejeződésére polling segítségével."""
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")
# Használat
completed_job = wait_for_batch(client, job.id)
print(f"Final result: {completed_job.status}")
Egy néhány percig tartó batch esetén a tíz másodperces időköz működik; egy éjszakai futtatásnál, amely több százezer sort dolgoz fel, növeld ezt egy percre vagy többre. A nagyobb pontosságú lekérdezés itt nem ad hozzá értéket, csak felesleges API-hívásokat halmoz fel.
Eredmények letöltése
Amint az állapot eléri a SUCCESS értéket, a feladat elérhetővé tesz egy output_file-t, amelyet letölthetsz és soronként elemezhetsz:
import json
if completed_job.status == "SUCCESS":
# Az kimeneti fájl azonosítójának lekérése
output_file_id = completed_job.output_file
# Tartalom letöltése
result_data = client.files.download(file_id=output_file_id)
# JSONL eredmények parszolása
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
# Példa megjelenítése
for cid, resp in list(results.items())[:3]:
content = resp["body"]["choices"][0]["message"]["content"]
print(f"\n--- {cid} ---")
print(content[:200])
Az eredményfájl szintén JSONL formátumú, és minden sor tartalmazza az eredeti custom_id-t a modell teljes válasza mellett. Itt térül meg az előző leckéből származó elnevezési erőfeszítés: a custom_id szerinti indexelés egy szótárban elegendő ahhoz, hogy egyeztesd a válaszokat a forrásdokumentumaiddal, függetlenül attól, milyen sorrendben érkeznek vissza. Az első három bejegyzés megjelenítése 200 karakterre csonkítva hasznos sanity check (józan ész ellenőrzés), mielőtt elkezdenél írni az adatbázisodba.
Feladatok listázása és kezelése
Szűrhetsz a feladatlistán állapot szerint, így bármely pillanatban láthatod, mi fut éppen a fiókodon:
# Az összes jelenleg futó feladat listázása
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}")
És amikor egy feladat elhúzódik, vagy beküldés után hibát veszel észre a promptban, a megszakítás elkerüli a haszontalan feldolgozás kifizetését:
# Egy túl sokáig tartó feladat megszakítása
client.batch.jobs.cancel(job_id="job-abc123")
A megszakítás aszinkron: az állapot először CANCELLATION_REQUESTED-re vált, majd CANCELLED-re, amint a leállítás生效 (hatályba lép). Ne tekintsd az erőforrást azonnal felszabadultnak a hívás visszatérésekor.
End-to-end munkafolyamat
Összeállítva ez a négy lépés egy rövid scriptet alkot, amelyet közvetlenül ütemezőbe (scheduler) tehetsz:
from mistralai.client import Mistral
import json
import os
import time
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# 1. Fájl feltöltése
with open("batch_requests.jsonl", "rb") as f:
batch_file = client.files.upload(
file={"file_name": "batch_requests.jsonl", "content": f},
purpose="batch"
)
# 2. Feladat létrehozása
job = client.batch.jobs.create(
input_files=[batch_file.id],
model="mistral-small-latest",
endpoint="/v1/chat/completions"
)
# 3. Várakozás a befejezésre
completed = wait_for_batch(client, job.id)
# 4. Eredmények letöltése és parszolása
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}")
Használd újra ezt a vázat a saját korpuszodon mindössze tíz sorral: néhány perc alatt validálhatod az egész láncot, mielőtt ráállnál a teljes mennyiségre.
Főbb megállapítások
- Hozz létre batch feladatot a
client.batch.jobs.create()hívással, megadva a fájlt, a modellt és a végpontot - Hét lehetséges állapot létezik, beleértve három véglegeset:
SUCCESS,FAILED,CANCELLED - A haladás nyomon követésének szabványos mintája az időközönkénti polling
- Az eredmények JSONL formátumban vannak, és a
custom_idköti össze őket a kérésekkel - Bármikor listázhatod, inspectálhatod és megszakíthatod a feladataidat