Trabalhos em lote unificados por meio de um gateway de API de IA: filas duráveis, adaptadores de provedor e faturamento em nível de locatário

O processamento em lote não deve ser tratado como uma porta lateral em torno do gateway da API de IA. Se avaliações, enriquecimento de documentos, extração, varreduras de moderação ou trabalhos de incorporação saírem do caminho de solicitação síncrona, eles ainda precisarão de controles de locatário, atribuição de custos, novas tentativas, auditabilidade e análise de uso.

O padrão de implementação é tornar a execução em lote um subsistema de gateway de primeira classe. O gateway deve expor um contrato de trabalho neutro em termos de provedor enquanto se adapta às APIs OpenAI, Anthropic, Gemini e futuras APIs em lote de fornecedores nos bastidores.

O problema do leitor: APIs em lote são semelhantes em intenção, diferentes em operação

Cargas de trabalho tolerantes à latência são uma opção natural para execução em lote. A parte difícil não é decidir se um trabalho pode esperar. A parte difícil é operar o trabalho em lote de forma consistente entre os provedores.

Fatos verificados: a API Batch da OpenAI é assíncrona, lê solicitações de um arquivo carregado, grava respostas em um arquivo de saída e atualmente usa uma janela de processamento de 24 horas. OpenAI lista status como validando, com falha, em_progress, finalizando, concluído, expirado, cancelamento e cancelado. A API Message Batches da Anthropic processa muitas solicitações de mensagens de forma assíncrona, trata cada solicitação de forma independente, requer pesquisa e retorna resultados após o término do processamento. A Anthropic também recomenda valores custom_id significativos porque a ordem dos resultados não é garantida. A API Batch do Gemini expõe métodos de estilo de operação de longa duração, como métodos de listar, cancelar, excluir e atualizar, e sua operação de cancelamento é descrita como de melhor esforço.

Essas diferenças são importantes quando você adiciona requisitos reais de negócios:

• Qual inquilino, cliente, projeto ou chave de API possui cada item?
• O orçamento foi reservado antes do trabalho sair do gateway?
• Quais itens concluídos serão faturáveis se o lote expirar ou for canceladas?
• Como as falhas parciais são repetidas sem duplicar o trabalho bem-sucedido?
• Por quanto tempo os arquivos de resultados podem ser recuperados e o que o gateway deve armazenar?
• Um parceiro pode criar processamento em lote no escopo do cliente sem expor as credenciais do provedor upstream?

A resposta não é ocultar todas as diferenças do provedor. A resposta é normalizar o contrato operacional e, ao mesmo tempo, preservar os metadados nativos do provedor para depuração, reconciliação e suporte.

API pública recomendada: separe os trabalhos em lote das conclusões síncronas

Recomendação: exponha os trabalhos em lote como sua própria superfície de API, não como um sinalizador especial nas conclusões do chat. Uma solicitação síncrona e um trabalho em lote assíncrono têm diferentes semânticas de ciclo de vida, cobrança, repetição e recuperação de resultados.

Um contrato de gateway prático inclui estas operações:

• create_job: crie um trabalho de rascunho de propriedade de um locatário, projeto, chave ou cliente parceiro.
• append_items ou upload_manifest: adicione solicitações individuais com item estável identificadores.
• enviar: validar, reservar orçamento, selecionar provedor, enviar e bloquear o manifesto enviado.
• get_status: retornar contagens normalizadas de tarefas e itens.
• list_results: percorrer resultados, erros e uso de itens normalizados.
• cancelar: solicitar cancelamento, sem promessa imediata rescisão.
• export_usage: exporta registros de custo em nível de trabalho e de item para sistemas analíticos ou de faturamento.

Exemplo de objeto de trabalho público:

{
  "job_id": "job_01j7...",
  "tenant_id": "tenant_acme",
  "customer_id": "cust_123",
  "endpoint": "chat.completions",
  "modelo": "análise grande",
  "status": "em execução",
  "conta": {
    "enviado": 50.000,
    "concluído": 31240,
    "falhou": 180,
    "expirado": 0
  },
  "custo": {
    "estimado": "184,20",
    "reservado": "205,00",
    "resolvido": "117,43",
    "moeda": "USD"
  },
  "criado_em": "2026-08-19T10:00:00Z",
  "submetido_em": "2026-08-19T10:05:00Z",
  "retrieval_deadline": "2026-09-17T10:00:00Z"
}

O objeto público não deve expor IDs de arquivos do provedor, nomes de operações ou erros brutos de upstream por padrão. Eles pertencem aos metadados voltados para o operador.

Use registros de trabalho duráveis ​​como fonte de verdade

Uma camada de lote de propriedade do gateway precisa de um estado durável antes que qualquer coisa seja enviada ao upstream. Não confie nos registros de lote do fornecedor como seu único armazenamento estatal. Os registros do provedor são necessários, mas eles não conhecem a hierarquia do locatário, as reservas de orçamento, os aliases do modelo interno, os clientes parceiros ou os requisitos de análise.

Modelo mínimo de banco de dados

Um esquema útil tem três níveis:

1. Trabalho em lote

batch_jobs
- id_do_trabalho
- inquilino_id
- id_do_projeto
- customer_id anulável-api_key_id
- ponto final
- modelo_solicitado
- provedor_resolvido
- modelo_de_provedor_resolvido
- estado
- contagem_de_itens
- estimados_input_tokens
- estimados_output_tokens
- valor_reservado
- valor_liquidado
- criado_em
- enviado_em
- concluído_em
- expira_em
- prazo_de_recuperação
- cancelamento_requested_at

2. Item em lote

batch_items
- id_do_trabalho
- item_id
- custom_id
- idempotência_chave
- request_hash
- estado
- Provider_request_index anulável
- tokens_estimados
- actual_input_tokens anulável
- actual_output_tokens anulável
- Liquidado_valor anulável
- result_pointer anulável
- error_code anulável
- retry_of_item_id anulável
- criado_em
- assentamento_at

3. Metadados do provedor

batch_provider_metadata
- id_do_trabalho
- provedor
- provedor_batch_id anulável
- input_file_id anulável
- output_file_id anulável
- error_file_id anulável
- nome_da_operação anulável
- ponto final
- região anulável
- status_nativo
- Native_request_counts jsonb
- last_polled_at
- raw_error_pointer nullable

Manter os metadados do provedor separados do contrato de trabalho público permite que o gateway evolua os adaptadores do provedor sem quebrar as APIs voltadas ao locatário.

Exigir identificadores de item estáveis antes do envio

Recomendação: gere um gateway job_id e exija um custom_id por item ou uma chave de idempotência antes do envio. Nunca reconcilie resultados por ordem.

A Anthropic avisa explicitamente que a ordem dos resultados não é garantida e recomenda valores custom_id significativos. Mesmo quando um provedor parece preservar a ordem, um gateway não deve depender dele. Os trabalhos são fragmentados, repetidos, cancelados, parcialmente concluídos e reingeridos. As suposições de pedido eventualmente falham.

Um formato de identificador de item seguro é descritivo, mas não confidencial:

tenantA.invoice_extraction.2026-08-19.row_000381

Evite colocar e-mails, nomes, títulos de documentos ou segredos de clientes brutos em identificadores. Armazene dados de correlação confidenciais em seu próprio banco de dados de locatário, e não em IDs visíveis do provedor.

Normalize status sem apagar detalhes do provedor

As APIs em lote do provedor expõem diferentes ciclos de vida. O gateway deve normalizá-los em uma pequena máquina de estado interna que os painéis, o faturamento e a automação possam entender.

Ciclo de vida normalizado recomendado:

• rascunho: o trabalho existe, mas ainda é editável.
• validação: a validação do gateway ou do provedor está em execução.
• enfileirado: aceito, mas ainda não processamento.
• em execução: o provedor está processando itens.
• finalizando: o provedor concluiu a computação e está preparando os artefatos de resultado.
• concluído: todos os itens aceitos alcançaram sucesso no terminal.
• completed_with_errors: alguns itens foram bem-sucedidos e alguns falharam.
• expirado: a janela do provedor terminou antes de todo o trabalho concluído.
• cancel_requested: o locatário solicitou o cancelamento, mas o trabalho faturável final não foi liquidado.
• cancelled: cancelamento resolvido.
• failed: falha no nível do trabalho impediu a execução útil.

Não recolha os erros do provedor nativo em rótulos genéricos muito cedo. Os operadores ainda precisam de acesso a status nativos, erros de validação, contagens de solicitações, IDs de arquivos e nomes de operações durante a depuração.

Validar em uma matriz de recursos antes do envio

Recomendação: executar a validação de simulação antes da reserva do orçamento e do envio do provedor. O modo em lote não é apenas o modo síncrono com atraso. Alguns modelos, endpoints, recursos de solicitação, regiões e configurações de ferramentas podem não ser compatíveis com a API em lote de um provedor.

Sua matriz de capacidade interna deve verificar:

• Endpoint compatível: bate-papo, mensagens, incorporações, moderação ou geração.
• Elegibilidade do modelo para modo em lote.
• Tamanho máximo do trabalho, contagem de itens, tamanho da solicitação e tamanho do arquivo enviado.
• Se o streaming é proibido.
• Uso de ferramentas e suporte para chamada de função.
• Suporte para saída estruturada ou esquema JSON.
• Suporte para imagem, áudio ou entrada multimodal.
• Restrições de região e residência.
• Retenção do provedor e janelas de recuperação de resultados.
• Limites de taxa e limites de fila específicos do lote.
• Semântica de cancelamento.

Uma boa resposta de comprovação é específico:

{
  "erro": "batch_capability_not_supported",
  "message": "O adaptador em lote do provedor selecionado não suporta respostas de streaming. Remova stream=true ou escolha um endpoint síncrono.",
  "campo": "itens[*].request.stream"}

Isso é mais útil do que aceitar o trabalho e reprová-lo após uma passagem de validação upstream.

Reservar o orçamento do locatário e, em seguida, liquidar o uso real

A execução em lote complica o faturamento porque o gateway pode perder o acesso síncrono ao uso exato até que os arquivos de resultados estejam disponíveis. O padrão seguro é cotar, reservar, enviar, ingerir, liquidar e reconciliar.

Fatos verificados: a OpenAI afirma que o preço da API em lote é oferecido com desconto em comparação com APIs síncronas, e lotes expirados ou cancelados ainda podem retornar trabalho concluído que é faturável. A Anthropic observa que o processamento em lote de alto rendimento pode exceder um pouco o limite de gastos do espaço de trabalho, tornando a reserva do lado do gateway e a pós-liquidação importantes.

Recomendação: reserve o orçamento do locatário antes do envio usando tokens estimados, regras de preço do fornecedor selecionado e uma margem de segurança. Após a ingestão dos resultados, liquide o uso real no nível do item. Se a estimativa for muito alta, libere a reserva não utilizada. Se for muito baixo, aplique a política de excedente configurada pelo locatário.

Eventos práticos do razão:

batch.estimated
lote.reservado
lote.submetido
lote.item.liquidado
lote.item.reembolsado
batch.cancel_requested
lote.expiradobatch.reconciled

O razão de nível de item é essencial. Se 45.000 itens forem concluídos e 5.000 expirarem, o locatário deverá ser cobrado pelo trabalho concluído do provedor, não pelo manifesto original como um único blob indiferenciado.

Crie adaptadores de provedor como tradutores, não como proprietários de lógica de negócios.

Cada adaptador de provedor deve saber como transformar o trabalho de gateway no formato em lote do provedor, enviá-lo, pesquisar ou recuperar status, baixar resultados e mapear resultados nativos de volta ao normalizado registros.

Mantenha a política de locatário fora do adaptador. O adaptador não deve decidir se um cliente tem orçamento suficiente, se um cliente parceiro está suspenso ou se os prompts podem ser armazenados. Essas são decisões de gateway.

Responsabilidades do adaptador

• Renderizar manifestos de solicitação específicos do provedor.
• Fazer upload de arquivos de entrada ou criar operações do provedor.
• Armazenar identificadores do provedor em metadados.
• Mapear o status nativo para o status normalizado.
• Recuperar artefatos de saída e de erro.
• Analisar resultados em nível de item.
• Retornar registros de uso nativos quando disponível.
• Surpreenda erros de repetição versus erros de terminal.

Responsabilidades do gateway

• Autenticar locatário e chave de API.
• Aplicar controles de equipe, projeto e cliente.
• Resolver aliases de modelo e política de roteamento de provedor.
• Validar recursos em lote.
• Reservar e liquidar orçamento.
• Persistir trabalho e item estado.
• Aplicar política de retenção.
• Expor análises e exportações.

Essa separação facilita a adição de um novo provedor sem reescrever o faturamento, as análises ou a governança do locatário.

Ingerir resultados de forma idempotente

A ingestão de resultados é onde muitos sistemas em lote duplicam acidentalmente cobranças ou perdem trabalho parcial. Trate a ingestão como um processo repetível. Deve ser seguro baixar o mesmo arquivo de saída duas vezes, processar a mesma operação do provedor duas vezes ou reproduzir o mesmo evento de webhook duas vezes.

Recomendação: use chaves de idempotência em nível de item e restrições de exclusividade do razão. Um resultado para job_id + custom_id deve ser liquidado exatamente uma vez, mesmo se a ingestão for repetida.

Um fluxo de ingestão robusto:

1. Adquira um bloqueio de curta duração para o trabalho ou artefato de resultado.
2. Busque a saída do provedor e artefatos de erro.
3. Analise registros em eventos de resultado de item normalizados.
4. Corresponda cada registro por custom_id ou item de gateway ID.
5. Grave metadados de resultados e uso em uma transação.
6. Crie um evento de liquidação contábil somente se ainda não existir um.
7. Atualize contagens de tarefas a partir de estados de itens, não de suposições.
8. Libere reserva de orçamento não utilizada quando todos os estados terminais forem conhecidos.

Se webhooks estiverem disponíveis, verifique assinaturas e proteja contra repetição. Se a pesquisa for necessária, use a pesquisa adaptativa: consulte frequentemente perto da conclusão esperada, recue durante períodos de execução longos e pare após a liquidação do terminal.

Tente novamente os itens, não os trabalhos inteiros

Recomendação:tente novamente no nível do item sempre que possível. As novas tentativas de todo o trabalho são simples, mas aumentam o risco de trabalho duplicado e dificultam o faturamento.

Classifique as falhas antes de tentar novamente:

• Erros de validação: geralmente terminam até que a solicitação seja corrigida.
• Erros 5xx do provedor: geralmente podem ser repetidas com espera.
• Falhas de cota ou limite de taxa: tente novamente somente depois que a capacidade for atingida. disponível.
• Bloqueios de segurança: não tente novamente cegamente; caminho para o tratamento da política.
• Itens expirados: podem ser tentados novamente em um novo trabalho se o inquilino ainda quiser que o trabalho e o orçamento permitirem.

Uma nova tentativa deve criar um novo item vinculado ao original:

{
  "item_id": "item_retry_002",
  "retry_of_item_id": "item_001",
  "custom_id": "tenantA.eval.row_901.retry_1"
}

Não reenvie itens concluídos apenas porque eles faziam parte de um trabalho que terminou como completed_with_errors ou expired.

Decida o que armazenar: resultados brutos, ponteiros ou hashes

Os sistemas em lote são locais tentadores para acumular prompts e saídas. Isso pode ser útil para exportações e depuração, mas aumenta a responsabilidade pela retenção de dados.

Recomendação: torne a política de armazenamento configurável pelo locatário. Para cargas de trabalho confidenciais, armazene metadados, hashes, uso e ponteiros de resultados em vez de prompts e saídas brutas.Para cargas de trabalho menos confidenciais, o armazenamento normalizado de resultados pode ser aceitável se as janelas de retenção, os controles de acesso e os fluxos de trabalho de exclusão forem claros.

Rastreie pelo menos:

• Se a entrada bruta foi armazenada.
• Se a saída bruta foi armazenada.
• Onde os artefatos de resultado do provedor residem.
• Prazo de recuperação do provedor.
• Prazo de exclusão do gateway.
• Hash de solicitação e resposta para auditoria sem exposição de conteúdo.

Fato verificado: Os resultados em lote dos estados antrópicos ficam disponíveis por 29 dias após a criação e isolados no espaço de trabalho. Esse tipo de janela de recuperação específica do provedor deve ser refletida nos metadados do gateway e nas exportações voltadas para o locatário.

Exponha análises que correspondam à forma como as equipes operam.

A análise em lote deve existir tanto no nível do trabalho quanto no nível do item. O proprietário do produto deseja saber se um enriquecimento noturno foi concluído. Um administrador financeiro deseja custos por inquilino, modelo e cliente. Um engenheiro deseja saber qual classe de falha tentar novamente.

As métricas úteis incluem:

• Contagem de itens enviados, concluídos, com falha, expirados e cancelados.
• Custo estimado versus custo liquidado.
• Orçamento reservado ainda retido.
• Tokens de entrada e saída por provedor e modelo.
• Indicadores de acertos no cache onde os provedores os expõem.
• Contagem de novas tentativas e novas tentativas com êxito. taxa.
• Tempo médio em estados de fila, execução e finalização.
• Principais erros de validação por endpoint e modelo.
• Atribuição do cliente parceiro.

Para usuários da Partner API, exponha trabalhos em lote como recursos no escopo do cliente. Isso permite que agências e criadores de SaaS ofereçam processamento de IA off-line, mantendo credenciais de provedor upstream, reconciliação de faturamento e tratamento de limite de taxa dentro do gateway.

Compensações para tornar explícita

abstração do gateway versus capacidade específica do provedor: um contrato unificado simplifica a integração, mas não pode tornar todos os recursos do provedor idênticos. Mantenha os erros de capacidade explícitos.

Reserva de orçamento versus precisão da estimativa: a reserva protege os inquilinos de trabalhos descontrolados, mas as estimativas podem estar erradas. O razão deve suportar ajustes, reembolsos e tratamento de excedentes.

Pesquisas versus webhooks: as pesquisas são simples e confiáveis, mas podem desperdiçar chamadas de API e atrasar a conclusão. Webhooks são mais rápidos, mas exigem verificação de assinatura, proteção de reprodução e monitoramento.

Armazenamento de resultados brutos versus minimização de retenção: o armazenamento de resultados normalizados melhora as exportações e análises, mas aumenta a carga de conformidade. Locatários sensíveis podem preferir ponteiros e hashes.

Lotes grandes versus lotes em partes: lotes grandes podem melhorar a eficiência do fornecedor, mas pedaços menores reduzem o raio de explosão e facilitam as novas tentativas.

Lista de verificação de implementação

• Crie uma superfície de API de trabalho em lote separada.
• Persista registros de trabalho e item antes do envio do provedor.
• Exigir IDs de trabalho de gateway e IDs personalizados por item.
• Normalize status enquanto armazena metadados de provedor nativos.
• Crie uma matriz de capacidade para cada adaptador de lote de provedor.
• Valide os manifestos antes de reservar o orçamento.
• Reserve o orçamento do locatário antes do envio.
• Estabeleça o uso real no nível do item após a ingestão.
• Torne a ingestão de resultados idempotente.
• Tente novamente os itens com falha seletivamente, não os trabalhos inteiros. cegamente.
• Rastreie os prazos de recuperação do provedor e a política de retenção do gateway.
• Exponha análises de trabalhos e itens a inquilinos e clientes parceiros.

Previsões: para onde esse padrão está indo

Previsão: a execução em lote se tornará uma parte normal da infraestrutura de automação de IA, não apenas um mecanismo de desconto. À medida que as equipes executam mais avaliações, tarefas de limpeza de dados, análises de segurança e pipelines de enriquecimento, elas esperam que as cargas de trabalho assíncronas tenham a mesma governança que as chamadas de API síncronas.

Previsão: as APIs em lote do provedor continuarão a divergir de maneiras úteis. Alguns otimizarão arquivos, outros para operações de longa duração e outros para conjuntos de dados gerenciados ou retornos de chamada de eventos. Uma camada de adaptador de gateway se tornará mais valiosa, e não menos, porque o contrato operacional acima dos adaptadores pode permanecer estável.

Conclusão acionável

Não inclua o processamento em lote em um gateway de API de IA como uma saída de emergência específica do provedor. Construa-o como um subsistema durável com seus próprios registros de trabalho, identificadores de item, modelo de status, adaptadores de provedor, reserva de orçamento, ingestão idempotente e análises.

A escolha de design mais importante é a contabilidade em nível de item. Depois que cada solicitação dentro de um lote tiver uma identidade estável, o gateway poderá reconciliar resultados não ordenados, tentar novamente apenas trabalhos com falha, cobrar apenas trabalhos concluídos do fornecedor e mostrar aos locatários o que aconteceu.Essa é a diferença entre enviar arquivos para um provedor e operar uma API multimodelo confiável para cargas de trabalho assíncronas.

Leitura relacionada

• citar, reservar, liquidar e reconciliar padrão de faturamento da API de IA
• análise de uso em nível de gateway e design de registro de token
• quando cargas de trabalho tolerantes à latência se ajustam ao processamento em lote