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 ti consente di inviare più richieste insieme per l'elaborazione asincrona. Questo modello è particolarmente utile quando:

• Hai bisogno di elaborare grandi volumi di dati
• Le risposte immediate non sono richieste
• Vuoi ottimizzare l'efficienza dei costi
• Stai eseguendo valutazioni o analisi su larga scala

L'API Message Batches è la prima implementazione di questo modello da parte di Anthropic.

API Message Batches

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

Puoi esplorare il riferimento API direttamente, 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 indipendentemente.
3. Puoi 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 approfondimenti o riepiloghi per grandi set di dati.
• Generazione di contenuti in blocco: Crea grandi quantità di testo per vari scopi (ad es. 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 raggiunto per primo.
• Il sistema elabora ogni batch il più velocemente possibile, con la maggior parte dei batch che si completano entro 1 ora. Puoi accedere ai risultati del batch quando tutti i messaggi sono stati completati o dopo 24 ore, a seconda di quale viene raggiunto per primo. I batch scadono se l'elaborazione non si completa entro 24 ore.
• I risultati del batch sono disponibili per 29 giorni dopo la creazione. Dopo di che, puoi comunque 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) creati all'interno del Workspace a cui appartiene la tua chiave API.
• I limiti di velocità si applicano sia alle richieste HTTP dell'API Batches che al numero di richieste all'interno di un batch in attesa di essere elaborate. Vedi Limiti di velocità dell'API Message Batches. Inoltre, l'elaborazione potrebbe essere rallentata in base alla domanda attuale e al volume delle tue richieste. In tal caso, potresti vedere più richieste scadere dopo 24 ore.
• A causa dell'elevato throughput e dell'elaborazione concorrente, i batch potrebbero superare leggermente il limite di spesa configurato del tuo Workspace.

Modelli supportati

Tutti i modelli attivi supportano l'API Message Batches.

Cosa può essere elaborato in batch

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

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

Poiché ogni richiesta nel batch viene elaborata indipendentemente, puoi mescolare diversi tipi di richieste all'interno di un singolo batch.

Prezzi

L'API Batches offre risparmi significativi sui costi. Tutti gli utilizzi vengono addebitati al 50% dei prezzi standard dell'API.

Come utilizzare l'API Message Batches

Prepara e crea il tuo batch

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

• Un custom_id univoco per identificare la richiesta Messages. Deve essere da 1 a 64 caratteri e contenere solo caratteri alfanumerici, trattini e sottolineature (corrispondenti a ^[a-zA-Z0-9_-]{1,64}$).
• Un oggetto params con i parametri standard dell'API Messages

Puoi creare un batch passando questo elenco nel parametro requests:

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

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

Tracciamento del tuo batch

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

Polling per il completamento di Message Batch

Per eseguire il polling di un Message Batch, avrai bisogno del suo id, che viene fornito nella risposta quando crei un batch o elencando i batch. Puoi implementare un ciclo di polling che controlla periodicamente lo stato del batch fino a quando l'elaborazione non è terminata:

Elenco di tutti i Message Batches

Puoi elencare tutti i Message Batches nel tuo Workspace utilizzando l'endpoint di elenco. L'API supporta la paginazione, recuperando automaticamente pagine aggiuntive secondo necessità:

Recupero dei risultati del batch

Una volta che l'elaborazione del batch è terminata, ogni richiesta Messages nel batch ha un risultato. Ci sono 4 tipi di risultati:

Vedrai una panoramica dei tuoi risultati con request_counts del batch, che mostra quante richieste hanno raggiunto ognuno di questi quattro stati.

I risultati del batch sono disponibili per il download nella proprietà results_url su Message Batch, e se il permesso dell'organizzazione lo consente, nella Console. A causa della potenziale grande dimensione dei risultati, si consiglia di trasmettere i risultati piuttosto che scaricarli tutti in una volta.

I risultati sono 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, 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-7","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-7","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 forma di errore standard.

Annullamento di un Message Batch

Puoi annullare un Message Batch che è attualmente in elaborazione utilizzando l'endpoint di annullamento. Immediatamente dopo l'annullamento, lo processing_status di un batch sarà canceling. Puoi utilizzare la stessa tecnica di polling descritta sopra per attendere fino a quando l'annullamento non è finalizzato. I batch annullati finiscono con uno stato di ended e possono contenere risultati parziali per le richieste che sono state elaborate prima dell'annullamento.

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 della cache dei prompt con Message Batches

L'API Message Batches supporta la cache dei prompt, consentendoti di ridurre potenzialmente i costi e i tempi 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 funzioni vengono utilizzate insieme. Tuttavia, poiché le richieste batch vengono elaborate in modo asincrono e concorrente, i cache hit vengono forniti su base best-effort. Gli utenti in genere sperimentano tassi di cache hit che vanno dal 30% al 98%, a seconda dei loro modelli di traffico.

Per massimizzare la probabilità di cache hit 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 in cache

Esempio di implementazione della cache dei prompt in un batch:

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

Output esteso (beta)

L'intestazione beta output-300k-2026-03-24 aumenta il limite di max_tokens a 300.000 per le richieste batch utilizzando Claude Opus 4.7, Claude Opus 4.6 o Claude Sonnet 4.6. Includi l'intestazione per generare output molto più lunghi del limite standard (da 64k a 128k a seconda del modello) in un singolo turno.

Utilizza l'output esteso per la generazione di contenuti lunghi come bozze di libri e documentazione tecnica, estrazione di dati strutturati esaustiva, grandi scaffold di generazione di codice e lunghe catene di ragionamento.

Una singola generazione di 300k token può richiedere più di un'ora per completarsi, quindi pianifica i tuoi invii batch tenendo in considerazione la finestra di elaborazione di 24 ore. Si applica il prezzo batch standard (50% dei prezzi API standard).

Best practice per un batching efficace

Per ottenere il massimo dall'API Batches:

• Monitora regolarmente lo stato di elaborazione del batch e implementa una logica di retry appropriata per le richieste non riuscite.
• 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 un test di una singola forma di richiesta con l'API Messages per evitare errori di convalida.

Risoluzione dei problemi comuni

Se riscontri comportamenti inaspettati:

• Verifica che la dimensione totale della richiesta batch non superi 256 MB. Se la dimensione della richiesta è troppo grande, potresti ricevere un errore 413 request_too_large.
• Controlla che stai utilizzando modelli supportati per tutte le richieste nel batch.
• Assicurati che ogni richiesta nel batch abbia un custom_id univoco.
• Assicurati che siano passati meno di 29 giorni dal momento di created_at del batch (non dal tempo di elaborazione ended_at). Se sono passati 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 batch e privacy

• Isolamento dell'area di lavoro: I batch sono isolati all'interno dell'area di lavoro in cui vengono creati. Possono essere accessibili solo da chiavi API associate a quell'area di lavoro, o da utenti con autorizzazione per visualizzare i batch dell'area di lavoro nella Console.

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

Conservazione dei dati

L'elaborazione batch archivia i dati di richiesta e risposta per un massimo di 29 giorni dopo la creazione del batch. Puoi eliminare un batch di messaggi in qualsiasi momento dopo l'elaborazione utilizzando l'endpoint DELETE /v1/messages/batches/{batch_id}. Per eliminare un batch in corso, annullalo prima. 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 in tutte le funzioni, vedi Conservazione API e dati.

FAQ