Batch API de LLM: como processar grandes volumes em lote

Batch API de LLM: como processar grandes volumes em lote

Use a batch API de LLM quando a tarefa não precisa de resposta na hora e o volume é grande: classificação, resumo e extração em massa são os casos típicos. Você envia um arquivo com muitas requisições, o provedor processa de forma assíncrona e devolve os resultados depois, com um identificador por item. O que decide se o lote funciona é o tratamento de falhas parciais: cada item precisa ser rastreável, validado e reenviável sozinho.

Principais pontos

• Lote serve para trabalho que pode esperar: se ninguém está aguardando a resposta na tela ou no WhatsApp, vale considerar a batch API.
• Em geral, os provedores oferecem custo por token menor no modo em lote em troca de prazo mais flexível. Confirme as condições vigentes na documentação do seu provedor.
• Um lote quase nunca falha ou acerta por inteiro. Planeje para itens com erro, itens inválidos e itens que ficaram sem resultado.
• Cada requisição precisa de um identificador próprio, estável e ligado ao registro de origem, para reconciliar resultados e reenviar só o que falhou.
• Antes de rodar o volume todo, teste uma amostra pequena e defina o que conta como resposta aceitável.

O que é processamento em lote e como ele difere da chamada normal?

Na chamada normal (síncrona), seu sistema envia uma requisição e espera a resposta. É o modelo de um atendente virtual, de um assistente dentro de um sistema ou de qualquer fluxo em que uma pessoa aguarda. A latência importa, então você paga pela prontidão.

Na batch API, você monta um conjunto de requisições, envia tudo junto e consulta o status depois. O provedor processa quando tem capacidade, dentro de uma janela de conclusão que ele define. Quando termina, você baixa um arquivo de resultados. Em geral, a ordem dos resultados não é garantida, por isso cada item carrega um identificador que você mesmo atribui.

Na prática, isso muda três coisas no desenho do sistema:

• Você troca tempo por custo e por folga operacional: o resultado chega mais tarde, mas o processamento não disputa capacidade com o tempo real.
• Você precisa de estado: quais itens foram enviados, em qual lote, com qual versão de instrução e com qual resultado.
• Você precisa de uma etapa de reconciliação, que compara o que foi pedido com o que voltou.

Os nomes dos campos, os limites de tamanho do lote e a janela de conclusão variam entre provedores e mudam com o tempo. Trate a documentação oficial do provedor como a fonte desses detalhes e não copie limites de artigos, inclusive deste.

Quais tarefas devem ir para lote e quais não devem?

A pergunta que organiza a decisão é simples: alguém precisa disso agora? Se a resposta é não, e há muitos itens parecidos, lote é candidato forte. Use este guia de decisão como lista de verificação:

• Vai para lote: classificar um acervo de mensagens, tickets ou avaliações por tema, urgência ou sentimento, quando o resultado alimenta um relatório e não uma resposta imediata.
• Vai para lote: resumir um histórico grande de conversas, atas ou documentos para consulta posterior.
• Vai para lote: extrair campos de muitos documentos já recebidos, como notas, contratos ou laudos. Para o desenho dos campos e da conferência humana, veja extrair dados de PDF com IA.
• Vai para lote: enriquecer cadastros, padronizar descrições de produtos ou revisar a qualidade de uma base de conhecimento.
• Vai para lote: rodar avaliações offline, comparando versões de instrução sobre o mesmo conjunto de exemplos.
• Fica em tempo real: conversa com cliente, em que a pessoa espera a resposta.
• Fica em tempo real: qualquer etapa que bloqueia uma ação humana imediata, como validar um dado no momento do cadastro.
• Fica em tempo real: fluxos em que o resultado de um item decide a pergunta seguinte ao mesmo usuário.

Existe também um meio-termo: tarefas que o negócio chama de urgentes, mas que toleram atraso. Um resumo de fim de dia, por exemplo, não precisa ser gerado a cada mensagem. Vale perguntar à área responsável qual atraso é realmente aceitável antes de decidir pelo modo síncrono por hábito.

Como montar um lote, passo a passo?

Um plano enxuto, que serve para a maioria dos casos de classificação, resumo e extração:

• Defina a tarefa e o formato de saída. Escreva a instrução, o esquema esperado da resposta (por exemplo, categoria dentro de uma lista fechada) e o que fazer quando o dado não existe no texto.
• Selecione os registros. Liste de onde vêm, quais campos entram no modelo e quais ficam de fora. Dados pessoais desnecessários não devem ir para a requisição.
• Atribua um identificador por item. Use um valor estável, ligado ao registro de origem e à versão da instrução, para que reenviar o mesmo item não crie duplicidade.
• Rode uma amostra pequena em modo síncrono ou em um lote de teste. Compare a saída com o que uma pessoa da área consideraria correto.
• Envie o lote completo e registre: identificador do lote, data de envio, versão da instrução, modelo usado e quantidade de itens enviados.
• Consulte o status em intervalos razoáveis. Não faça consulta em laço apertado; o processamento é assíncrono por definição.
• Baixe os resultados e reconcilie: cada identificador enviado deve ter um destino, seja sucesso, erro ou ausente.
• Valide as saídas antes de gravar no sistema de destino. Esquema inválido, categoria fora da lista e campos vazios vão para uma fila de revisão ou de reenvio.
• Reenvie apenas os itens que falharam, em um novo lote, mantendo os identificadores originais ligados à tentativa.
• Feche o ciclo com um relatório curto: enviados, concluídos, rejeitados pela validação, reenviados e pendentes de revisão humana.

Como tratar falhas parciais sem reprocessar tudo?

Falha parcial é o comportamento normal de um lote grande, não a exceção. Alguns itens retornam erro do provedor, outros expiram dentro da janela, outros voltam com uma resposta que não respeita o formato pedido. Cada situação pede uma ação diferente.

Separe as falhas em categorias:

• Erro de requisição: o item estava mal formado, grande demais ou com conteúdo recusado. Reenviar sem mudar nada repete o erro. Corrija o item ou envie para revisão humana.
• Erro transitório do provedor: indisponibilidade ou sobrecarga. Reenviar costuma resolver, com espera crescente entre tentativas e um limite de tentativas.
• Item expirado ou cancelado: o lote não terminou a tempo para aquele item. Reenvie em um novo lote.
• Resposta inválida: o item foi processado, mas a saída não passa na validação. Aqui o problema costuma estar na instrução ou nos dados, não na infraestrutura.
• Resposta válida porém duvidosa: passa no formato, mas contradiz o texto de origem ou tem baixa consistência. Só aparece com amostragem e conferência humana.

Algumas regras tornam o reenvio seguro:

• Idempotência: reenviar o mesmo item não pode gravar duas vezes no destino. A ideia é a mesma de APIs de pagamento que aceitam uma chave de idempotência por operação, como descreve a documentação de requisições idempotentes da Stripe. Você pode aplicar o princípio usando o identificador do item como chave de gravação.
• Limite de tentativas: após algumas rodadas, o item sai da automação e vai para uma pessoa. Um laço de reenvio sem teto vira custo sem fim.
• Estado explícito por item: pendente, enviado, concluído, rejeitado, em revisão. Sem isso, ninguém sabe o que falta.
• Lote de reenvio separado: não misture itens novos e reenviados no mesmo lote sem registrar a origem. Facilita auditar.

Se o seu orquestrador é uma ferramenta de fluxo, vale aplicar as mesmas práticas de erros e retentativas no n8n: erros separados por tipo, espera entre tentativas e um caminho de saída para revisão humana.

Cenário ilustrativo: classificar um acervo de mensagens

Este é um cenário ilustrativo, sem relação com nenhuma empresa real. Uma loja acumulou um histórico grande de mensagens de clientes e quer saber os principais motivos de contato por trimestre, para ajustar o catálogo e o atendimento. Ninguém precisa da resposta de cada mensagem agora.

O time define uma lista fechada de categorias, mais uma categoria "outros" e uma regra: se a mensagem for ambígua, classificar como "outros" em vez de adivinhar. Cada mensagem recebe um identificador ligado ao registro original. Antes do lote completo, uma pessoa revisa uma amostra das classificações e ajusta a instrução onde as categorias se confundiam.

O lote é enviado. Quando os resultados chegam, a reconciliação mostra três grupos: itens concluídos e válidos, itens com erro do provedor e itens cuja categoria veio fora da lista. Os primeiros são gravados. Os segundos entram em um lote de reenvio. Os terceiros vão para uma fila pequena de revisão, e os padrões que aparecem ali alimentam uma nova versão da instrução. O relatório final informa quantos itens ficaram sem classificação, para que ninguém confunda "sem erro" com "completo".

O ganho aqui não é velocidade. É poder processar um acervo grande com custo menor e sem ocupar a capacidade do atendimento em tempo real, mantendo rastreabilidade de cada decisão do modelo.

Como cuidar de custo, privacidade e qualidade?

Custo. O modo em lote costuma ser mais barato por token, mas o custo total depende do tamanho de cada item e da instrução repetida em todos. Entender o que é um token ajuda a estimar o volume: veja o que são tokens em IA. Instruções longas e idênticas em todos os itens são candidatas a cache de prompt, quando o provedor oferece essa combinação com o modo em lote. A documentação de prompt caching da Anthropic explica o mecanismo; confira nela se e como ele se aplica ao seu cenário. Meça o custo por item concluído e válido, não só o custo do lote, porque itens reenviados e revisados também entram na conta.

Privacidade. Um lote costuma concentrar muitos dados pessoais em um único envio, o que aumenta o impacto de um erro. Envie só os campos necessários, anonimize o que for possível e registre a finalidade do tratamento. Se o provedor processa os dados fora do Brasil, a LGPD tem exigências específicas; o texto sobre transferência internacional de dados com IA detalha o que verificar. Para orientações oficiais, a página da ANPD é o ponto de partida.

Qualidade. Como ninguém acompanha o lote item a item, a avaliação precisa ser planejada antes. Monte um conjunto de exemplos com a resposta esperada, rode a instrução sobre ele e só então escale. O guia de avaliações da OpenAI mostra uma forma estruturada de pensar nisso, e a lógica vale para qualquer provedor. Depois do lote, amostre uma parte dos resultados válidos para conferência humana; formato correto não garante conteúdo correto.

Como esse trabalho se encaixa no método do Juan Carlo?

O processamento em lote segue a mesma sequência de qualquer automação com IA. Mapear: entender de onde vêm os dados, quem usa o resultado e qual atraso é aceitável. Limitar: definir quais campos o modelo recebe, quais categorias são permitidas e o que acontece quando há dúvida. Pilotar: rodar um fluxo real em escala reduzida, com registro de cada item e uma métrica de sucesso combinada de antemão. Transferir: entregar a operação com a documentação, o relatório de reconciliação e a decisão clara entre expandir, ajustar ou parar.

Do que é documentação oficial, o que é experiência de implementação e o que é hipótese: a existência de APIs em lote e o princípio de idempotência estão documentados pelos provedores. A divisão em categorias de falha e o fluxo de reconciliação descritos acima são práticas de implementação. Já a ideia de que sua tarefa específica tolera atraso é uma hipótese, e só o piloto confirma.

Perguntas frequentes

Quando vale mais a pena usar batch API do que chamadas normais? Vale quando há muitos itens parecidos, ninguém espera a resposta em tempo real e o resultado alimenta um relatório, uma base ou uma etapa posterior. Se uma pessoa está esperando na tela ou na conversa, mantenha a chamada síncrona. Em caso de dúvida, pergunte à área responsável qual atraso é aceitável.

O que fazer quando parte do lote volta com erro? Classifique o erro antes de reenviar. Falhas transitórias podem ser reenviadas com espera e limite de tentativas; itens mal formados precisam de correção ou de revisão humana. Reenvie só os itens que falharam, mantendo o mesmo identificador para evitar gravações duplicadas.

A ordem dos resultados é a mesma da ordem de envio? Não conte com isso. Em geral, os provedores devolvem os resultados sem garantia de ordem e esperam que você relacione cada resposta ao pedido pelo identificador que você mesmo definiu. Confirme esse comportamento na documentação do provedor que você usa.

Posso enviar dados de clientes em um lote? Pode, desde que haja base legal, finalidade clara e só os campos necessários. Como o lote concentra muitos registros, um erro de configuração tem impacto maior. Avalie anonimização, o local de processamento do provedor e as exigências da LGPD antes do envio.

Fontes

• Stripe: requisições idempotentes
• OpenAI: guia de avaliações (evals)
• Anthropic: prompt caching
• ANPD: Autoridade Nacional de Proteção de Dados