Ir al contenido principal
Español— Elegir un idioma
Menú

API por lotes: procesamiento asíncrono masivo

Lección 6 de 20 Actualizado el 3 de noviembre de 2026 Avanzado
En esta página
  1. Intercambia latencia por coste
  2. Construye y lanza un lote
  3. Planifica fallos parciales
  4. Acumula ahorros
  5. Puntos clave

Actualizado el 3 de noviembre de 2026 según la guía de la Batch API y la estructura de respuesta de la Responses API: la lectura de resultados ya no asume que el primer elemento de output sea el mensaje (puede precederlo un elemento de razonamiento), y la clave del código de error, escrita sin comillas, provocaba un NameError. Fuente: Batch API.

Intercambia latencia por coste

La API por lotes se basa en un principio de mercado sencillo: aceptas que tus solicitudes se procesen de forma asíncrona en una ventana de hasta veinticuatro horas y, a cambio, pagas un cincuenta por ciento menos. Cualquier tarea que no requiera servir a un humano esperando frente a la pantalla entra en esta categoría. A gran escala, esto no es una microoptimización; reduce a la mitad tu partida presupuestaria.

El hábito que debe consolidarse en el equipo es preguntarse, para cada nueva tarea de procesamiento, si alguien está esperando el resultado. Analizar un stock de contratos, generar fichas de producto para un catálogo, ejecutar un benchmark sobre miles de casos de prueba, clasificar un backlog de tickets de seis meses o extraer campos de un lote de facturas: en todos estos casos, la respuesta acaba en un cuadro de mandos o en una base de datos, no en una interfaz conversacional. El retraso es invisible, pero el ahorro no.

Construye y lanza un lote

El formato de entrada es un archivo JSONL: una línea por solicitud, donde cada línea es un objeto completo e independiente. El campo custom_id es lo que te permite vincular cada respuesta con su solicitud original, ya que nada garantiza el orden del archivo de salida. Elige un ID estable y significativo, como un ID de documento de tu base de datos en lugar de un número de iteración; de lo contrario, la fase de reconciliación se convertirá en una pesadilla.

import json

requests = [
    {
        "custom_id": f"doc-{i}",
        "method": "POST",
        "url": "/v1/responses",
        "body": {
            "model": "gpt-5.6-luna",
            "input": f"Resume este documento en 3 puntos clave: {doc}",
            "max_output_tokens": 500,
        },
    }
    for i, doc in enumerate(documents_list)
]

# Escribe el archivo JSONL
with open("batch_input.jsonl", "w") as f:
    for request in requests:
        f.write(json.dumps(request) + "\n")

A continuación, el archivo se sube y se referencia al crear el lote. Los metadatos no tienen propósito técnico, pero te salvarán el día cuando tengas tres lotes ejecutándose en paralelo y necesites identificar a cuál corresponde cada versión del prompt.

import openai

client = openai.OpenAI()

# Subir el archivo
file_obj = client.files.create(
    file=open("batch_input.jsonl", "rb"),
    purpose="batch",
)

# Crear el lote
batch = client.batches.create(
    input_file_id=file_obj.id,
    endpoint="/v1/responses",
    completion_window="24h",
    metadata={"project": "contract-analysis", "version": "2.1"},
)

print(f"Lote creado: {batch.id}")
print(f"Estado: {batch.status}")

El seguimiento consiste en sondear el lote hasta que abandone el estado de progreso y, a continuación, descargar el archivo de salida, que también está en formato JSONL. El bucle siguiente distingue tres resultados finales: failed, expired y cancelled, y lanza una excepción para cada uno. Un lote caducado es aquel en el que la ventana de veinticuatro horas transcurrió antes de que todo se procesara; tratarlo como un éxito parcial silencioso sería la peor opción.

import time

def wait_for_batch(batch_id: str, interval: int = 60) -> list:
    """Espera a que un lote termine y devuelve los resultados."""
    while True:
        batch = client.batches.retrieve(batch_id)
        print(
            f"Estado: {batch.status} | "
            f"Completadas: {batch.request_counts.completed}/"
            f"{batch.request_counts.total} | "
            f"Fallidas: {batch.request_counts.failed}"
        )

        if batch.status == "completed":
            break
        elif batch.status in ("failed", "expired", "cancelled"):
            raise RuntimeError(f"Lote fallido: {batch.status}")

        time.sleep(interval)

    # Descargar resultados
    content = client.files.content(batch.output_file_id)
    results = []
    for line in content.text.strip().split("\n"):
        results.append(json.loads(line))

    return results


results = wait_for_batch(batch.id)

# Procesar resultados
for result in results:
    custom_id = result["custom_id"]
    response = result["response"]
    if response["status_code"] == 200:
        # output puede contener otros elementos antes del mensaje
        # (razonamiento, por ejemplo): busca el texto del mensaje
        text = next(
            part["text"]
            for item in response["body"]["output"] if item["type"] == "message"
            for part in item["content"] if part["type"] == "output_text"
        )
        print(f"{custom_id}: {text[:100]}...")
    else:
        print(f"{custom_id}: ERROR {response['status_code']}")

Planifica fallos parciales

En un lote grande, algunas solicitudes fallarán: un documento truncado, un desbordamiento de contexto o un error transitorio del servidor. Por tanto, un lote nunca es simplemente «exitoso» o «fallido»; es parcialmente exitoso y debes saber aislar la parte faltante. El patrón a adoptar es separar inmediatamente los éxitos de los fallos y regenerar un archivo JSONL listo para relanzarse, en lugar de hurgar en los registros tres días después para reconstruir lo que falta.

def handle_batch_errors(results: list[dict]) -> tuple[list, list]:
    """Separa éxitos de fallos para reprocesamiento."""
    successes = []
    failures = []

    for r in results:
        if r["response"]["status_code"] == 200:
            successes.append(r)
        else:
            failures.append(r)

    if failures:
        print(f"Aviso: {len(failures)} solicitudes fallidas de {len(results)}")
        # Reescribe un archivo JSONL con los fallos para reintentar
        with open("batch_retry.jsonl", "w") as f:
            for failure in failures:
                original_request = {
                    "custom_id": failure["custom_id"],
                    "method": "POST",
                    "url": "/v1/responses",
                    "body": failure["request"]["body"],
                }
                f.write(json.dumps(original_request) + "\n")

    return successes, failures

Acumula ahorros

En una ejecución de procesamiento de diez mil documentos con GPT-5.6 Luna, la API síncrona representa el coste base, la API por lotes la mitad de ese coste, y el almacenamiento en caché de prompts se suma además, ya que los tokens en caché también se benefician de su propia reducción. Los dos mecanismos no compiten: si tus diez mil solicitudes comparten el mismo prompt de sistema largo, estructúralo como un prefijo estable y acumularás ambos efectos.

Por último, está la cuestión de la división. Un lote no debe ser infinito; resulta más cómodo supervisar varios lotes manejables que un único monolito cuyo fallo cueste un día entero. La siguiente función divide una lista de solicitudes en lotes de tamaño acotado.

def create_optimized_batches(
    requests: list[dict],
    max_size: int = 50_000,
) -> list[list[dict]]:
    """Divide en lotes de tamaño óptimo."""
    batches = []
    current_batch = []

    for request in requests:
        current_batch.append(request)
        if len(current_batch) >= max_size:
            batches.append(current_batch)
            current_batch = []

    if current_batch:
        batches.append(current_batch)

    return batches

Puntos clave

  • La API por lotes ofrece una reducción del 50 % para el procesamiento no en tiempo real
  • Prepara tus solicitudes en un archivo JSONL con un custom_id único por solicitud
  • Planifica un mecanismo de reintento para las solicitudes fallidas
  • Combínalo con el almacenamiento en caché de prompts para maximizar el ahorro