Crear un trabajo por lotes, seguir su estado y descargar los resultados
En esta página
Actualizado el 3 de noviembre de 2026: Adenda del 3 de noviembre:
files.downloaddevuelve una respuesta HTTP (httpx2.Response); lee su contenido con.read()antes de llamar a.decode(). La subida esperafile={"file_name": …, "content": …}. La clave de API ya no está hardcodeada.
De archivo JSONL a resultados: el ciclo de vida completo
Tu archivo JSONL está preparado y subido, y ya dispones de un file_id. El siguiente paso es transformar ese archivo inactivo en resultados utilizables: crear el trabajo por lotes (batch job), monitorizar su progreso durante los minutos u horas que dure el procesamiento y, finalmente, recuperar y conciliar las respuestas. Esta lección recorre el código Python de extremo a extremo en el orden exacto en que lo escribirás.
Crear un trabajo por lotes
La creación requiere una única llamada. Especificas el archivo de origen, el modelo y el endpoint de destino:
from mistralai.client import Mistral
import time
client = Mistral(api_key="your-api-key")
# Crear el trabajo por lotes
job = client.batch.jobs.create(
input_files=[batch_file.id], # ID del archivo subido
model="mistral-small-latest",
endpoint="/v1/chat/completions",
metadata={"project": "document-analysis", "version": "1.0"}
)
print(f"Trabajo creado: {job.id}")
print(f"Estado inicial: {job.status}")
Cada parámetro merece una nota:
input_files: una lista de IDs de archivos subidos. Puedes pasar varios archivos a un único trabajo.model: el modelo de Mistral que se utilizará. Solo un modelo por trabajo por lotes.endpoint: el endpoint de API de destino (debe coincidir con el formato delbodyde tu JSONL).metadata: un diccionario opcional de metadatos personalizados para organizar y recuperar tus trabajos.
La restricción de un solo modelo por trabajo estructura cómo divides tu carga de trabajo: si quieres comparar dos modelos sobre el mismo corpus, envía dos trabajos distintos que apunten al mismo archivo. En cuanto a los metadatos, pueden parecer incidentales hasta que tengas treinta trabajos en tu historial; el par proyecto/versión mostrado arriba te permite entonces encontrar el lote que produjo datos cuestionables en tres segundos planos.
Estados de un trabajo por lotes
Un trabajo por lotes pasa por varios estados durante su ciclo de vida:
| Estado | Descripción |
|---|---|
QUEUED | En cola, aún no iniciado |
RUNNING | Procesamiento en curso |
SUCCESS | Completado con éxito |
FAILED | Procesamiento fallido |
TIMEOUT_EXCEEDED | Se ha superado el tiempo de espera de ejecución |
CANCELLATION_REQUESTED | Cancelación solicitada |
CANCELLED | Cancelado |
Cuatro de estos siete estados son terminales: SUCCESS, FAILED, TIMEOUT_EXCEEDED y CANCELLED. Esta distinción impulsa el bucle de monitorización: mientras el estado no esté en este conjunto, el trabajo sigue vivo y debes esperar. CANCELLATION_REQUESTED, en particular, no es un estado de detención, sino uno de transición; un código que lo trate como terminal saldría del bucle demasiado pronto.
Seguir el progreso
El patrón de sondeo (polling) siguiente encapsula esta lógica exactamente, con una guarda de duración máxima para evitar que un script olvidado se ejecute indefinidamente:
def wait_for_batch(client, job_id, poll_interval=10, max_wait=3600):
"""Esperar a que un trabajo por lotes termine usando sondeo."""
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] Estado: {job.status}")
if job.status in terminal_states:
return job
time.sleep(poll_interval)
elapsed += poll_interval
raise TimeoutError(f"El trabajo {job_id} sigue ejecutándose tras {max_wait}s")
# Uso
completed_job = wait_for_batch(client, job.id)
print(f"Resultado final: {completed_job.status}")
Un intervalo de diez segundos funciona para un lote que dura unos minutos; para una ejecución nocturna que procesa varios cientos de miles de líneas, auméntalo a un minuto o más. Una mayor precisión en el sondeo no aporta valor ahí y solo acumula llamadas a la API innecesarias.
Descargar resultados
Una vez que el estado alcanza SUCCESS, el trabajo expone un output_file que descargas y analizas línea por línea:
import json
if completed_job.status == "SUCCESS":
# Obtener el ID del archivo de salida
output_file_id = completed_job.output_file
# Descargar el contenido
result_data = client.files.download(file_id=output_file_id)
# Analizar resultados JSONL
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
# Mostrar un ejemplo
for cid, resp in list(results.items())[:3]:
content = resp["body"]["choices"][0]["message"]["content"]
print(f"\n--- {cid} ---")
print(content[:200])
El archivo de resultados también está en formato JSONL, y cada línea lleva el custom_id original junto con la respuesta completa del modelo. Aquí es donde el esfuerzo de nomenclatura de la lección anterior da sus frutos: indexar por custom_id en un diccionario es suficiente para conciliar las respuestas con tus documentos de origen, independientemente del orden en que regresen. Mostrar las tres primeras entradas truncadas a 200 caracteres es una comprobación de cordura útil antes de empezar a escribir en tu base de datos.
Listar y gestionar tus trabajos
Puedes filtrar el inventario de trabajos por estado, lo que te permite ver en cualquier momento qué se está ejecutando realmente en tu cuenta:
# Listar todos los trabajos en ejecución actualmente
running_jobs = client.batch.jobs.list(status="RUNNING")
for j in running_jobs.data:
print(f"Trabajo {j.id} - Modelo: {j.model} - Creado: {j.created_at}")
Y cuando un trabajo se alarga demasiado o detectas un error en el prompt tras el envío, la cancelación evita pagar por un procesamiento inútil:
# Cancelar un trabajo que está tardando demasiado
client.batch.jobs.cancel(job_id="job-abc123")
La cancelación es asíncrona: el estado pasa primero a CANCELLATION_REQUESTED y luego a CANCELLED una vez que la detención es efectiva. No consideres el recurso liberado inmediatamente tras el retorno de la llamada.
Flujo de trabajo de extremo a extremo
Ensamblados, estos cuatro pasos forman un script breve que puedes colocar directamente en un planificador:
from mistralai.client import Mistral
import json
import os
import time
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# 1. Subir el archivo
with open("batch_requests.jsonl", "rb") as f:
batch_file = client.files.upload(
file={"file_name": "batch_requests.jsonl", "content": f},
purpose="batch"
)
# 2. Crear el trabajo
job = client.batch.jobs.create(
input_files=[batch_file.id],
model="mistral-small-latest",
endpoint="/v1/chat/completions"
)
# 3. Esperar a que termine
completed = wait_for_batch(client, job.id)
# 4. Descargar y analizar resultados
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"Lote fallido: {completed.status}")
Reutiliza este esqueleto en tu propio corpus con apenas diez líneas: validarás toda la cadena en unos minutos antes de comprometerte con el volumen completo.
Puntos clave
- Crea un trabajo por lotes con
client.batch.jobs.create()especificando el archivo, el modelo y el endpoint. - Siete estados posibles, incluidos tres terminales:
SUCCESS,FAILED,CANCELLED. - El sondeo con un intervalo es el patrón estándar para seguir el progreso.
- Los resultados están en formato JSONL, vinculados a las solicitudes mediante
custom_id. - Puedes listar, inspeccionar y cancelar tus trabajos en cualquier momento.