Por Jerry Fan

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.

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.

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.
Estructura básica de una solicitud
{"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.

Una sola solicitud
{"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.

Archivo JSONL con varias solicitudes
{"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.

Formato de las solicitudes de embeddings
{"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.

Respuesta correcta
{"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.

Respuesta de error
{"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.

  1. 1Crea un archivo JSONL con una solicitud por línea
  2. 2Sube el archivo mediante la Files API con purpose definido como batch
  3. 3Crea un trabajo por lotes e indica el ID del archivo que has subido
  4. 4Consulta periódicamente el estado del lote hasta que sea completed, failed o cancelled
  5. 5Descarga y parsea el archivo JSONL de salida para extraer los resultados
Flujo de trabajo completo con la Batch API
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.

Característica
Batch API
API en tiempo real
Costo
50% de descuento
Tarifas estándar
Latencia
Hasta 24 horas
Segundos
Límites de solicitudes
Límites más altos
Límites estándar
Formato de entrada
Carga de un archivo JSONL
Llamadas individuales a la API
Uso recomendado
Procesamiento masivo, evaluación, generación de datos
Aplicaciones interactivas, chat en tiempo real, streaming

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.

Trabaja con archivos JSONL en línea

Visualiza, valida y convierte archivos JSONL de hasta 1GB directamente en tu navegador. Sin necesidad de subir archivos, 100% privado.

Preguntas frecuentes

Referencias