L'elaborazione in batch è un approccio potente per gestire grandi volumi di richieste in modo efficiente. Invece di elaborare le richieste una alla volta con risposte immediate, l'elaborazione in batch consente di inviare più richieste insieme per l'elaborazione asincrona. Questo schema è particolarmente utile quando:

• È necessario elaborare grandi volumi di dati
• Le risposte immediate non sono richieste
• Si desidera ottimizzare l'efficienza dei costi
• Si eseguono valutazioni o analisi su larga scala

La Message Batches API è la prima implementazione di questo schema da parte di Anthropic.

Message Batches API

La Message Batches API è un modo potente ed economico per elaborare in modo asincrono grandi volumi di richieste Messages. Questo approccio è adatto a compiti che non richiedono risposte immediate, con la maggior parte dei batch completati in meno di 1 ora, riducendo i costi del 50% e aumentando il throughput.

È possibile esplorare direttamente il riferimento API, oltre a questa guida.

Come funziona la Message Batches API

Quando si invia una richiesta alla Message Batches API:

1. Il sistema crea un nuovo Message Batch con le richieste Messages fornite.
2. Il batch viene quindi elaborato in modo asincrono, con ogni richiesta gestita in modo indipendente.
3. È possibile eseguire il polling dello stato del batch e recuperare i risultati quando l'elaborazione è terminata per tutte le richieste.

Questo è particolarmente utile per operazioni in blocco che non richiedono risultati immediati, come:

• Valutazioni su larga scala: elabora migliaia di casi di test in modo efficiente.
• Moderazione dei contenuti: analizza grandi volumi di contenuti generati dagli utenti in modo asincrono.
• Analisi dei dati: genera informazioni o riepiloghi per grandi dataset.
• Generazione di contenuti in blocco: crea grandi quantità di testo per vari scopi (ad esempio, descrizioni di prodotti, riepiloghi di articoli).

Limitazioni dei batch

• Un Message Batch è limitato a 100.000 richieste Messages o 256 MB di dimensione, a seconda di quale viene raggiunta prima.
• Il sistema elabora ogni batch il più velocemente possibile, con la maggior parte dei batch completati entro 1 ora. Sarà possibile accedere ai risultati del batch quando tutti i messaggi sono stati completati o dopo 24 ore, a seconda di quale avviene prima. I batch scadranno se l'elaborazione non viene completata entro 24 ore.
• I risultati del batch sono disponibili per 29 giorni dopo la creazione. Successivamente, è ancora possibile visualizzare il Batch, ma i suoi risultati non saranno più disponibili per il download.
• I batch sono limitati a un Workspace. È possibile visualizzare tutti i batch (e i loro risultati) creati all'interno del Workspace a cui appartiene la propria chiave API.
• I limiti di frequenza si applicano sia alle richieste HTTP della Batches API che al numero di richieste all'interno di un batch in attesa di essere elaborate. Vedere Limiti di frequenza della Message Batches API. Inoltre, l'elaborazione potrebbe essere rallentata in base alla domanda corrente e al volume delle richieste. In tal caso, è possibile che più richieste scadano dopo 24 ore.
• A causa dell'elevato throughput e dell'elaborazione concorrente, i batch potrebbero superare leggermente il limite di spesa configurato per il proprio Workspace.

Modelli supportati

Tutti i modelli attivi supportano la Message Batches API.

Cosa può essere inserito in un batch

Qualsiasi richiesta che è possibile effettuare alla Messages API può essere inclusa in un batch. Questo include:

• Vision
• Utilizzo degli strumenti
• Messaggi di sistema
• Conversazioni multi-turno
• Qualsiasi funzionalità beta

Poiché ogni richiesta nel batch viene elaborata in modo indipendente, è possibile combinare diversi tipi di richieste all'interno di un singolo batch.

Prezzi

La Batches API offre significativi risparmi sui costi. Tutto l'utilizzo viene addebitato al 50% dei prezzi API standard.

Come utilizzare la Message Batches API

Preparare e creare il batch

Un Message Batch è composto da un elenco di richieste per creare un Message. La struttura di una singola richiesta è composta da:

• Un custom_id univoco per identificare la richiesta Messages
• Un oggetto params con i parametri standard dell'API Messages

È possibile creare un batch passando questo elenco nel parametro requests:

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'

In questo esempio, due richieste separate vengono raggruppate insieme per l'elaborazione asincrona. Ogni richiesta ha un custom_id univoco e contiene i parametri standard che si utilizzerebbero per una chiamata all'API Messages.

Quando un batch viene creato per la prima volta, la risposta avrà uno stato di elaborazione 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
}

Monitoraggio del batch

Il campo processing_status del Message Batch indica la fase di elaborazione in cui si trova il batch. Inizia come in_progress, poi si aggiorna a ended una volta che tutte le richieste nel batch hanno terminato l'elaborazione e i risultati sono pronti. È possibile monitorare lo stato del batch visitando la Console o utilizzando l'endpoint di recupero.

Polling per il completamento del Message Batch

Per eseguire il polling di un Message Batch, è necessario il suo id, fornito nella risposta durante la creazione di un batch o elencando i batch. È possibile implementare un ciclo di polling che controlla periodicamente lo stato del batch fino al termine dell'elaborazione:

import anthropic
import time

client = anthropic.Anthropic()

message_batch = None
while True:
    message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)
    if message_batch.processing_status == "ended":
        break

    print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
    time.sleep(60)
print(message_batch)

Elenco di tutti i Message Batch

È possibile elencare tutti i Message Batch nel proprio Workspace utilizzando l'endpoint di elenco. L'API supporta la paginazione, recuperando automaticamente le pagine aggiuntive secondo necessità:

import anthropic

client = anthropic.Anthropic()

# Recupera automaticamente più pagine secondo necessità.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

Recupero dei risultati del batch

Una volta terminata l'elaborazione del batch, ogni richiesta Messages nel batch avrà un risultato. Ci sono 4 tipi di risultato:

Verrà visualizzata una panoramica dei risultati con i request_counts del batch, che mostra quante richieste hanno raggiunto ciascuno di questi quattro stati.

I risultati del batch sono disponibili per il download alla proprietà results_url del Message Batch e, se il permesso dell'organizzazione lo consente, nella Console. A causa delle dimensioni potenzialmente grandi dei risultati, si consiglia di trasmettere i risultati in streaming anziché scaricarli tutti in una volta.

#!/bin/sh
curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  | grep -o '"results_url":[[:space:]]*"[^"]*"' \
  | cut -d'"' -f4 \
  | while read -r url; do
    curl -s "$url" \
      --header "anthropic-version: 2023-06-01" \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      | sed 's/}{/}\n{/g' \
      | while IFS= read -r line
    do
      result_type=$(echo "$line" | sed -n 's/.*"result":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')
      custom_id=$(echo "$line" | sed -n 's/.*"custom_id":[[:space:]]*"\([^"]*\)".*/\1/p')
      error_type=$(echo "$line" | sed -n 's/.*"error":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')

      case "$result_type" in
        "succeeded")
          echo "Success! $custom_id"
          ;;
        "errored")
          if [ "$error_type" = "invalid_request" ]; then
            # Il corpo della richiesta deve essere corretto prima di inviare nuovamente la richiesta
            echo "Validation error: $custom_id"
          else
            # La richiesta può essere riprovata direttamente
            echo "Server error: $custom_id"
          fi
          ;;
        "expired")
          echo "Expired: $line"
          ;;
      esac
    done
  done

I risultati saranno in formato .jsonl, dove ogni riga è un oggetto JSON valido che rappresenta il risultato di una singola richiesta nel Message Batch. Per ogni risultato trasmesso in streaming, è possibile eseguire operazioni diverse in base al suo custom_id e al tipo di risultato. Ecco un esempio di set di risultati:

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-6","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"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-opus-4-6","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}

Se il risultato contiene un errore, il suo result.error sarà impostato sulla forma di errore standard.

Annullamento di un Message Batch

È possibile annullare un Message Batch attualmente in elaborazione utilizzando l'endpoint di annullamento. Immediatamente dopo l'annullamento, il processing_status di un batch sarà canceling. È possibile utilizzare la stessa tecnica di polling descritta sopra per attendere che l'annullamento sia finalizzato. I batch annullati terminano con uno stato ended e possono contenere risultati parziali per le richieste elaborate prima dell'annullamento.

import anthropic

client = anthropic.Anthropic()

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)

La risposta mostrerà il batch in uno stato canceling:

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch",
  "processing_status": "canceling",
  "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": "2024-09-24T18:39:03.114875Z",
  "results_url": null
}

Utilizzo del prompt caching con le Message Batches

L'API Message Batches supporta il prompt caching, consentendo di ridurre potenzialmente i costi e i tempi di elaborazione per le richieste batch. Gli sconti sui prezzi derivanti dal prompt caching e dalle Message Batches possono accumularsi, fornendo un risparmio sui costi ancora maggiore quando entrambe le funzionalità vengono utilizzate insieme. Tuttavia, poiché le richieste batch vengono elaborate in modo asincrono e concorrente, i cache hit vengono forniti nella misura del possibile. Gli utenti in genere registrano tassi di cache hit compresi tra il 30% e il 98%, a seconda dei loro pattern di traffico.

Per massimizzare la probabilità di cache hit nelle richieste batch:

1. Includere blocchi cache_control identici in ogni richiesta Message all'interno del batch
2. Mantenere un flusso costante di richieste per evitare che le voci della cache scadano dopo la loro durata di 5 minuti
3. Strutturare le richieste in modo da condividere il maggior contenuto memorizzato nella cache possibile

Esempio di implementazione del prompt caching in un batch:

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "system": [
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "system": [
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Write a summary of Pride and Prejudice."}
                ]
            }
        }
    ]
}'

In questo esempio, entrambe le richieste nel batch includono messaggi di sistema identici e il testo completo di Orgoglio e Pregiudizio contrassegnato con cache_control per aumentare la probabilità di cache hit.

Best practice per un batching efficace

Per ottenere il massimo dall'API Batches:

• Monitorare regolarmente lo stato di elaborazione del batch e implementare una logica di retry appropriata per le richieste fallite.
• Utilizzare valori custom_id significativi per abbinare facilmente i risultati alle richieste, poiché l'ordine non è garantito.
• Considerare di suddividere dataset molto grandi in più batch per una migliore gestibilità.
• Eseguire un dry run di una singola forma di richiesta con l'API Messages per evitare errori di validazione.

Risoluzione dei problemi comuni

In caso di comportamento imprevisto:

• Verificare che la dimensione totale della richiesta batch non superi 256 MB. Se la dimensione della richiesta è troppo grande, potrebbe essere restituito un errore 413 request_too_large.
• Verificare di utilizzare modelli supportati per tutte le richieste nel batch.
• Assicurarsi che ogni richiesta nel batch abbia un custom_id univoco.
• Assicurarsi che siano trascorsi meno di 29 giorni dalla data created_at del batch (non dalla data ended_at dell'elaborazione). Se sono trascorsi più di 29 giorni, i risultati non saranno più visualizzabili.
• Confermare che il batch non sia stato annullato.

Si noti che il fallimento di una richiesta in un batch non influisce sull'elaborazione delle altre richieste.

Archiviazione e privacy dei batch

• Isolamento del Workspace: I batch sono isolati all'interno del Workspace in cui vengono creati. È possibile accedervi solo tramite chiavi API associate a quel Workspace, o da utenti con autorizzazione a visualizzare i batch del Workspace nella Console.

• Disponibilità dei risultati: I risultati dei batch sono disponibili per 29 giorni dopo la creazione del batch, consentendo un tempo sufficiente per il recupero e l'elaborazione.

Conservazione dei dati

L'elaborazione batch memorizza i dati di richiesta e risposta per un massimo di 29 giorni dopo la creazione del batch. È possibile eliminare un message batch in qualsiasi momento dopo l'elaborazione utilizzando l'endpoint DELETE /v1/messages/batches/{batch_id}. L'elaborazione asincrona richiede l'archiviazione lato server sia degli input che degli output fino al completamento del batch e al recupero dei risultati.

Per l'idoneità ZDR su tutte le funzionalità, vedere API e conservazione dei dati.

FAQ