L’elaborazione in batch è un approccio potente per gestire in modo efficiente grandi volumi di richieste. 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 modello è particolarmente utile quando:

• È necessario elaborare grandi volumi di dati
• Non sono richieste risposte immediate
• Si desidera ottimizzare l’efficienza dei costi
• Si stanno eseguendo valutazioni o analisi su larga scala

L’API Message Batches è la nostra prima implementazione di questo modello.

​

API Message Batches

L’API Message Batches è 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 che terminano in meno di 1 ora, riducendo i costi del 50% e aumentando la produttività.

Puoi esplorare direttamente la documentazione di riferimento dell’API, oltre a questa guida.

​

Come funziona l’API Message Batches

Quando invii una richiesta all’API Message Batches:

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. Puoi verificare lo stato del batch e recuperare i risultati quando l’elaborazione è terminata per tutte le richieste.

Questo è particolarmente utile per operazioni di massa 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 approfondimenti o riassunti per grandi set di dati.
• Generazione di contenuti in blocco: crea grandi quantità di testo per vari scopi (ad esempio, descrizioni di prodotti, riassunti di articoli).

​

Limitazioni dei batch

• Un Message Batch è limitato a 100.000 richieste Message o a 256 MB di dimensione, a seconda di quale limite viene raggiunto per primo.
• Elaboriamo ogni batch il più velocemente possibile, con la maggior parte dei batch che si completano entro 1 ora. Potrai accedere ai risultati del batch quando tutti i messaggi sono stati completati o dopo 24 ore, a seconda di quale evento si verifica per primo. I batch scadranno se l’elaborazione non viene completata entro 24 ore.
• I risultati dei batch sono disponibili per 29 giorni dopo la creazione. Dopo tale periodo, potrai ancora visualizzare il Batch, ma i suoi risultati non saranno più disponibili per il download.
• I batch sono limitati a un Workspace. Puoi visualizzare tutti i batch e i loro risultati che sono stati creati all’interno del Workspace a cui appartiene la tua chiave API.
• I limiti di frequenza si applicano sia alle richieste HTTP dell’API Batches sia al numero di richieste all’interno di un batch in attesa di essere elaborate. Vedi Limiti di frequenza dell’API Message Batches. Inoltre, potremmo rallentare l’elaborazione in base alla domanda corrente e al volume delle tue richieste. In tal caso, potresti vedere più richieste che scadono dopo 24 ore.
• A causa dell’elevata produttività e dell’elaborazione simultanea, i batch potrebbero superare leggermente il limite di spesa configurato per il tuo Workspace.

​

Modelli supportati

L’API Message Batches attualmente supporta:

• 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 e claude-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)

​

Cosa può essere elaborato in batch

Qualsiasi richiesta che puoi fare all’API Messages può essere inclusa in un batch. Questo include:

• Visione
• Uso di strumenti
• Messaggi di sistema
• Conversazioni multi-turno
• Qualsiasi funzionalità beta

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

​

Prezzi

L’API Batches offre significativi risparmi sui costi. Tutto l’utilizzo viene addebitato al 50% dei prezzi standard dell’API.

​

Come utilizzare l’API Message Batches

​

Preparare e creare il tuo batch

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

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

Puoi 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-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'

In questo esempio, due richieste separate sono raggruppate insieme per l’elaborazione asincrona. Ogni richiesta ha un custom_id univoco e contiene i parametri standard che utilizzeresti 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
}

​

Monitorare il tuo 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. Puoi monitorare lo stato del tuo batch visitando la Console o utilizzando l’endpoint di recupero:

curl https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
 --header "x-api-key: $ANTHROPIC_API_KEY" \
 --header "anthropic-version: 2023-06-01" \
 | sed -E 's/.*"id":"([^"]+)".*"processing_status":"([^"]+)".*/Batch \1 processing status is \2/'

Puoi interrogare questo endpoint per sapere quando l’elaborazione è terminata.

​

Recuperare i risultati del batch

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

Vedrai una panoramica dei tuoi 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 sul Message Batch e, se l’autorizzazione dell’organizzazione lo consente, nella Console. A causa della potenziale grande dimensione dei risultati, si consiglia di trasmettere i risultati in streaming piuttosto che 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
            # Request body must be fixed before re-sending request
            echo "Validation error: $custom_id"
          else
            # Request can be retried directly
            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, puoi fare qualcosa di diverso a seconda del suo custom_id e del 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-20250514","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-20250514","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 tuo risultato ha un errore, il suo result.error sarà impostato sulla nostra forma standard di errore.

​

Utilizzo della cache dei prompt con Message Batches

L’API Message Batches supporta la cache dei prompt, consentendoti di ridurre potenzialmente i costi e il tempo di elaborazione per le richieste batch. Gli sconti sui prezzi dalla cache dei prompt e da Message Batches possono accumularsi, fornendo risparmi sui costi ancora maggiori quando entrambe le funzionalità vengono utilizzate insieme. Tuttavia, poiché le richieste batch vengono elaborate in modo asincrono e simultaneo, i successi della cache vengono forniti con il massimo impegno possibile. Gli utenti in genere sperimentano tassi di successo della cache che vanno dal 30% al 98%, a seconda dei loro modelli di traffico.

Per massimizzare la probabilità di successi della cache nelle tue richieste batch:

1. Includi blocchi cache_control identici in ogni richiesta Message all’interno del tuo batch
2. Mantieni un flusso costante di richieste per evitare che le voci della cache scadano dopo la loro durata di 5 minuti
3. Struttura le tue richieste per condividere il maggior contenuto possibile nella cache

Esempio di implementazione della cache dei prompt 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-20250514",
                "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-20250514",
                "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 successi della cache.

​

Best practice per un’efficace elaborazione in batch

Per ottenere il massimo dall’API Batches:

• Monitora regolarmente lo stato di elaborazione del batch e implementa una logica di ripetizione appropriata per le richieste fallite.
• Utilizza valori custom_id significativi per abbinare facilmente i risultati alle richieste, poiché l’ordine non è garantito.
• Considera di suddividere set di dati molto grandi in più batch per una migliore gestibilità.
• Esegui una prova con una singola forma di richiesta con l’API Messages per evitare errori di validazione.

​

Risoluzione dei problemi comuni

Se si verificano comportamenti inaspettati:

• Verifica che la dimensione totale della richiesta batch non superi i 256 MB. Se la dimensione della richiesta è troppo grande, potresti ricevere un errore 413 request_too_large.
• Controlla di utilizzare modelli supportati per tutte le richieste nel batch.
• Assicurati che ogni richiesta nel batch abbia un custom_id univoco.
• Assicurati che siano trascorsi meno di 29 giorni dal momento created_at del batch (non dal momento ended_at dell’elaborazione). Se sono trascorsi più di 29 giorni, i risultati non saranno più visualizzabili.
• Conferma che il batch non sia stato annullato.

Nota che il fallimento di una richiesta in un batch non influisce sull’elaborazione di altre richieste.

​

Archiviazione e privacy dei batch

• Isolamento del Workspace: I batch sono isolati all’interno del Workspace in cui vengono creati. Possono essere accessibili solo tramite chiavi API associate a quel Workspace o da utenti con il permesso di visualizzare i batch del Workspace nella Console.

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

​

FAQ