Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Criar um Trabalho em Lote, Acompanhar o Estado e Transferir Resultados

Aula 3 de 16 Atualizada a 3 de novembro de 2026 Avancado
Nesta página
  1. Do Ficheiro JSONL aos Resultados: O Ciclo de Vida Completo
  2. Criar um Trabalho em Lote
  3. Estados de um Trabalho em Lote
  4. Acompanhar o Progresso
  5. Transferir Resultados
  6. Listar e Gerir os Seus Trabalhos
  7. Fluxo de Trabalho de Ponta a Ponta
  8. Pontos-chave

Atualizado a 3 de novembro de 2026: Aditamento de 3 de novembro: files.download devolve uma resposta HTTP (httpx2.Response); leia o seu conteúdo com .read() antes de chamar .decode(). O upload espera file={"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 do body no 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:

EstadoDescrição
QUEUEDNa fila, ainda não iniciado
RUNNINGProcessamento em curso
SUCCESSConcluído com sucesso
FAILEDProcessamento falhou
TIMEOUT_EXCEEDEDTempo limite de execução excedido
CANCELLATION_REQUESTEDCancelamento solicitado
CANCELLEDCancelado

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