Formato JSONL, custom_id y carga de archivos
En esta página
Actualizado el 3 de noviembre de 2026: Con la versión 3.7.0 del SDK
mistralai,files.uploadesperafile={"file_name": …, "content": …}(pasar una tupla lanza unValidationErrorantes de enviar cualquier dato), y el tamaño del archivo está disponible ensize_bytes.
El formato JSONL: la columna vertebral de la inferencia por lotes
JSONL (JSON Lines) es el formato estándar que utiliza Mistral para estructurar las solicitudes por lotes. Cada línea del archivo es un objeto JSON independiente que representa una única solicitud. Este diseño es intencionado: puedes generar mediante streaming un archivo de un millón de líneas sin cargarlo todo en memoria, leerlo línea a línea e inspeccionar entradas específicas manualmente cuando una solicitud falla. A diferencia de un único array JSON masivo, que te obliga a cargar el archivo entero solo para verificar una entrada, JSONL te permite trabajar a nivel de línea.
Estructura de la solicitud JSONL
Cada línea de tu archivo JSONL debe contener dos campos obligatorios:
{
"custom_id": "req-001",
"body": {
"max_tokens": 100,
"messages": [
{"role": "user", "content": "Resume este documento en 3 puntos."}
]
}
}
El custom_id es un identificador único que tú defines para cada solicitud. Es lo que hace que los resultados sean utilizables. Mistral no garantiza el orden de procesamiento: el archivo de salida podría comenzar con la solicitud 8.472. Sin un custom_id, te quedas con un montón de respuestas y ninguna forma de saber a qué documento corresponde cada una. Acostúmbrate a derivar este ID de tu propio sistema de referencia —doc-001, email-2024-03-15-042, product-sku-ABC123— en lugar de usar un contador anónimo. Cuando una respuesta cause problemas, podrás rastrearla hasta su origen sin necesidad de ejecutar una consulta SQL. Aquí aplican dos reglas prácticas: los IDs deben ser únicos dentro del archivo, o el procesamiento devolverá un error, y deben ser razonablemente cortos, ya que un identificador de 200 caracteres hace que los registros sean ilegibles.
El campo body no requiere ningún aprendizaje nuevo: contiene exactamente la misma estructura que usarías para una llamada síncrona a la API hacia el endpoint objetivo. Si tu objetivo es /v1/chat/completions, el cuerpo es idéntico al que pasarías en una llamada client.chat.complete(). Un prompt validado interactivamente se traduce directamente en un trabajo por lotes.
Generación de un archivo JSONL en Python
Así es como generar programáticamente un archivo JSONL a partir de una lista de documentos:
import json
documents = [
{"id": "doc-001", "text": "La inteligencia artificial está transformando..."},
{"id": "doc-002", "text": "Las redes neuronales profundas..."},
{"id": "doc-003", "text": "El procesamiento del lenguaje natural..."},
]
with open("batch_requests.jsonl", "w", encoding="utf-8") as f:
for doc in documents:
request = {
"custom_id": doc["id"],
"body": {
"model": "mistral-small-latest",
"max_tokens": 200,
"messages": [
{
"role": "system",
"content": "Eres un asistente que resume textos."
},
{
"role": "user",
"content": f"Resume este texto: {doc['text']}"
}
]
}
}
f.write(json.dumps(request, ensure_ascii=False) + "\n")
Observa el parámetro ensure_ascii=False. Sin él, json.dumps escapa los caracteres acentuados como secuencias \uXXXX. El archivo sigue siendo válido, pero se vuelve imposible de leer para un humano, convirtiendo cualquier depuración sobre un corpus en francés en un ejercicio de descifrado. Haz de esto tu valor por defecto desde la primera línea de código.
Carga del archivo en Mistral
En producción, realiza la carga mediante la API de Python:
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Cargar el archivo JSONL
with open("batch_requests.jsonl", "rb") as f:
batch_file = client.files.upload(
file={"file_name": "batch_requests.jsonl", "content": f},
purpose="batch"
)
print(f"Archivo cargado: {batch_file.id}")
print(f"Tamaño: {batch_file.size_bytes} bytes")
print(f"Propósito: {batch_file.purpose}")
El parámetro purpose="batch" indica a Mistral que este archivo está destinado al procesamiento por lotes, no a otras funciones como el ajuste fino o RAG. Esta declaración de intenciones dicta lo que sucede a continuación: un archivo cargado con el propósito incorrecto será rechazado por el trabajo.
Para una prueba rápida o para equipos no técnicos, AI Studio ofrece el mismo servicio a través de la interfaz gráfica:
- Ve a
console.mistral.ai/build/files - Haz clic en “Upload” (Cargar)
- Selecciona tu archivo JSONL
- Elige el propósito “Batch Processing” (Procesamiento por lotes)
La interfaz devuelve un file_id, exactamente igual que la API, y este es el identificador que utilizas para crear el trabajo por lotes.
Validación del archivo
Un lote de un millón de líneas que falla en la línea 300 debido a un custom_id duplicado te cuesta un ciclo de espera completo. Unos segundos de validación local evitan esta pérdida. El siguiente script realiza un único pase para comprobar la validez del JSON, la presencia de los dos campos obligatorios y la unicidad de los ID:
import json
errors = []
seen_ids = set()
with open("batch_requests.jsonl", "r", encoding="utf-8") as f:
for line_num, line in enumerate(f, 1):
try:
data = json.loads(line)
except json.JSONDecodeError as e:
errors.append(f"Línea {line_num}: JSON no válido - {e}")
continue
# Comprobar campos obligatorios
if "custom_id" not in data:
errors.append(f"Línea {line_num}: falta custom_id")
if "body" not in data:
errors.append(f"Línea {line_num}: falta body")
# Comprobar unicidad de custom_id
cid = data.get("custom_id")
if cid in seen_ids:
errors.append(f"Línea {line_num}: custom_id duplicado '{cid}'")
seen_ids.add(cid)
if errors:
print(f"Se han encontrado {len(errors)} error(es):")
for e in errors:
print(f" - {e}")
else:
print(f"Archivo válido: {len(seen_ids)} solicitudes listas.")
Convierte esto en un paso sistemático de tu pipeline de preparación, ejecutado justo antes de la carga.
Límites y restricciones
El procesamiento por lotes de archivos tiene un límite de un millón de líneas por archivo, lo que significa que debes dividir los corpus más grandes en múltiples envíos. La codificación debe ser UTF-8 y el formato requiere estrictamente un objeto JSON por línea: un objeto JSON distribuido en varias líneas, como el producido por un json.dumps(..., indent=2) mal colocado, rompe el análisis del lado del servidor. Por último, recuerda las dos reglas ya mencionadas, ya que violarlas hace que el trabajo falle: el custom_id debe ser único dentro del archivo y el body debe coincidir con el esquema del endpoint objetivo.
Puntos clave
- JSONL estructura tus solicitudes por lotes con un objeto JSON por línea
- Cada solicitud requiere un
custom_idúnico y unbodyque coincida con el endpoint objetivo - Carga el archivo mediante la API de Python (
client.files.upload) o a través de AI Studio - Valida siempre tu archivo antes del envío para evitar errores de procesamiento
- Usa
ensure_ascii=Falsepara caracteres franceses y acentuados