Lotes de Mensagens

A API de Lotes de Mensagens é uma maneira poderosa e econômica de processar assincronamente grandes volumes de requisições de Mensagens. Esta abordagem é adequada para tarefas que não requerem respostas imediatas, reduzindo custos em 50% enquanto aumenta 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 requisição para a API de Lotes de Mensagens:

1. O sistema cria um novo Lote de Mensagens com as requisições de Mensagens fornecidas.
2. O lote é então processado assincronamente, com cada requisição tratada independentemente.
3. Você pode consultar o status do lote e recuperar resultados quando o processamento tiver terminado para todas as requisições.

Isso é especialmente útil para operações em massa que não requerem resultados imediatos, como:

• Avaliações em larga escala: Processe milhares de casos de teste eficientemente.
• Moderação de conteúdo: Analise grandes volumes de conteúdo gerado por usuários assincronamente.
• 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 vários propósitos (ex.: descrições de produtos, resumos de artigos).

​

Limitações do lote

• Um Lote de Mensagens é limitado a 100.000 requisições de Mensagens ou 256 MB em tamanho, o que for atingido primeiro.
• O lote leva até 24 horas para gerar respostas, embora o processamento possa terminar antes disso. Os resultados do seu lote não estarão disponíveis até que o processamento do lote inteiro termine. 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 API pertence.
• Limites de taxa se aplicam tanto às requisições HTTP da API de Lotes quanto ao número de requisições dentro de um lote aguardando processamento. Veja 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 requisições. Nesse caso, você pode ver mais requisições expirando após 24 horas.
• Devido à alta taxa de transferência e processamento concorrente, os lotes podem ultrapassar ligeiramente o limite de gastos configurado do seu Workspace.

​

Modelos suportados

A API de Lotes de Mensagens atualmente suporta:

• Claude 3.5 Sonnet (claude-3-5-sonnet-20240620 e claude-3-5-sonnet-20241022)
• Claude 3.5 Haiku (claude-3-5-haiku-20241022)
• Claude 3 Haiku (claude-3-haiku-20240307)
• Claude 3 Opus (claude-3-opus-20240229)

​

O que pode ser processado em lote

Qualquer requisição que você pode fazer à API de Mensagens pode ser incluída em um lote. Isso inclui:

• Visão
• Uso de ferramentas
• Mensagens do sistema
• Conversas com múltiplos turnos
• Quaisquer recursos beta

Como cada requisição no lote é processada independentemente, você pode misturar diferentes tipos de requisições dentro de um único lote.

​

Preços

A API de Lotes oferece economias significativas de custos. Todo uso é cobrado a 50% dos preços padrão da API.

​

Como usar a API de Lotes de Mensagens

​

Prepare e crie seu lote

Um Lote de Mensagens é composto por uma lista de requisições para criar uma Mensagem. A forma de uma requisição individual é composta por:

• Um custom_id único para identificar a requisiçã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 requisições separadas são agrupadas para processamento assíncrono. Cada requisição tem um custom_id único e contém os parâmetros padrão que você usaria para uma chamada da API de Mensagens.

Quando um lote é criado pela primeira vez, a resposta terá um status de processamento in_progress.

{
  "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": null,
  "results_url": null
}

​

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, depois atualiza para ended quando todas as requisições no lote terminaram o processamento 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

Uma vez que o processamento do lote terminou, cada requisição de Mensagens no lote terá um resultado. Existem 4 tipos de resultado:

Você verá uma visão geral dos seus resultados com o request_counts do lote, que mostra quantas requisições alcançaram cada um desses quatro estados.

Os resultados do lote estão disponíveis para download tanto no Console quanto na results_url do Lote de Mensagens. Devido ao tamanho potencialmente grande dos resultados, é recomendado transmitir os resultados de volta 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 requisiçã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:

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-3-5-sonnet-20241022","content":[{"type":"text","text":"Olá novamente! É bom ver você. Como posso ajudar você hoje? Há algo específico sobre o qual você gostaria de conversar ou alguma pergunta que você tenha?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-3-5-sonnet-20241022","content":[{"type":"text","text":"Olá! Como posso ajudar você hoje? Sinta-se à vontade para fazer qualquer pergunta ou me dizer se há algo sobre o qual você gostaria de conversar."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}

Se seu resultado tiver um erro, seu result.error será definido com nossa forma de erro padrão.

​

Melhores práticas para processamento em lote efetivo

Para obter o máximo da API de Lotes:

• Monitore o status de processamento do lote regularmente e implemente lógica de nova tentativa apropriada para requisições falhas.
• Use valores custom_id significativos para facilmente corresponder resultados com requisições, já que a ordem não é garantida.
• Considere dividir conjuntos de dados muito grandes em múltiplos lotes para melhor gerenciabilidade.
• Faça um teste com uma única forma de requisição com a API de Mensagens para evitar erros de validação.

​

Solucionando problemas comuns

Se estiver experimentando comportamento inesperado:

• Verifique se o tamanho total da requisição do lote não excede 256 MB. Se o tamanho da requisição for muito grande, você pode receber um erro 413 request_too_large.
• Verifique se você está usando modelos suportados para todas as requisições no lote.
• Garanta que cada requisição no lote tenha um custom_id único.
• Garanta que se passaram menos de 29 dias desde o tempo created_at do lote (não o tempo ended_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.

Note que a falha de uma requisição em um lote não afeta o processamento de outras requisições.

​

Armazenamento e privacidade do lote

• Isolamento do Workspace: Os lotes são isolados dentro do Workspace em que são criados. Eles só podem ser acessados por chaves API associadas àquele Workspace, ou usuários com permissão para visualizar lotes do Workspace no Console.

• Disponibilidade dos resultados: Os resultados do lote estão disponíveis por 29 dias após a criação do lote, permitindo tempo amplo para recuperação e processamento.

​

Perguntas Frequentes

import anthropic

client = anthropic.Anthropic()

message_batch = client.beta.messages.batches.create(
    betas: ["max-tokens-3-5-sonnet-2024-07-15"],
    ...
)