Criar um Trabalho em Lote, Acompanhar o Estado e Transferir Resultados
Nesta página
Atualizado a 3 de novembro de 2026: Aditamento de 3 de novembro:
files.downloaddevolve uma resposta HTTP (httpx2.Response); leia o seu conteúdo com.read()antes de chamar.decode(). O upload esperafile={"file_name": …, "content": …}. A chave da API já não está codificada diretamente.
Do Ficheiro JSONL aos Resultados: O Ciclo de Vida Completo
O seu ficheiro JSONL está preparado e carregado, e já possui um file_id. O passo seguinte é transformar esse ficheiro adormecido em resultados utilizáveis: criar o trabalho em lote (batch job), monitorizar o seu progresso durante os minutos ou horas que o processamento demora e, finalmente, recuperar e reconciliar as respostas. Esta lição percorre o código Python de ponta a ponta, exatamente pela ordem em que o irá escrever.
Criar um Trabalho em Lote
A criação requer uma única chamada. Especifica o ficheiro de origem, o modelo e o endpoint de destino:
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}")
Cada parâmetro merece uma nota:
input_files— Uma lista de IDs de ficheiros carregados. Pode passar vários ficheiros para um único trabalho.model— O modelo Mistral a utilizar. Apenas um modelo por trabalho em lote.endpoint— O endpoint da API de destino (deve corresponder ao formato dobodyno seu JSONL).metadata— Um dicionário opcional de metadados personalizados para organizar e recuperar os seus trabalhos.
A restrição de um único modelo por trabalho estrutura a forma como divide o seu trabalho: se quiser comparar dois modelos no mesmo corpus, submeta dois trabalhos distintos apontando para o mesmo ficheiro. Quanto aos metadados, podem parecer incidentais até ter trinta trabalhos no seu histórico; o par projeto/versão mostrado acima permite-lhe então encontrar o lote que produziu dados questionáveis em três segundos exatos.
Estados de um Trabalho em Lote
Um trabalho em lote passa por vários estados durante o seu ciclo de vida:
| Estado | Descrição |
|---|---|
QUEUED | Na fila, ainda não iniciado |
RUNNING | Processamento em curso |
SUCCESS | Concluído com sucesso |
FAILED | Processamento falhou |
TIMEOUT_EXCEEDED | Tempo limite de execução excedido |
CANCELLATION_REQUESTED | Cancelamento solicitado |
CANCELLED | Cancelado |
Quatro destes sete estados são terminais — SUCCESS, FAILED, TIMEOUT_EXCEEDED e CANCELLED — e esta distinção conduz o ciclo de monitorização: enquanto o estado não estiver neste conjunto, o trabalho ainda está ativo e deve aguardar. CANCELLATION_REQUESTED, em particular, não é um estado de paragem, mas sim de transição; um código que o trate como terminal sairia do ciclo prematuramente.
Acompanhar o Progresso
O padrão de sondagem (polling) abaixo encapsula exatamente esta lógica, com um limite de duração máxima para impedir que um script esquecido execute indefinidamente:
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}")
Um intervalo de dez segundos funciona para um lote que dura alguns minutos; para uma execução noturna que processa várias centenas de milhares de linhas, aumente-o para um minuto ou mais. Uma maior precisão na sondagem não acrescenta valor nesse cenário e apenas acumula chamadas à API desnecessárias.
Transferir Resultados
Assim que o estado atinge SUCCESS, o trabalho expõe um output_file que pode transferir e analisar linha por linha:
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])
O ficheiro de resultados também está no formato JSONL, e cada linha transporta o custom_id original juntamente com a resposta completa do modelo. É aqui que o esforço de nomenclatura da lição anterior compensa: indexar por custom_id num dicionário é suficiente para reconciliar as respostas com os seus documentos de origem, independentemente da ordem em que retornam. Exibir as primeiras três entradas truncadas a 200 caracteres é uma verificação de sanidade útil antes de começar a escrever na sua base de dados.
Listar e Gerir os Seus Trabalhos
Pode filtrar o inventário de trabalhos por estado, permitindo-lhe ver a qualquer momento o que está realmente em execução na sua conta:
# 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}")
E quando um trabalho se arrasta demasiado ou deteta um erro no prompt após o envio, o cancelamento evita pagar por processamento inútil:
# Cancel a job that is taking too long
client.batch.jobs.cancel(job_id="job-abc123")
O cancelamento é assíncrono: o estado muda primeiro para CANCELLATION_REQUESTED e depois para CANCELLED assim que a paragem é efetiva. Não considere o recurso libertado imediatamente após o retorno da chamada.
Fluxo de Trabalho de Ponta a Ponta
Reunidos, estes quatro passos formam um script curto que pode colocar diretamente num agendador:
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}")
Reutilize este esqueleto no seu próprio corpus com apenas dez linhas: validará toda a cadeia em alguns minutos antes de se comprometer com o volume total.
Pontos-chave
- Crie um trabalho em lote com
client.batch.jobs.create(), especificando o ficheiro, o modelo e o endpoint - Sete estados possíveis, incluindo três terminais:
SUCCESS,FAILED,CANCELLED - A sondagem com um intervalo é o padrão habitual para acompanhar o progresso
- Os resultados estão no formato JSONL, ligados aos pedidos através do
custom_id - Pode listar, inspecionar e cancelar os seus trabalhos a qualquer momento