Batch API para LLM: 50 000 solicitudes con descuentos de hasta el 50% y tres clases de errores

Mientras las solicitudes a un LLM se cuentan por decenas o centenas, la API síncrona funciona bien: envías una solicitud y recibes una respuesta. Pero cuando necesitas procesar 50 000 contratos o fichas de producto, enseguida alcanzas los límites de TPM y RPM, y las solicitudes con contextos largos empiezan a fallar incluso antes de la generación. Para estas tareas, OpenAI, Anthropic y Google ofrecen un modo de procesamiento por lotes, Batch API. Reúnes todas las tareas en un archivo, lo envías al proveedor y esperas hasta 24 horas, a cambio de pagar menos.

Cómo funciona la cola

Detrás de la sencilla palabra «lote» hay tres niveles de restricciones.

El primer nivel es el propio lote. Se trata de un archivo JSONL en el que cada línea contiene custom_id, method, url y un body con el modelo y los mensajes. En esencia, es una solicitud normal a Chat Completions condensada en una línea. El archivo se sube a través de Files API con purpose «batch» y después se crea la tarea. Los resultados no se devuelven en el orden en que se enviaron, por lo que custom_id funciona, en la práctica, como clave primaria: permite vincular cada respuesta con su registro original.

El segundo nivel es el cupo de tokens en cola, o enqueued. El límite no se calcula por archivos, sino por el volumen total de tokens de todos los lotes pendientes de finalizar. Si un nuevo lote hace que la organización supere ese máximo, la API devuelve token_limit_exceeded y rechaza la creación de la tarea. En OpenAI, el máximo depende del tier: cuanto más alto sea, más tokens puedes mantener en cola.

El tercer nivel es el plazo de finalización. Un día es el SLA, no una previsión. En la práctica, los lotes suelen completarse en unas horas, y Anthropic indica que la mayoría están listos en menos de una hora. Pero hay que planificar para el peor caso. Actualmente, el parámetro completion_window solo admite el valor «24h».

Dónde falla el pipeline

El autor del artículo original divide los errores en cuatro clases, con trampas que no siempre resultan evidentes.

Antes de crear el lote. Una coma de más en el JSONL, un custom_id duplicado o ausente, un endpoint incorrecto. Según el autor, Anthropic solo valida los parámetros de las solicitudes cuando termina el lote entero: puedes enviar 100 mil líneas, esperar una hora y descubrir que tres tienen un max_tokens incorrecto. Por eso, valida el archivo localmente antes de subirlo: analiza cada línea, comprueba que los custom_id sean únicos y que estén presentes model y messages. También puedes usar modelos de Pydantic para hacerlo.

En la cola. Aquí, el principal error es token_limit_exceeded. Se resuelve contando los tokens antes del envío y manteniendo una cola propia en la aplicación. Si el volumen previsto supera el cupo, espera a que terminen los lotes anteriores o vuelve a intentarlo con backoff exponencial: 30, 60, 120 segundos y así sucesivamente.

Dentro del lote. Es la categoría más traicionera. El lote figura como completed, pero el archivo de resultados contiene líneas succeeded, errored y expired. Si el código se limita a leer content y escribir en la base de datos, las líneas problemáticas se pierden sin aviso. En Anthropic, los contadores errored, canceled y expired de request_counts permanecen en cero hasta que termina el lote entero, así que no podrás evaluar de antemano el alcance del fallo. Un esquema razonable consiste en separar los casos en tres grupos: corregir y reenviar los invalid_request, reintentar los errores del servidor tras una espera y enviar los expired en un lote nuevo, porque su plazo ya ha vencido.

Al consultar el estado. Si consultas el estado cada cinco segundos, puedes recibir un 429 por el propio polling. Un bucle ingenuo lo interpretará como «el lote aún no está listo», aunque en realidad hayas alcanzado el límite de frecuencia de lectura. Para lotes de hasta mil líneas, consulta cada 30 segundos; para los grandes, cada 2–5 minutos. Si un lote lleva varias horas pendiente, comprueba si se ha quedado atascado en la fase validating.

Cuánto cuesta realmente

El descuento del 50% es un máximo, no una garantía. La cifra final depende de cuántas solicitudes hayan terminado como expired, cuántas haya sido necesario reenviar y si se ha utilizado la caché del prompt del sistema. En un escenario favorable, el ahorro es incluso mayor, porque cached-input también cuesta menos. En uno desfavorable, pagas dos veces por las mismas líneas. Otro matiz importante: en OpenAI, al cancelar un lote se cancelan las solicitudes pendientes, pero se cobran las que ya se han completado.

También conviene señalar que el original tiene, en parte, un enfoque publicitario: el autor propone Bothub, una pasarela compatible con OpenAI que permite pagar con una tarjeta rusa y anuncia un ahorro del 45%. La idea de un endpoint compatible es viable, pero conviene comprobar por cuenta propia las condiciones y la fiabilidad de cualquier intermediario, sin basarse en un enlace de referido.

Qué hacer en la práctica

El procesamiento por lotes implica un contrato distinto: obtienes un descuento y un cupo de límites independiente, pero asumes la responsabilidad de interpretar los resultados. Si estás desarrollando un sistema de procesamiento masivo de documentos, clasificación o anotación, incorpora varios elementos al pipeline:

• validación local del JSONL antes del envío;
• recuento de tokens y un semáforo para el límite de tokens enqueued;
• clasificación del archivo de resultados por tipo de resultado y reenvío exclusivo de las líneas que hayan fallado;
• polling con backoff y registro de created_at.

Y la regla principal: no reenvíes un lote entero por tres líneas fallidas, porque las que se completaron correctamente ya las has pagado.