Processamento em lote
O processamento em lote é uma abordagem poderosa para lidar com grandes volumes de solicitações de forma eficiente. Em vez de processar solicitações uma por vez com respostas imediatas, o processamento em lote permite enviar várias solicitações juntas para processamento assíncrono. Este padrão é particularmente útil quando:
- Você precisa processar grandes volumes de dados
- Respostas imediatas não são necessárias
- Você deseja otimizar a eficiência de custos
- Você está executando avaliações ou análises em grande escala
A API de Lotes de Mensagens é nossa primeira implementação desse padrão.
API de Lotes de Mensagens
A API de Lotes de Mensagens é uma maneira poderosa e econômica de processar assincronamente grandes volumes de solicitações de Mensagens. Esta abordagem é adequada para tarefas que não exigem respostas imediatas, com a maioria dos lotes sendo concluídos em menos de 1 hora, reduzindo custos em 50% e aumentando a taxa de transferência.
Você pode explorar a referência da API diretamente, além deste guia.
Como funciona a API de Lotes de Mensagens
Quando você envia uma solicitação para a API de Lotes de Mensagens:
- O sistema cria um novo Lote de Mensagens com as solicitações de Mensagens fornecidas.
- O lote é então processado de forma assíncrona, com cada solicitação tratada independentemente.
- Você pode verificar o status do lote e recuperar os resultados quando o processamento terminar para todas as solicitações.
Isso é especialmente útil para operações em massa que não exigem resultados imediatos, como:
- Avaliações em grande escala: Processe milhares de casos de teste de forma eficiente.
- Moderação de conteúdo: Analise grandes volumes de conteúdo gerado por usuários de forma assíncrona.
- Análise de dados: Gere insights ou resumos para grandes conjuntos de dados.
- Geração de conteúdo em massa: Crie grandes quantidades de texto para diversos fins (por exemplo, descrições de produtos, resumos de artigos).
Limitações de lote
- Um Lote de Mensagens é limitado a 100.000 solicitações de Mensagem ou 256 MB de tamanho, o que for atingido primeiro.
- Processamos cada lote o mais rápido possível, com a maioria dos lotes sendo concluídos em 1 hora. Você poderá acessar os resultados do lote quando todas as mensagens forem concluídas ou após 24 horas, o que ocorrer primeiro. Os lotes expirarão se o processamento não for concluído em 24 horas.
- Os resultados do lote estão disponíveis por 29 dias após a criação. Depois disso, você ainda poderá visualizar o Lote, mas seus resultados não estarão mais disponíveis para download.
- Os lotes são limitados a um Workspace. Você pode visualizar todos os lotes — e seus resultados — que foram criados dentro do Workspace ao qual sua chave de API pertence.
- Os limites de taxa se aplicam tanto às solicitações HTTP da API de Lotes quanto ao número de solicitações dentro de um lote aguardando processamento. Consulte Limites de taxa da API de Lotes de Mensagens. Além disso, podemos diminuir o processamento com base na demanda atual e no volume de suas solicitações. Nesse caso, você pode ver mais solicitações expirando após 24 horas.
- Devido à alta taxa de transferência e processamento simultâneo, os lotes podem ultrapassar ligeiramente o limite de gastos configurado do seu Workspace.
Modelos suportados
A API de Lotes de Mensagens atualmente suporta:
- Claude Opus 4 (
claude-opus-4-20250514
) - Claude Sonnet 4 (
claude-sonnet-4-20250514
) - Claude Sonnet 3.7 (
claude-3-7-sonnet-20250219
) - Claude Sonnet 3.5 (
claude-3-5-sonnet-20240620
eclaude-3-5-sonnet-20241022
) - Claude Haiku 3.5 (
claude-3-5-haiku-20241022
) - Claude Haiku 3 (
claude-3-haiku-20240307
) - Claude Opus 3 (
claude-3-opus-20240229
)
O que pode ser processado em lote
Qualquer solicitação que você possa fazer à API de Mensagens pode ser incluída em um lote. Isso inclui:
- Visão
- Uso de ferramentas
- Mensagens do sistema
- Conversas de múltiplos turnos
- Quaisquer recursos beta
Como cada solicitação no lote é processada independentemente, você pode misturar diferentes tipos de solicitações dentro de um único lote.
Preços
A API de Lotes oferece economias significativas de custos. Todo o uso é cobrado a 50% dos preços padrão da API.
Model | Batch input | Batch output |
---|---|---|
Claude Opus 4 | $7.50 / MTok | $37.50 / MTok |
Claude Sonnet 4 | $1.50 / MTok | $7.50 / MTok |
Claude Sonnet 3.7 | $1.50 / MTok | $7.50 / MTok |
Claude Sonnet 3.5 | $1.50 / MTok | $7.50 / MTok |
Claude Haiku 3.5 | $0.40 / MTok | $2 / MTok |
Claude Opus 3 | $7.50 / MTok | $37.50 / MTok |
Claude Haiku 3 | $0.125 / MTok | $0.625 / MTok |
Como usar a API de Lotes de Mensagens
Preparar e criar seu lote
Um Lote de Mensagens é composto por uma lista de solicitações para criar uma Mensagem. O formato de uma solicitação individual é composto por:
- Um
custom_id
único para identificar a solicitação de Mensagens - Um objeto
params
com os parâmetros padrão da API de Mensagens
Você pode criar um lote passando esta lista para o parâmetro requests
:
Neste exemplo, duas solicitações separadas são agrupadas para processamento assíncrono. Cada solicitação tem um custom_id
único e contém os parâmetros padrão que você usaria para uma chamada à API de Mensagens.
Teste suas solicitações em lote com a API de Mensagens
A validação do objeto params
para cada solicitação de mensagem é realizada de forma assíncrona, e os erros de validação são retornados quando o processamento de todo o lote é concluído. Você pode garantir que está construindo sua entrada corretamente verificando o formato da sua solicitação com a API de Mensagens primeiro.
Quando um lote é criado pela primeira vez, a resposta terá um status de processamento in_progress
.
Acompanhando seu lote
O campo processing_status
do Lote de Mensagens indica o estágio de processamento em que o lote se encontra. Ele começa como in_progress
e depois é atualizado para ended
quando todas as solicitações no lote terminaram de ser processadas e os resultados estão prontos. Você pode monitorar o estado do seu lote visitando o Console ou usando o endpoint de recuperação:
Você pode consultar este endpoint para saber quando o processamento terminou.
Recuperando resultados do lote
Quando o processamento do lote termina, cada solicitação de Mensagens no lote terá um resultado. Existem 4 tipos de resultados:
Tipo de Resultado | Descrição |
---|---|
succeeded | A solicitação foi bem-sucedida. Inclui o resultado da mensagem. |
errored | A solicitação encontrou um erro e uma mensagem não foi criada. Os erros possíveis incluem solicitações inválidas e erros internos do servidor. Você não será cobrado por essas solicitações. |
canceled | O usuário cancelou o lote antes que esta solicitação pudesse ser enviada ao modelo. Você não será cobrado por essas solicitações. |
expired | O lote atingiu sua expiração de 24 horas antes que esta solicitação pudesse ser enviada ao modelo. Você não será cobrado por essas solicitações. |
Você verá uma visão geral dos seus resultados com o request_counts
do lote, que mostra quantas solicitações atingiram cada um desses quatro estados.
Os resultados do lote estão disponíveis para download na propriedade results_url
do Lote de Mensagens e, se a permissão da organização permitir, no Console. Devido ao tamanho potencialmente grande dos resultados, é recomendável transmitir os resultados em vez de baixá-los todos de uma vez.
Os resultados estarão no formato .jsonl
, onde cada linha é um objeto JSON válido representando o resultado de uma única solicitação no Lote de Mensagens. Para cada resultado transmitido, você pode fazer algo diferente dependendo do seu custom_id
e tipo de resultado. Aqui está um exemplo de conjunto de resultados:
Se o seu resultado tiver um erro, seu result.error
será definido com nosso formato de erro padrão.
Os resultados do lote podem não corresponder à ordem de entrada
Os resultados do lote podem ser retornados em qualquer ordem e podem não corresponder à ordenação das solicitações quando o lote foi criado. No exemplo acima, o resultado da segunda solicitação do lote é retornado antes da primeira. Para corresponder corretamente os resultados às suas solicitações correspondentes, sempre use o campo custom_id
.
Usando cache de prompt com Lotes de Mensagens
A API de Lotes de Mensagens suporta cache de prompt, permitindo potencialmente reduzir custos e tempo de processamento para solicitações em lote. Os descontos de preço do cache de prompt e dos Lotes de Mensagens podem se acumular, proporcionando economias de custo ainda maiores quando ambos os recursos são usados juntos. No entanto, como as solicitações em lote são processadas de forma assíncrona e concorrente, os acertos de cache são fornecidos com base no melhor esforço. Os usuários normalmente experimentam taxas de acerto de cache variando de 30% a 98%, dependendo de seus padrões de tráfego.
Para maximizar a probabilidade de acertos de cache em suas solicitações em lote:
- Inclua blocos
cache_control
idênticos em cada solicitação de Mensagem dentro do seu lote - Mantenha um fluxo constante de solicitações para evitar que as entradas de cache expirem após seu tempo de vida de 5 minutos
- Estruture suas solicitações para compartilhar o máximo possível de conteúdo em cache
Exemplo de implementação de cache de prompt em um lote:
Neste exemplo, ambas as solicitações no lote incluem mensagens de sistema idênticas e o texto completo de Orgulho e Preconceito marcado com cache_control
para aumentar a probabilidade de acertos de cache.
Melhores práticas para processamento em lote eficaz
Para obter o máximo da API de Lotes:
- Monitore regularmente o status de processamento do lote e implemente lógica de repetição apropriada para solicitações com falha.
- Use valores
custom_id
significativos para facilmente corresponder resultados com solicitações, já que a ordem não é garantida. - Considere dividir conjuntos de dados muito grandes em vários lotes para melhor gerenciamento.
- Faça um teste com um único formato de solicitação com a API de Mensagens para evitar erros de validação.
Solucionando problemas comuns
Se estiver enfrentando comportamento inesperado:
- Verifique se o tamanho total da solicitação em lote não excede 256 MB. Se o tamanho da solicitação for muito grande, você pode receber um erro 413
request_too_large
. - Verifique se você está usando modelos suportados para todas as solicitações no lote.
- Certifique-se de que cada solicitação no lote tenha um
custom_id
único. - Certifique-se de que se passaram menos de 29 dias desde o horário
created_at
do lote (não o horárioended_at
do processamento). Se mais de 29 dias se passaram, os resultados não serão mais visíveis. - Confirme que o lote não foi cancelado.
Observe que a falha de uma solicitação em um lote não afeta o processamento de outras solicitações.
Armazenamento e privacidade de lotes
-
Isolamento de Workspace: Os lotes são isolados dentro do Workspace em que são criados. Eles só podem ser acessados por chaves de API associadas a esse Workspace ou por usuários com permissão para visualizar lotes do Workspace no Console.
-
Disponibilidade de resultados: Os resultados do lote estão disponíveis por 29 dias após a criação do lote, permitindo tempo suficiente para recuperação e processamento.