Tworzenie zadania wsadowego, śledzenie statusu i pobieranie wyników
Na tej stronie
Zaktualizowano 3 listopada 2026: Dodatkowe informacje na dzień 3 listopada:
files.downloadzwraca odpowiedź HTTP (httpx2.Response); przed wywołaniem.decode()odczytaj jej zawartość metodą.read(). Przesyłanie oczekuje parametrufile={"file_name": …, "content": …}. Klucz API nie jest już zaszyty na sztywno w kodzie.
Od pliku JSONL do wyników: Pełny cykl życia
Twój plik JSONL jest przygotowany i przesłany, a Ty masz już jego file_id. Kolejnym krokiem jest przekształcenie tego uśpionego pliku w użyteczne wyniki: utworzenie zadania wsadowego, monitorowanie jego postępu przez minuty lub godziny trwania przetwarzania, a następnie pobranie i uzgodnienie odpowiedzi. Ta lekcja przeprowadzi Cię przez kompletny kod Pythona dokładnie w takiej kolejności, w jakiej go napiszesz.
Tworzenie zadania wsadowego
Utworzenie wymaga pojedynczego wywołania. Określasz plik źródłowy, model i docelowy punkt końcowy:
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żdy parametr zasługuje na uwagę:
input_files– lista identyfikatorów przesłanych plików. Do jednego zadania możesz przekazać wiele plików.model– model Mistral, którego chcesz użyć. Na jedno zadanie wsadowe przypada tylko jeden model.endpoint– docelowy punkt końcowy API (musi odpowiadać formatowibodyw Twoim pliku JSONL).metadata– opcjonalny słownik z niestandardowymi metadanymi służącymi do organizowania i wyszukiwania zadań.
Ograniczenie jednego modelu na zadanie determinuje sposób dzielenia pracy: jeśli chcesz porównać dwa modele na tym samym korpusie, wyślij dwa osobne zadania wskazujące na ten sam plik. Jeśli chodzi o metadane, mogą wydawać się drugorzędne, dopóki nie będziesz mieć trzydziestu zadań w historii; wtedy para projekt/wersja pokazana powyżej pozwoli Ci znaleźć wsad, który wygenerował wątpliwe dane, w trzy sekundy.
Statusy zadań wsadowych
Zadanie wsadowe przechodzi przez kilka stanów w trakcie swojego cyklu życia:
| Status | Opis |
|---|---|
QUEUED | W kolejce, jeszcze nie rozpoczęte |
RUNNING | Przetwarzanie w toku |
SUCCESS | Zakończone pomyślnie |
FAILED | Przetwarzanie nieudane |
TIMEOUT_EXCEEDED | Przekroczono limit czasu wykonania |
CANCELLATION_REQUESTED | Żądanie anulowania |
CANCELLED | Anulowane |
Cztery z tych siedmiu stanów są stanami końcowymi – SUCCESS, FAILED, TIMEOUT_EXCEEDED i CANCELLED – i to rozróżnienie napędza pętlę monitorującą: dopóki status nie znajduje się w tym zbiorze, zadanie wciąż żyje i musisz czekać. CANCELLATION_REQUESTED w szczególności nie jest stanem zatrzymania, lecz stanem przejściowym; kod traktujący go jako końcowy zbyt wcześnie przerwałby pętlę.
Śledzenie postępu
Poniższy wzorzec odpytywania (polling) dokładnie odwzorowuje tę logikę, zawierając również zabezpieczenie przed maksymalnym czasem oczekiwania, aby zapobiec nieskończonemu działaniu zapomnianego skryptu:
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}")
Interwał dziesięciu sekund sprawdza się przy zadaniach trwających kilka minut; przy uruchomieniach nocnych przetwarzających kilkaset tysięcy linii zwiększ go do minuty lub więcej. Większa precyzja odpytywania nie wnosi tam żadnej wartości, a jedynie generuje niepotrzebne wywołania API.
Pobieranie wyników
Gdy status osiągnie SUCCESS, zadanie udostępnia output_file, które pobierasz i parsujesz linia po linii:
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])
Plik z wynikami również ma format JSONL, a każda linia zawiera oryginalne custom_id wraz z pełną odpowiedzią modelu. To tutaj owocuje wysiłek włożony w nazewnictwo podczas poprzedniej lekcji: indeksowanie po custom_id w słowniku wystarcza, aby uzgodnić odpowiedzi z dokumentami źródłowymi, niezależnie od kolejności, w jakiej zostały zwrócone. Wyświetlenie pierwszych trzech wpisów przyciętych do 200 znaków to przydatna kontrola sanityzująca przed rozpoczęciem zapisu do bazy danych.
Lista i zarządzanie zadaniami
Możesz filtrować inwentarz zadań według statusu, co pozwala w każdej chwili zobaczyć, co faktycznie działa na Twoim koncie:
# 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 gdy zadanie przeciąga się w czasie lub zauważysz błąd w prompcie po jego wysłaniu, anulowanie pozwala uniknąć płacenia za bezużyteczne przetwarzanie:
# Cancel a job that is taking too long
client.batch.jobs.cancel(job_id="job-abc123")
Anulowanie jest asynchroniczne: status najpierw zmienia się na CANCELLATION_REQUESTED, a następnie na CANCELLED, gdy zatrzymanie stanie się skuteczne. Nie zakładaj, że zasób jest natychmiast zwolniony w momencie powrotu z wywołania.
Przepływ end-to-end
Złożone razem, te cztery kroki tworzą krótki skrypt, który możesz umieścić bezpośrednio w harmonogramie zadań:
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}")
Wykorzystaj ten szkielet na własnym korpusie, dodając zaledwie dziesięć linii: zwalidujesz cały łańcuch w kilka minut, zanim przejdziesz do pełnej objętości danych.
Kluczowe wnioski
- Utwórz zadanie wsadowe za pomocą
client.batch.jobs.create(), określając plik, model i punkt końcowy - Siedem możliwych statusów, w tym trzy końcowe:
SUCCESS,FAILED,CANCELLED - Odpytywanie z określonym interwałem to standardowy wzorzec śledzenia postępu
- Wyniki są w formacie JSONL i powiązane z żądaniami poprzez
custom_id - W dowolnym momencie możesz wyświetlić listę zadań, sprawdzić ich szczegóły i anulować je