Guía del formato JSONL para la Batch API de OpenAI
Aprende a estructurar archivos JSONL para la Batch API de OpenAI y ahorra un 50% en costos
¿Qué es la Batch API de OpenAI?
La Batch API de OpenAI te permite agrupar un gran volumen de solicitudes a la API en un único trabajo por lotes. En lugar de realizar miles de llamadas individuales a la API, subes un archivo JSONL con todas las solicitudes y OpenAI las procesa de forma asíncrona en un plazo de 24 horas.
La principal ventaja es el costo: las solicitudes por lotes cuestan un 50% menos que las llamadas a la API en tiempo real. Por eso, la Batch API es ideal para tareas que no requieren una respuesta inmediata, como la generación de contenido, la clasificación de datos, el cálculo de embeddings y los pipelines de evaluación.
Formato JSONL de las solicitudes
Cada línea del archivo JSONL de entrada del lote representa una solicitud a la API. Debe contener tres campos obligatorios y seguir una estructura específica.
custom_id — Identificador único de cada solicitud. Permite relacionar cada solicitud con su respuesta. Puede ser cualquier cadena de hasta 512 caracteres.method — Método HTTP. Actualmente solo se admite POST.url — Ruta del endpoint de la API. Para chat completions: /v1/chat/completions. Para embeddings: /v1/embeddings.body — Cuerpo de la solicitud. Tiene el mismo formato que el cuerpo de las solicitudes al endpoint correspondiente de la API.{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}Solicitudes a Chat Completions por lotes
El uso más habitual de la Batch API es enviar varias solicitudes a Chat Completions. Cada línea contiene una solicitud completa con model, messages y parámetros opcionales como max_tokens o temperature.
Una sola solicitud
Cada línea contiene una solicitud completa a Chat Completions con model, messages y parámetros opcionales.
{"custom_id": "task-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Summarize the benefits of renewable energy."}], "max_tokens": 500}}Archivo JSONL con varias solicitudes
Un archivo para procesamiento por lotes suele contener cientos o miles de solicitudes. Este ejemplo contiene tres tareas distintas: resumen, clasificación y traducción.
{"custom_id": "summary-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Summarize: Solar energy is a renewable source of power that harnesses sunlight using photovoltaic cells."}], "max_tokens": 200}}
{"custom_id": "classify-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Classify this review as positive or negative: Great product, works perfectly!"}], "max_tokens": 50}}
{"custom_id": "translate-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Translate to French: Hello, how are you today?"}], "max_tokens": 100}}Solicitudes de embeddings por lotes
La Batch API también admite solicitudes de embeddings, lo que resulta útil para procesar grandes colecciones de documentos. Estos lotes usan la misma estructura JSONL, pero envían las solicitudes al endpoint /v1/embeddings.
El cuerpo de las solicitudes de embeddings tiene una estructura más sencilla, con model y el texto de entrada.
{"custom_id": "embed-001", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "JSONL is a text format for storing structured data."}}
{"custom_id": "embed-002", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "Each line contains one valid JSON object."}}
{"custom_id": "embed-003", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "JSONL files use the .jsonl extension."}}Formato de las respuestas
Cuando termina un trabajo por lotes, OpenAI proporciona un archivo JSONL de salida con la respuesta a una solicitud en cada línea. Cada respuesta incluye el custom_id original para que puedas relacionarla con su solicitud.
Respuesta correcta
Una respuesta correcta incluye el custom_id, el código de estado de la respuesta y el cuerpo completo de la respuesta de la API.
{"id": "batch_req_abc123", "custom_id": "task-001", "response": {"status_code": 200, "body": {"id": "chatcmpl-xyz", "object": "chat.completion", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Renewable energy provides numerous benefits including reduced greenhouse gas emissions, lower long-term costs, and energy independence."}}]}}, "error": null}Respuesta de error
Las solicitudes que fallan incluyen un objeto de error con un código y un mensaje que explica el problema.
{"id": "batch_req_def456", "custom_id": "task-002", "response": null, "error": {"code": "invalid_request_error", "message": "The model 'gpt-5' does not exist."}}Flujo de trabajo completo con la Batch API
Estos son los cinco pasos para usar la Batch API con el SDK de Python, desde la creación del archivo JSONL hasta la descarga y el análisis de los resultados.
- 1Crea un archivo JSONL con una solicitud por línea
- 2Sube el archivo mediante la Files API con purpose definido como batch
- 3Crea un trabajo por lotes e indica el ID del archivo que has subido
- 4Consulta periódicamente el estado del lote hasta que sea completed, failed o cancelled
- 5Descarga y parsea el archivo JSONL de salida para extraer los resultados
from openai import OpenAI
import json
import time
client = OpenAI()
# Step 1: Create the JSONL batch file
prompts = [
"Summarize the benefits of renewable energy.",
"Classify this text as positive or negative: Great product!",
"Translate to French: Hello, how are you?",
]
requests = [
{
"custom_id": f"req-{i}",
"method": "POST",
"url": "/v1/chat/completions",
"body": {
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": prompt}],
"max_tokens": 200,
},
}
for i, prompt in enumerate(prompts)
]
with open("batch_input.jsonl", "w") as f:
for req in requests:
f.write(json.dumps(req) + "\n")
# Step 2: Upload the file
batch_file = client.files.create(
file=open("batch_input.jsonl", "rb"),
purpose="batch",
)
# Step 3: Create the batch
batch = client.batches.create(
input_file_id=batch_file.id,
endpoint="/v1/chat/completions",
completion_window="24h",
)
print(f"Batch created: {batch.id}")
# Step 4: Poll for completion
while True:
status = client.batches.retrieve(batch.id)
print(f"Status: {status.status}")
if status.status in ("completed", "failed", "cancelled"):
break
time.sleep(60)
# Step 5: Download results
if status.output_file_id:
content = client.files.content(status.output_file_id)
with open("batch_output.jsonl", "wb") as f:
f.write(content.read())Batch API frente a la API en tiempo real
Saber cuándo usar la Batch API y cuándo recurrir a la API estándar en tiempo real te ayuda a optimizar los costos y el rendimiento.
Para obtener más información sobre el formato JSONL para el fine-tuning de OpenAI, consulta nuestra Guía del formato JSONL para OpenAI.
Prepara tus archivos para el procesamiento por lotes
Usa nuestras herramientas gratuitas para crear, validar e inspeccionar los archivos JSONL de tus lotes antes de enviarlos a OpenAI.
Guía completa para preparar archivos JSONL para OpenAI. Incluye el formato de los datos de fine-tuning, las solicitudes de Batch API, los errores habituales y consejos de validación.
Divide archivos JSONL grandes en fragmentos más pequeños y manejables por número de líneas.
Valida archivos JSONL línea por línea. Detecta al instante errores de sintaxis, problemas de codificación y fallos de formato.
Estrategias para procesar gigabytes de datos JSONL: lectura en streaming, gestión de memoria, división de archivos, compresión y herramientas online.
Aprende a preparar datos de entrenamiento en JSONL para fine-tuning de IA/ML. Incluye los formatos de datasets de OpenAI, Anthropic Claude y HuggingFace, junto con la validación y los pipelines de preparación de datos.