Crearea unei sarcini batch, urmărirea stării și descărcarea rezultatelor
Pe această pagină
Actualizat pe 3 noiembrie 2026: Supliment pentru 3 noiembrie:
files.downloadreturnează un răspuns HTTP (httpx2.Response); citiți conținutul său cu.read()înainte de a apela.decode(). Încărcarea așteaptăfile={"file_name": …, "content": …}. Cheia API nu mai este codificată direct.
De la fișierul JSONL la rezultate: Ciclul de viață complet
Fișierul dumneavoastră JSONL este pregătit și încărcat, iar dumneavoastră dețineți un file_id. Următorul pas constă în transformarea acelui fișier dormant în rezultate utilizabile: creați sarcina batch, monitorizați progresul acesteia pe parcursul minutelor sau orelor necesare procesării, apoi preluați și reconciliați răspunsurile. Această lecție parcurge codul Python cap-coadă, în exact ordinea în care îl veți scrie.
Crearea unei sarcini batch
Crearea necesită un singur apel. Specificați fișierul sursă, modelul și punctul final (endpoint) țintă:
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}")
Fiecare parametru merită o notă:
input_files— O listă de ID-uri de fișiere încărcate. Puteți transmite mai multe fișiere unei singure sarcini.model— Modelul Mistral de utilizat. Doar un singur model per sarcină batch.endpoint— Punctul final API țintă (trebuie să corespundă formatuluibodydin JSONL-ul dumneavoastră).metadata— Un dicționar opțional de metadate personalizate pentru a vă organiza și recupera sarcinile.
Constrângerea „un singur model per sarcină“ structurează modul în care vă divizați munca: dacă doriți să comparați două modele pe același corpus, trimiteți două sarcini distincte care indică spre același fișier. Cât despre metadate, acestea pot părea incidentale până când aveți treizeci de sarcini în istoric; perechea proiect/versiune prezentată mai sus vă permite atunci să găsiți batch-ul care a produs date discutabile în exact trei secunde.
Stările sarcinii batch
O sarcină batch trece prin mai multe stări pe parcursul ciclului său de viață:
| Status | Descriere |
|---|---|
QUEUED | În coadă, nu a început încă |
RUNNING | Procesare în curs |
SUCCESS | Finalizat cu succes |
FAILED | Procesare eșuată |
TIMEOUT_EXCEEDED | Depășirea timpului limită de execuție |
CANCELLATION_REQUESTED | Anulare solicitată |
CANCELLED | Anulat |
Patru dintre aceste șapte stări sunt terminale—SUCCESS, FAILED, TIMEOUT_EXCEEDED și CANCELLED—iar această distincție guvernează bucla de monitorizare: atâta timp cât starea nu se află în acest set, sarcina este încă activă și trebuie să așteptați. CANCELLATION_REQUESTED, în special, nu este o stare de oprire, ci una de tranziție; un cod care ar trata-o ca terminal ar ieși din buclă prea devreme.
Urmărirea progresului
Modelul de interogare (polling) de mai jos încapsulează exact această logică, incluzând o limită de durată maximă pentru a preveni rularea indefinită a unui script uitat:
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}")
Un interval de zece secunde funcționează pentru un batch care durează câteva minute; pentru o execuție peste noapte care procesează câteva sute de mii de linii, măriți-l la un minut sau mai mult. O precizie mai mare a interogării nu aduce nicio valoare în acel caz și doar acumulează apeluri API inutile.
Descărcarea rezultatelor
Odată ce starea ajunge la SUCCESS, sarcina expune un output_file pe care îl descărcați și îl parsează linie cu linie:
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])
Fișierul de rezultate este, de asemenea, în format JSONL, iar fiecare linie conține custom_id original alături de răspunsul complet al modelului. Aici își dovedește utilitatea efortul de denumire din lecția anterioară: indexarea după custom_id într-un dicționar este suficientă pentru a reconcilia răspunsurile cu documentele sursă, indiferent de ordinea în care acestea sunt returnate. Afișarea primelor trei intrări trunchiate la 200 de caractere constituie o verificare de sanityitate utilă înainte de a începe scrierea în baza de date.
Listarea și gestionarea sarcinilor
Puteți filtra inventarul de sarcini după stare, permițându-vă să vedeți în orice moment ce rulează efectiv în contul dumneavoastră:
# 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}")
Iar atunci când o sarcină se prelungește excesiv sau depistați o eroare de prompt după submitere, anularea evită plata pentru o procesare inutilă:
# Cancel a job that is taking too long
client.batch.jobs.cancel(job_id="job-abc123")
Anularea este asincronă: starea trece mai întâi la CANCELLATION_REQUESTED, apoi la CANCELLED odată ce oprirea devine efectivă. Nu considerați resursa eliberată imediat la returnarea apelului.
Flux de lucru cap-coadă
Asamblate, acești patru pași formează un script scurt pe care îl puteți plasa direct într-un planificator (scheduler):
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}")
Reutilizați acest schelet pe propriul corpus cu doar zece linii: veți valida întregul lanț în câteva minute înainte de a vă angaja în volumul complet.
Puncte cheie
- Creați o sarcină batch cu
client.batch.jobs.create()specificând fișierul, modelul și endpoint-ul - Șapte stări posibile, inclusiv trei terminale:
SUCCESS,FAILED,CANCELLED - Interogarea (polling) cu un interval este modelul standard pentru urmărirea progresului
- Rezultatele sunt în format JSONL, legate de cereri prin
custom_id - Puteți lista, inspecta și anula sarcinile în orice moment