Para recuperar falhas na Gemini Batch API sem repetir os itens que deram certo, mantenha um manifesto das entradas, identifique cada pedido com uma chave estável e reconcilie os resultados individualmente. Monte um novo arquivo apenas com os pedidos cuja falha foi confirmada e cuja causa permite nova tentativa. Um lote concluído não dispensa conferir a resposta de cada item.
O procedimento abaixo usa a Gemini API documentada em Google AI for Developers. A seleção de falhas, o registro das tentativas e o bloqueio de duplicações são responsabilidades da sua aplicação. Não trate o nome visível de um lote como proteção contra reenvio. Para conhecer outros usos do produto, consulte a página de integrações com Google Gemini.
Resumo rápido
- Salve o pedido original e sua versão antes de criar o lote.
- Use a chave do item para relacionar entrada e saída, com validação de duplicatas.
- Separe sucesso técnico, resultado utilizável, erro confirmado e resultado desconhecido.
- Retente somente falhas elegíveis, com teto de tentativas e orçamento.
- A criação do lote não é idempotente: um timeout não autoriza recriar às cegas.
- Preserve os resultados aprovados e mantenha histórico das tentativas por item.
Entender as duas camadas de resultado
Um trabalho em lote tem estado próprio; cada pedido também tem um desfecho. O guia oficial da Batch API oferece envio inline ou por arquivo JSONL, no qual cada linha contém uma chave e uma requisição. Essa chave aparece no resultado para permitir a associação. A documentação também orienta verificar falhas individuais e alerta que repetir a criação gera outro trabalho.
A referência da Batch API descreve respostas inline que carregam metadados e uma saída de erro ou de resposta. Os nomes usados pelo SDK e pelo formato de arquivo precisam ser conferidos no adaptador escolhido. Não copie um exemplo REST para uma classe Python supondo que todos os campos terão a mesma grafia.
Na prática, se o arquivo de saída foi baixado, isso prova apenas que você tem um arquivo. É necessário validar a estrutura, identificar cada item e comparar com o manifesto. Da mesma forma, uma resposta recebida pode não servir à tarefa: o texto pode estar vazio, incompleto ou fora do esquema esperado. Registre esse resultado como problema de qualidade ou de contrato, separado de uma falha de transporte.
Construir um manifesto antes de enviar
O manifesto é a lista controlada pela sua aplicação que define o que deveria acontecer. Ele deve ser criado antes do upload e conter o identificador de negócio, a chave enviada, a versão da entrada e a configuração de geração. Sem isso, a recuperação depende de reconstruir prompts a partir do estado atual dos sistemas, o que pode alterar a solicitação sem deixar rastro.
| Campo local | Exemplo ilustrativo | Finalidade |
|---|---|---|
| item_id | produto-azul-42 | Identificar o objeto de negócio |
| versao_entrada | catalogo-v3 | Distinguir mudanças no conteúdo |
| key | produto-azul-42-v3 | Relacionar a linha ao resultado |
| hash_pedido | Resumo criptográfico do JSON canônico | Detectar alteração do pedido |
| tentativa | 1 | Controlar histórico e limite |
| job_name | Valor retornado pela API | Consultar o trabalho criado |
Escolha chaves sem CPF, telefone ou endereço de e-mail. Um identificador opaco basta para correlação e expõe menos dados em logs. Dentro de cada arquivo, rejeite chaves repetidas antes do envio. Entre tentativas, mantenha a relação com o mesmo item lógico e registre o novo trabalho em uma tabela de tentativas separada.
Se mudar o prompt, o modelo, o documento ou os parâmetros relevantes, crie uma nova versão. Uma correção de entrada não é repetição idêntica da tentativa anterior. Essa distinção permite comparar resultados sem sobrescrever silenciosamente o que já foi aprovado. Para entradas que contêm dados pessoais, aplique as medidas de mascaramento antes do envio a APIs externas.
Reconciliar a saída sem presumir sucesso
Faça download e arquive o resultado em local restrito antes de processá-lo. Calcule um resumo do arquivo para auditoria e registre a conclusão da leitura somente quando todas as linhas forem examinadas. Se a conexão cair no meio do download, um arquivo parcial não deve ser interpretado como conjunto final de resultados.
Um adaptador deve converter a resposta recebida para um formato interno simples: chave, resposta, erro e metadados úteis. Mantenha também a referência ao registro original, para investigar divergências sem perder informação. Com esse formato, a regra de negócio fica independente de nomes específicos de cada biblioteca.
esperados = conjunto de chaves do manifesto
vistos = conjunto vazio
para cada registro normalizado:
conferir se a chave pertence ao manifesto
recusar chave repetida e marcar anomalia
se existe erro:
classificar e registrar a falha
senão, se a resposta passa na validação:
salvar resultado aprovado sem sobrescrever outra versão
senão:
encaminhar para revisão de qualidade
adicionar chave a vistos
pendentes_de_reconciliacao = esperados menos vistosO conjunto de chaves ausentes não é automaticamente a lista de reenvio. Uma ausência pode vir de leitura incompleta, associação incorreta ou inconsistência que precisa ser investigada. Marque esses itens como desconhecidos, confirme o estado final do trabalho e releia o artefato completo. Só retente depois de estabelecer um motivo seguro para fazê-lo.
Compare também contagens: total esperado, respostas aprovadas, erros, revisões de qualidade e desconhecidos. A soma precisa fechar sem duplicatas. Contadores agregados do fornecedor ajudam a localizar divergências, mas não substituem a lista por chave. Um painel que mostra apenas “lote concluído” esconde exatamente os casos que a recuperação precisa resolver.
Escolher quais falhas admitem nova tentativa
O guia de solução de problemas do Gemini recomenda espera exponencial para erros que indiquem retentativa, como esgotamento de recursos e indisponibilidade. Classifique a causa pelo código e pelo contexto, sem buscar apenas palavras na mensagem. Não misture códigos HTTP com códigos de status internos que podem aparecer nas saídas.
Crie categorias locais: transitório, entrada inválida, configuração ou acesso, qualidade e desconhecido. Um erro transitório pode ser candidato a repetição após espera. Um parâmetro inválido exige correção. Uma falha de acesso pede intervenção no projeto ou credencial. Um bloqueio de conteúdo exige revisão da tarefa e das regras aplicáveis, sem tentativas de contornar proteções por insistência.
A documentação de limites informa que Batch tem cotas próprias. Confira os limites vigentes do projeto e do modelo antes de programar o reenvio. Não crie vários lotes menores só para tentar escapar de uma cota. A fila de recuperação deve compartilhar o controle de admissão com as tarefas novas, para que uma onda de falhas não consuma toda a capacidade disponível.
Defina um número máximo de tentativas, um prazo de recuperação e um orçamento de consumo. Acrescente variação aleatória à espera para evitar que vários trabalhadores retomem juntos. Esses parâmetros são decisões da operação, não garantias do fornecedor. Depois do teto, encaminhe o item com contexto suficiente para uma pessoa decidir o próximo passo.
Criar o lote de recuperação com controle de concorrência
Selecione as falhas elegíveis em uma transação local e reserve os itens para um único processo. Gere o arquivo a partir das requisições originais preservadas, sem incluir sucessos. Salve uma lista de associação entre o lote de recuperação e suas chaves antes de iniciar a chamada externa. Isso permite explicar por que cada item foi incluído.
A criação precisa de cuidado especial. Se a chamada termina com timeout, o servidor pode ter criado o trabalho mesmo que a aplicação não tenha recebido o nome. Marque a criação como incerta, investigue os trabalhos existentes e reconcilie o resultado antes de enviar outra solicitação. Um nome descritivo ajuda a operação, mas não deve ser tratado como chave de idempotência oferecida pela API.
Quando a criação retorna normalmente, salve imediatamente o identificador do trabalho e vincule as tentativas. Depois, acompanhe esse trabalho até o estado final e execute a mesma reconciliação por item. Não crie um caminho especial que confie mais nas retentativas do que no lote original: elas podem apresentar as mesmas classes de erro.
Para aplicar resultados no sistema de negócio, use unicidade por item e versão. Salvar o resultado e marcar sua aplicação devem ocorrer em uma transação quando compartilham banco. Se a aplicação exige publicar em outro sistema, separe geração de publicação e registre a ação externa. Um lote de textos não deveria disparar publicação automática apenas porque todos os pedidos retornaram uma resposta.
Guarde indicadores por etapa: itens aprovados na primeira tentativa, falhas recuperadas, entradas corrigidas, resultados desconhecidos e itens encerrados por limite. Faça a correlação com job e chave sem colocar prompts inteiros nos logs. O guia de tracing de chamadas de modelos ajuda a organizar essa investigação entre serviços.
Exemplo: catálogo de uma loja em Recife
Imagine uma loja fictícia de artigos para casa em Recife que prepara rascunhos de descrições para seu catálogo. Cada produto tem uma ficha revisada e uma versão. A equipe cria um manifesto e envia o trabalho em lote; as descrições devem voltar para revisão humana, sem publicação direta na loja virtual.
Na conciliação, parte dos itens passa na validação. Alguns têm erro transitório confirmado, outros têm pedido malformado, e um conjunto precisa de revisão porque a descrição omitiu informações obrigatórias. Os resultados aprovados ficam salvos. O recuperador gera outro arquivo somente para as falhas transitórias elegíveis. As entradas malformadas voltam à equipe técnica; os textos incompletos seguem para revisão editorial.
Um produto é atualizado enquanto a recuperação está em andamento. A saída da versão antiga continua identificada como antiga e não sobrescreve a ficha nova. A equipe decide se aproveita o texto ou cria uma geração para a nova versão. Essa regra evita que uma tentativa demorada reverta uma correção recente do catálogo.
No ensaio, a equipe interrompe o download, repete a importação do mesmo arquivo e executa dois recuperadores ao mesmo tempo. O resultado esperado é observável: leitura incompleta fica pendente, importação repetida preserva o resultado já salvo e apenas um recuperador assume cada falha. Não há estimativa inventada de economia; o teste comprova a rastreabilidade e a seleção correta do reenvio.
Erros comuns
- Reenviar o arquivo inteiro por conveniência. A seleção deve vir do registro de falhas elegíveis, excluindo itens aprovados.
- Confundir ausência com erro confirmado. Primeiro investigue a integridade do arquivo e o estado do trabalho.
- Reconstruir prompts com dados atuais. Preserve a entrada enviada ou declare uma nova versão.
- Repetir criação após timeout sem reconciliar. A operação pode ter sido aceita e gerar um segundo trabalho.
- Sobrescrever um sucesso com uma tentativa atrasada. Aplique regras explícitas de item, versão e aprovação.
- Retentar indefinidamente. Use teto, prazo e responsável pelas exceções.
Um checklist de liberação deve incluir chave desconhecida, chave repetida, arquivo vazio, resultado não utilizável, interrupção após salvar e concorrência na seleção. Registre o desfecho esperado antes do teste. Assim a aprovação depende do comportamento do recuperador e não apenas de a chamada à API funcionar.
Perguntas frequentes
Preciso reenviar os itens que já foram aprovados?
Não para recuperar outras falhas. Preserve os sucessos e forme o novo arquivo a partir das falhas elegíveis. Se quiser gerar outra versão por mudança de conteúdo, registre isso como nova operação.
Uma resposta sem erro já pode ser publicada?
Ela ainda precisa cumprir os critérios do negócio. Valide estrutura, campos obrigatórios e qualidade. Em conteúdo de catálogo, a conferência das características do produto deve ocorrer antes de publicar.
Posso identificar itens apenas pela posição da linha?
A referência descreve ordenação em formatos de saída, mas uma chave explícita melhora a auditoria entre arquivos e tentativas. Use a chave quando disponível e valide a associação com o manifesto, inclusive ao adaptar exemplos de SDK.
Todo erro de cota deve ser repetido imediatamente?
Não. Leia o motivo, confira os limites ativos e programe espera ou intervenção conforme a causa. Repetições imediatas podem ocupar a fila sem resolver o bloqueio.
Como tratar resultado que nunca apareceu no arquivo?
Mantenha o item como desconhecido até reconciliar. Confirme download completo, chaves e estado final. A ausência por si só não prova que uma nova solicitação seja segura.
