Създаване на пакетна задача, проследяване на статуса и изтегляне на резултатите
На тази страница
Обновено на 3 ноември 2026 г.: Допълнение за 3 ноември:
files.downloadвръща HTTP отговор (httpx2.Response); прочетете съдържанието му с.read(), преди да извикате.decode(). Качването очакваfile={"file_name": …, "content": …}. API ключът вече не е вграден в кода.
От JSONL файл до резултати: Пълният жизнен цикъл
Вашият JSONL файл е подготвен и качен, а Вие разполагате с file_id. Следващата стъпка е трансформирането на този „спящ“ файл в използваеми резултати: създаване на пакетната задача, мониторинг на нейния напредък през минутите или часовете на обработка и последващо извличане и сверяване на отговорите. Този урок Ви превежда през Python кода от край до край в точния ред, в който ще го напишете.
Създаване на пакетна задача
Създаването изисква само едно извикване. Посочвате изходния файл, модела и целевия крайна точка (endpoint):
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}")
Всеки параметър заслужава внимание:
input_files— Списък с ID-та на качени файлове. Можете да предадете множество файлове на една задача.model— Моделът на Mistral, който да се използва. Само един модел на пакетна задача.endpoint— Целевият API endpoint (трябва да съвпада с формата наbodyвъв Вашия JSONL).metadata— Незадължителен речник с персонализирани метаданни за организиране и извличане на Вашите задачи.
Ограничението за един модел на задача структурира начина, по който разделяте работата си: ако искате да сравните два модела върху един и същи корпус, подайте две отделни задачи, сочещи към един и същи файл. Що се отнася до метаданните, те може да изглеждат второстепенни, докато не натрупате тридесет задачи в историята си; тогава двойката проект/версия, показана по-горе, Ви позволява да откриете пакетната задача, генерирала съмнителни данни, за броени секунди.
Статуси на пакетните задачи
Една пакетна задача преминава през няколко състояния по време на своя жизнен цикъл:
| Status | Description |
|---|---|
QUEUED | На опашка, все още не е стартирана |
RUNNING | Обработката е в ход |
SUCCESS | Завършена успешно |
FAILED | Обработката е неуспешна |
TIMEOUT_EXCEEDED | Превишено е времето за изпълнение |
CANCELLATION_REQUESTED | Заявено е отменяне |
CANCELLED | Отменена |
Четири от тези седем състояния са крайни (терминални) – SUCCESS, FAILED, TIMEOUT_EXCEEDED и CANCELLED – и това разграничение движи цикъла за мониторинг: докато статусът не е в този набор, задачата все още е активна и трябва да изчакате. CANCELLATION_REQUESTED по-специално не е спряно състояние, а преходно; код, който го третира като крайно, би излязъл от цикъла твърде рано.
Проследяване на напредъка
Шаблонът за допитване (polling) по-долу обхваща точно тази логика, включително предпазна мярка за максимална продължителност, която предотвратява безкрайното изпълнение на забравен скрипт:
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}")
Интервал от десет секунди работи добре за пакетна задача, траеща няколко минути; за изпълнение през нощта, обработващо няколкостотин хиляди реда, го увеличете до минута или повече. По-голямата точност на допитването не добавя стойност в този случай и само натрупва ненужни API извиквания.
Изтегляне на резултатите
След като статусът достигне SUCCESS, задачата предоставя output_file, който изтегляте и парсите ред по ред:
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])
Файлът с резултатите също е във формат JSONL и всеки ред носи оригиналния custom_id заедно с пълния отговор на модела. Тук усилията за именуване от предишния урок дават плод: индексирането по custom_id в речник е достатъчно, за да сверите отговорите с Вашите изходни документи, независимо от реда, в който се връщат. Показването на първите три записа, съкратени до 200 знака, е полезна проверка за здравословно състояние, преди да започнете да записвате във Вашата база данни.
Списък и управление на Вашите задачи
Можете да филтрирате инвентара със задачи по статус, което Ви позволява да виждате във всеки момент какво всъщност се изпълнява във Вашия акаунт:
# 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}")
И когато една задача се проточи твърде дълго или откриете грешка в подканата (prompt) след подаването, отменянето избягва плащането за безполезна обработка:
# Cancel a job that is taking too long
client.batch.jobs.cancel(job_id="job-abc123")
Отменянето е асинхронно: статусът първо преминава в CANCELLATION_REQUESTED, а след това в CANCELLED, щом спирането стане ефективно. Не считайте ресурса за освободен веднага след връщането на извикването.
Работен поток от край до край
Сглобени, тези четири стъпки формират кратък скрипт, който можете да поставите директно в планировчик (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}")
Използвайте този скелет отново за Вашия собствен корпус с едва десет реда: ще валидирате цялата верига за няколко минути, преди да се ангажирате с пълния обем.
Ключови изводи
- Създайте пакетна задача с
client.batch.jobs.create(), като посочите файла, модела и endpoint-а - Седем възможни статуса, включително три крайни:
SUCCESS,FAILED,CANCELLED - Допитването (polling) с интервал е стандартният шаблон за проследяване на напредъка
- Резултатите са във формат JSONL, свързани със заявките чрез
custom_id - Можете да изброявате, инспектирате и отменяте Вашите задачи по всяко време