Processamento em lote

Batch é o recurso da AIVAX para executar o mesmo fluxo de trabalho de IA em muitos itens independentes. Ele transforma uma lista de entradas em uma fila processada em segundo plano com instruções fixas, saída estruturada, validação opcional, acompanhamento de progresso, tentativas de nova execução e exportação de resultados.

Use Batch quando você tem dezenas, centenas ou milhares de registros que precisam passar pelo mesmo raciocínio: classificar leads, extrair campos de texto, enriquecer registros, resumir documentos curtos, avaliar respostas, moderar conteúdo, gerar dados estruturados ou invocar ferramentas integradas para cada linha de uma lista.

O que o Batch resolve #

Processar muitos itens com IA geralmente requer uma fila, tratamento de erros, novasativas, validação JSON e exportação de resultados. O Batch consolida essas partes na AIVAX.

Na prática, ele resolve principalmente:

• Processamento repetível: a mesma instrução, modelo e esquema são aplicados a todos os itens.
• Execução assíncrona: o trabalho continua em segundo plano, sem manter a solicitação aberta.
• Saída estruturada: cada item pode ser exigido a retornar um objeto compatível com um JSON Schema.
• Correção e validação: o AIVAX tenta reprocessar respostas inválidas e pode executar uma segunda etapa de validação.
• Operação em escala: trabalhos podem ser iniciados, pausados, retomados, monitorados, filtrados, limpos, reenviados para nova tentativa e exportados.
• Controle operacional: a interface mostra progresso, falhas, confiança e eventos do trabalho.

Quando usar #

Use Batch quando os itens podem ser processados independentemente e não precisam compartilhar memória. Bons exemplos são uma linha por cliente, URL, produto, ticket, mensagem, documento curto, trecho de contrato ou registro bruto.

Batch é uma boa escolha quando:

• o mesmo prompt se aplica a todos os itens;
• você precisa de resultados tabulares ou JSON para consumo posterior;
• o tempo de resposta pode ser assíncrono;
• você quer rastrear erros e tentar novamente apenas os itens problemáticos;
• você deseja usar ferramentas integradas, como busca web, para cada item;
• você precisa medir confiança e taxa de sucesso por execução.

Não use Batch para conversas em tempo real, fluxos onde um item depende da resposta do item anterior, indexação de documentos para RAG ou tarefas puramente determinísticas que não requerem um modelo de IA. Para indexar conhecimento pesquisável, use RAG collections. Para uma resposta imediata a um usuário, use inference.

Conceitos #

Workflow #

O workflow é a receita de processamento. Ele define como os itens futuros serão tratados:

• título;
• instruções de processamento;
• modelo ou gateway de IA;
• esquema de resultado esperado;
• ferramentas integradas habilitadas;
• instruções de validação; e
• comportamento de tentativa de nova execução e tratamento de erros.

Alterar um workflow afeta trabalhos e itens subsequentes processados com essa configuração. Use workflows separados quando a instrução, esquema, modelo ou regras de validação mudarem de forma significativa.

Modelo e roteamento #

Um workflow processa seus itens com um modelo integrado ou com um gateway de IA. Ambos são escolhidos na configuração Model do workflow e referenciados por modelName na API.

Batch otimiza custos quando o workflow não usa um gateway de IA: os itens são sempre roteados com a preferência de roteamento Cheapest provider routing preference, que seleciona o provedor disponível com o menor preço de token de entrada e saída para aquele modelo. O padrão Balanced não é aplicado neste caso, portanto a seleção de provedor pode diferir de outros recursos que solicitam o mesmo modelo. Quando apenas um provedor está disponível ou compatível com a solicitação, o roteamento não altera o resultado.

Crie um AI Gateway e selecione‑o no workflow para usar a preferência Balanced, Fastest ou Quality, restringir quais provedores são tentados, ou aplicar instruções fixas, ferramentas e configuração RAG a cada item.

Trabalho (Job) #

Um job é uma execução concreta criada a partir de um workflow. Ele agrupa os itens de uma carga de trabalho e mantém o estado, eventos e métricas da carga.

Um job representa a carga de trabalho enquanto está sendo preparado, processado, pausado ou concluído. Consulte a Referência de API embutida para os estados de job suportados.

Item #

Um item é uma linha da lista importada. Cada linha se torna uma entrada independente enviada ao modelo com as instruções do workflow.

Cada item registra seu resultado de processamento, saída, confiança e detalhes de validação. Consulte a Referência de API embutida para os estados de item suportados.

Como usar no console #

No console da AIVAX, vá para Batch.

Criar um workflow #

Em Workflows, crie um workflow e configure:

1. Basic: defina um título, a instrução de processamento e o JSON Schema do resultado.
2. Behavior: escolha as capacidades de assistente suportadas para o workflow.
3. Validation: habilite validação quando a resposta precisar ser verificada contra regras de negócio.
4. Handling: configure o comportamento de tratamento de erros do workflow.

Escreva a instrução como uma regra geral, não como uma única pergunta. O item importado será a entrada variável.

Exemplo de instrução:

Classifique a empresa fornecida na entrada. Retorne o setor provável, uma breve justificativa e sinais encontrados no texto. Se a entrada não contiver informações suficientes, use o setor "Undefined".

Exemplo de esquema:

{
  "type": "object",
  "properties": {
    "sector": { "type": "string" },
    "reason": { "type": "string" },
    "signals": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["sector", "reason", "signals"],
  "additionalProperties": false
}

Criar e executar um job #

Depois de criar o workflow, crie um job para a carga que deseja processar. Novos jobs são criados no estado Paused para que você possa importar e inspecionar a carga antes de iniciar o processamento.

Você pode importar itens em quatro modos:

• lines: lê um arquivo de texto enviado e importa cada linha não vazia como um item.
• files: importa cada arquivo de texto simples enviado como um item.
• zip: importa cada entrada de texto simples em um arquivo ZIP enviado como um item.
• text: importa o campo de texto enviado como um único item.

Linhas podem ser texto simples, CSV delimitado, URLs, IDs, JSON compacto ou qualquer formato que a instrução saiba interpretar. Para entradas estruturadas baseadas em linhas, prefira JSONL: um objeto JSON por linha.

Exemplo:

{"name":"Company A","description":"B2B auto-parts marketplace"}
{"name":"Company B","description":"Office specializing in employment contracts"}
{"name":"Company C","description":"Regional pharmacy chain"}

Com os itens importados, inicie o job. A tela do job permite monitorar:

• progresso geral;
• itens pendentes, concluídos e falhos;
• confiança média;
• eventos do job;
• itens processados mais recentes;
• lista completa de itens com filtros por estado e confiança.

Operar em itens falhos #

Use os filtros da lista para encontrar itens com erro de execução, erro de validação, recusa ou baixa confiança. Então você pode:

• tentar novamente todos os erros;
• tentar novamente apenas erros de execução;
• tentar novamente apenas erros de validação;
• tentar novamente itens concluídos com baixa confiança;
• remover itens pendentes, concluídos, com erro ou todos os não‑executados;
• abrir um item individual para revisar entrada, saída, estado e confiança.

Exportar resultados #

Quando o job terminar, exporte os resultados em JSONL. Cada linha exportada contém metadados, a entrada original e a saída. Use essa exportação para importar para uma planilha, banco de dados, pipeline de dados ou etapa de revisão manual.

Como usar via API #

Use a API quando quiser integrar o Batch ao seu sistema interno, pipeline de dados ou automação. A autenticação segue o mesmo padrão da API da AIVAX.

O fluxo da API é o mesmo do fluxo do console, apenas expresso como operações separadas. Primeiro crie o workflow, que é a receita reutilizável. Depois crie um job, importe os itens e inicie o job quando a carga estiver pronta. Após o início do processamento, use os endpoints de listagem, tentativa de nova execução, limpeza e exportação para operar o job sem perder o controle dos registros individuais.

Se ainda estiver decidindo se o Batch é o recurso certo, compare-o com RAG collections e direct inference. Batch serve para raciocínio repetido sobre itens independentes. RAG collections são para conhecimento pesquisável que será recuperado posteriormente. Direct inference é para uma resposta imediata.

Criar workflow #

Crie um workflow quando quiser salvar a regra de processamento que futuros jobs reutilizarão. É aqui que você define a instrução, modelo, esquema de saída, comportamento de validação, tentativas de nova execução e ferramentas habilitadas. Um bom workflow lê como uma política para cada item, não como um prompt único para um único registro.

Criar job #

Crie um job quando tiver uma carga concreta para executar através de um workflow existente. Jobs são criados pausados para que você possa importar e inspecionar itens antes do processamento.

Em seguida, importe os itens. O job permanece pausado até que você o inicie.

Importar itens #

Importe itens após o job existir. Cada item importado se torna uma unidade de trabalho independente, então escolha o modo que melhor corresponde aos seus dados de origem: uma linha por registro, um arquivo por registro, uma entrada ZIP por registro ou um texto enviado como um único registro.

Consulte a Referência de API embutida para os modos de importação suportados, campos e restrições atuais.

Iniciar, pausar ou finalizar #

Inicie o job somente depois que a lista de itens estiver correta. Pause para investigar erros ou ajustar o workflow, e finalize quando o job precisar ser encerrado em vez de retomado.

Consulte a Referência de API embutida para os estados de job suportados.

Monitorar #

Monitorar é como decidir se o workflow está saudável. A visualização do job mostra o estado geral; a lista de itens indica onde o trabalho está travando, quais itens falharam na validação e quais resultados de baixa confiança merecem revisão humana.

Para ver itens individuais e onde o trabalho está travando, liste os itens do job:

Use o endpoint de listagem para filtrar itens por estado, confiança ou texto de entrada. Consulte a Referência de API embutida para filtros suportados.

Tentativa de nova execução e limpeza #

Tentativas de nova execução são melhores após entender o padrão de falha:

• Tentar novamente erros de execução quando o provedor ou a solicitação falhar.
• Tentar novamente erros de validação quando a resposta puder ser regenerada para o formato esperado.
• Tentar novamente resultados de baixa confiança quando o item teve sucesso mas merece outra tentativa de modelo.

Endpoints de limpeza servem para remover itens não‑executados de um job quando eles não são mais úteis.

Use o endpoint de tentativa de nova execução após revisar o padrão de falha. Consulte a Referência de API embutida para opções de tentativa de nova execução suportadas e comportamento resultante do job.

Para remover itens não‑executados do job:

Use o endpoint de remoção apenas para itens que não são mais úteis. Consulte a Referência de API embutida para opções de remoção suportadas.

Exportar #

Exportar é o ponto de entrega da AIVAX de volta ao seu próprio fluxo. Use após o job terminar, ou exporte apenas um subconjunto quando um processo de revisão precisar primeiro dos itens concluídos e depois dos erros. O formato JSONL é conveniente para planilhas, bancos de dados, filas e ferramentas de auditoria manual porque cada linha permanece vinculada à entrada original e sua saída gerada.

Use o endpoint de exportação para selecionar os resultados concluídos que sua revisão ou processo subsequente necessita. Consulte a Referência de API embutida para filtros de exportação suportados.

Disponibilidade #

Revise a Pricing e os limits abaixo antes de processar uma carga grande.

Limites #

Um travessão longo (—) indica que o plano não impõe limite.

O processamento em lote é assíncrono. Se o processamento for pausado ou falhar por quota, tente novamente após o reset da janela de quota ou faça upgrade da conta. Para saber como o controle de admissão de lote lida com pausas de quota e resultados parciais, veja running thousands of LLM requests in batch.

Melhores práticas #

• Teste o workflow com alguns itens antes de importar uma lista grande.
• Use esquemas restritivos com required e additionalProperties: false quando a saída for consumida por um sistema.
• Inclua exemplos de entrada e saída na instrução quando o formato for ambíguo.
• Prefira uma linha por item; se precisar enviar objetos complexos, use JSONL.
• Mantenha a validação habilitada para tarefas sensíveis como extração legal, financeira ou dados que alimentam automações.
• Use maxRetries para corrigir falhas ocasionais, mas investigue erros recorrentes no prompt ou esquema.
• Defina um errorStopThreshold baixo em novos workflows para evitar gastar com um lote com configuração errada.
• Tente novamente itens de baixa confiança separadamente; baixa confiança não significa erro, mas indica que a resposta merece revisão.
• Exporte resultados por estado quando a revisão manual for necessária, por exemplo, primeiro finished, depois errors.
• Para um walkthrough operacional de limites de taxa, tentativas de nova execução e resultados parciais, veja running thousands of LLM requests in batch.