Vytvoření dávkové úlohy, sledování stavu a stažení výsledků
Na této stránce
Aktualizováno 3. listopadu 2026: Dodatek k 3. listopadu:
files.downloadvrací HTTP odpověď (httpx2.Response); před voláním.decode()si její obsah přečti pomocí.read(). Nahrávání očekáváfile={"file_name": …, "content": …}. API klíč již není natvrdo zakódován.
Od souboru JSONL k výsledkům: Kompletní životní cyklus
Tvůj soubor JSONL je připraven a nahrán a máš k dispozici file_id. Dalším krokem je transformace tohoto nečinného souboru na použitelné výsledky: vytvoř dávkovou úlohu (batch job), sleduj její průběh během minut či hodin potřebných ke zpracování a následně získej a seskup odpovědi. Tato lekce tě provede kódem v Pythonu od začátku do konce přesně v pořadí, v jakém ho napíšeš.
Vytvoření dávkové úlohy
Vytvoření vyžaduje jediný volání. Určíš zdrojový soubor, model a cílový koncový bod:
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}")
Každý parametr si zaslouží poznámku:
input_files– Seznam ID nahraných souborů. Do jedné úlohy můžeš předat více souborů.model– Model Mistral, který chceš použít. Na jednu dávkovou úlohu připadá pouze jeden model.endpoint– Cílový koncový bod API (musí odpovídat formátubodyv tvém JSONL).metadata– Volitelný slovník vlastních metadat pro organizaci a vyhledávání tvých úloh.
Omezení jednoho modelu na úlohu určuje, jak rozdělíš svou práci: pokud chceš na stejném korpusu porovnat dva modely, odešli dvě samostatné úlohy směřující na stejný soubor. Co se týče metadat, mohou se zdát nepodstatná, dokud nemáš v historii třicet úloh; pár projekt/verze uvedený výše ti pak umožní najít dávku, která vyprodukovala pochybná data, za tři sekundy.
Stavy dávkové úlohy
Dávková úloha prochází během svého životního cyklu několika stavy:
| Status | Description |
|---|---|
QUEUED | Ve frontě, ještě nespustěno |
RUNNING | Probíhá zpracování |
SUCCESS | Úspěšně dokončeno |
FAILED | Zpracování selhalo |
TIMEOUT_EXCEEDED | Překročen časový limit provádění |
CANCELLATION_REQUESTED | Požadavek na zrušení odeslán |
CANCELLED | Zrušeno |
Čtyři z těchto sedmi stavů jsou konečné – SUCCESS, FAILED, TIMEOUT_EXCEEDED a CANCELLED – a právě tento rozdíl řídí smyčku monitorování: dokud stav není v této množině, úloha stále běží a ty musíš čekat. CANCELLATION_REQUESTED není stav zastavení, ale přechodný stav; kód, který by s ním zacházel jako s konečným, by smyčku ukončil příliš brzy.
Sledování průběhu
Následující vzor dotazování (polling) tuto logiku přesně zapouzdřuje, včetně ochrany proti maximální délce trvání, aby zapomenutý skript neběžel donekonečna:
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}")
Desetisekundový interval funguje pro dávku trvající několik minut; pro noční běh zpracovávající několik set tisíc řádků jej zvyš na minutu nebo více. Větší přesnost dotazování tam nepřináší žádnou hodnotu a pouze hromadí zbytečná volání API.
Stažení výsledků
Jakmile stav dosáhne SUCCESS, úloha zpřístupní output_file, který stáhneš a řádek po řádku zpracuješ:
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])
Soubor s výsledky je také ve formátu JSONL a každý řádek obsahuje původní custom_id spolu s úplnou odpovědí modelu. Zde se vyplatí úsilí o pojmenování z předchozí lekce: indexování podle custom_id ve slovníku stačí k tomu, abys odpovědi přiřadil ke svým zdrojovým dokumentům, bez ohledu na pořadí, v jakém se vrátí. Zobrazení prvních tří položek oříznutých na 200 znaků je užitečná kontrola sanity předtím, než začneš zapisovat do své databáze.
Správa a výpis tvých úloh
Inventář úloh můžeš filtrovat podle stavu, což ti umožní kdykoli vidět, co se na tvém účtu skutečně provádí:
# 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}")
A když se úloha vleče nebo po odeslání objevíš chybu v promptu, zrušení zabrání placení za zbytečné zpracování:
# Cancel a job that is taking too long
client.batch.jobs.cancel(job_id="job-abc123")
Zrušení je asynchronní: stav se nejprve změní na CANCELLATION_REQUESTED a poté na CANCELLED, jakmile je zastavení účinné. Nepovažuj zdroj za uvolněný okamžitě po návratu volání.
Pracovní postup od začátku do konce
Tyto čtyři kroky dohromady tvoří krátký skript, který můžeš přímo umístit do plánovače:
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}")
Tuto kostru znovu použij na svém vlastním korpusu s pouhými deseti řádky: během několika minut ověříš celý řetězec, než se zavážeš k plnému objemu.
Klíčové poznatky
- Vytvoř dávkovou úlohu pomocí
client.batch.jobs.create()určením souboru, modelu a koncového bodu - Sedm možných stavů, včetně tří konečných:
SUCCESS,FAILED,CANCELLED - Dotazování (polling) v intervalech je standardním vzorem pro sledování průběhu
- Výsledky jsou ve formátu JSONL a jsou propojeny s požadavky prostřednictvím
custom_id - Svě úlohy můžeš kdykoli vypsat, zkontrolovat a zrušit