Batch API para LLMs: 50 000 requisições com desconto de até 50% e três classes de erros

Enquanto o volume de requisições a uma LLM fica em algumas dezenas ou centenas, a API síncrona funciona bem: você envia a requisição e recebe a resposta. Mas, quando precisa processar 50 000 contratos ou fichas de produtos, logo esbarra nos limites de TPM e RPM, e as requisições com contextos longos começam a falhar antes mesmo da geração. Para essas tarefas, OpenAI, Anthropic e Google oferecem um modo de processamento em lote, a Batch API. Você reúne todas as tarefas em um arquivo, envia ao provedor e espera até 24 horas, mas paga menos.

Como funciona a fila

Por trás da palavra aparentemente simples “lote”, há três níveis de restrições.

O primeiro nível é o próprio lote. Trata-se de um arquivo JSONL em que cada linha contém custom_id, method, url e body com o modelo e as mensagens. Na prática, é uma requisição comum ao Chat Completions, empacotada em uma única linha. O arquivo é enviado pela Files API com purpose “batch”, e então a tarefa é criada. Os resultados não voltam na mesma ordem do envio, por isso custom_id funciona, na prática, como uma chave primária: é ele que permite associar cada resposta ao registro original.

O segundo nível é a cota de tokens enqueued. O limite não considera a quantidade de arquivos, mas o volume total de tokens em todos os lotes ainda não concluídos. Se um novo lote fizer a organização ultrapassar o teto, a API retorna token_limit_exceeded e se recusa a criar a tarefa. Na OpenAI, esse teto depende do tier: quanto mais alto, mais tokens podem permanecer na fila.

O terceiro nível é a janela de conclusão. Um dia é o SLA, não uma previsão. Na prática, os lotes costumam terminar em algumas horas, e a Anthropic afirma que a maioria fica pronta em menos de uma hora. Mas é preciso planejar para o pior caso. Atualmente, o parâmetro completion_window aceita apenas o valor “24h”.

Onde o pipeline falha

O autor do artigo original divide os erros em quatro classes, com armadilhas que não são óbvias.

Antes da criação do lote. Uma vírgula a mais no JSONL, um custom_id duplicado ou ausente, um endpoint incorreto. Segundo o autor, a Anthropic só verifica os parâmetros das requisições depois que todo o lote termina: você pode enviar 100 mil linhas, esperar uma hora e descobrir que três delas têm um max_tokens inválido. Por isso, valide o arquivo localmente antes do upload: faça o parsing de cada linha, confira se os valores de custom_id são únicos e verifique a presença de model e messages. Modelos Pydantic também servem para isso.

No nível da fila. Aqui, o principal erro é token_limit_exceeded. A solução é contar os tokens antes do envio e manter uma fila na própria aplicação. Se o volume de tokens não couber na cota disponível, espere os lotes anteriores terminarem ou tente novamente com backoff exponencial: 30, 60, 120 segundos e assim por diante.

Dentro do lote. É a categoria mais traiçoeira. O lote está completed, mas o arquivo de resultados tem algumas linhas succeeded, outras errored e outras expired. Se o código apenas lê content e grava no banco, as linhas com problemas se perdem silenciosamente. Na Anthropic, os contadores errored, canceled e expired em request_counts permanecem zerados até que todo o lote termine, então não é possível estimar antes disso a extensão da falha. Uma abordagem sensata é separar os casos em três grupos: corrigir e reenviar invalid_request, repetir as requisições com erros de servidor após uma espera e colocar expired em um novo lote, porque a janela já se encerrou.

Ao consultar o status. Consultar o status a cada cinco segundos pode gerar um 429 no próprio polling. Um loop ingênuo interpretará isso como “o lote ainda não está pronto”, quando, na verdade, você atingiu o limite de requisições de leitura. Para lotes de até mil linhas, consulte a cada 30 segundos; para os maiores, a cada 2–5 minutos. Se o lote continuar pendente por mais de algumas horas, verifique se ficou preso na etapa validating.

Quanto isso custa de verdade

O desconto de 50% é um teto, não uma garantia. O valor final depende de quantas requisições ficaram como expired, quantas precisaram ser reenviadas e se houve uso do cache do prompt de sistema. Em um cenário favorável, a economia pode ser ainda maior, porque cached-input também custa menos. Em um cenário desfavorável, você paga duas vezes pelas mesmas linhas. Outro detalhe importante: na OpenAI, ao cancelar um lote, as requisições ainda não concluídas são canceladas, mas as já executadas são cobradas.

Vale mencionar também que parte do original tem caráter publicitário: o autor promove o gateway Bothub, compatível com a OpenAI, com pagamento por cartão russo e uma economia anunciada de 45%. A ideia de um endpoint compatível funciona, mas é preciso verificar por conta própria as condições e a confiabilidade de qualquer intermediário, em vez de se guiar por um link de indicação.

O que fazer na prática

O processamento em lote envolve outro contrato: você recebe um desconto e um conjunto separado de limites, mas assume a responsabilidade de tratar os resultados. Se estiver criando um fluxo de processamento de documentos em massa, classificação ou anotação, inclua alguns elementos no pipeline:

• validação local do JSONL antes do envio;
• contagem de tokens e um semáforo para o limite de tokens enqueued;
• separação dos resultados por tipo e reenvio apenas das linhas que falharam;
• polling com backoff e registro de created_at nos logs.

E a regra principal: não reenvie um lote inteiro por causa de três linhas que falharam, porque você já pagou pelas que deram certo.