Batch di Messaggi

L’API dei Batch di Messaggi è un modo potente ed economico per elaborare in modo asincrono grandi volumi di richieste di Messaggi. Questo approccio è adatto a compiti che non richiedono risposte immediate, riducendo i costi del 50% e aumentando il throughput.

Puoi esplorare direttamente il riferimento API, oltre a questa guida.

​

Come funziona l’API dei Batch di Messaggi

Quando invii una richiesta all’API dei Batch di Messaggi:

1. Il sistema crea un nuovo Batch di Messaggi con le richieste di Messaggi fornite.
2. Il batch viene quindi elaborato in modo asincrono, con ogni richiesta gestita indipendentemente.
3. Puoi interrogare lo 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 riassunti per grandi set di dati.
• Generazione di contenuti in blocco: Crea grandi quantità di testo per vari scopi (es. descrizioni di prodotti, riassunti di articoli).

​

Limitazioni dei batch

• Un Batch di Messaggi è limitato a 100.000 richieste di Messaggi o 256 MB di dimensione, a seconda di quale limite viene raggiunto per primo.
• Il batch impiega fino a 24 ore per generare risposte, anche se l’elaborazione può terminare prima. I risultati del tuo batch non saranno disponibili fino al termine dell’elaborazione dell’intero batch. I batch scadranno se l’elaborazione non viene completata entro 24 ore.
• I risultati del batch sono disponibili per 29 giorni dopo la creazione. Dopo di che, 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 velocità si applicano sia alle richieste HTTP dell’API dei Batch che al numero di richieste all’interno di un batch in attesa di essere elaborate. Vedi limiti di velocità dell’API dei Batch di Messaggi. Inoltre, potremmo rallentare l’elaborazione in base alla domanda corrente 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

L’API dei Batch di Messaggi attualmente supporta:

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

​

Cosa può essere messo in batch

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

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

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

​

Prezzi

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

​

Come utilizzare l’API dei Batch di Messaggi

​

Preparare e creare il tuo batch

Un Batch di Messaggi è composto da una lista di richieste per creare un Messaggio. La forma di una singola richiesta comprende:

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

Puoi creare un batch passando questa lista nel parametro requests:

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 useresti per una chiamata all’API dei Messaggi.

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 Batch di Messaggi 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:

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

​

Recuperare i risultati del batch

Una volta terminata l’elaborazione del batch, ogni richiesta di Messaggi 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 sia nella Console che all’URL results_url sul Batch di Messaggi. A causa della potenziale grande dimensione dei risultati, si consiglia di trasmettere i risultati in streaming piuttosto che scaricarli tutti in una volta.

I risultati saranno in formato .jsonl, dove ogni riga è un oggetto JSON valido che rappresenta il risultato di una singola richiesta nel Batch di Messaggi. 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-3-5-sonnet-20241022","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-3-5-sonnet-20241022","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 di errore standard.

​

Migliori pratiche per un batching efficace

Per ottenere il massimo dall’API dei Batch:

• Monitora regolarmente lo stato di elaborazione del batch e implementa una logica di retry appropriata per le richieste fallite.
• Usa valori custom_id significativi per far corrispondere facilmente i risultati con le 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 dei Messaggi 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 passati meno di 29 giorni dal momento created_at del batch (non dal momento ended_at dell’elaborazione). 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 delle altre richieste.

​

Archiviazione e privacy dei batch

• Isolamento del Workspace: I batch sono isolati all’interno del Workspace in cui sono stati creati. Possono essere accessibili solo da 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 ampio tempo per il recupero e l’elaborazione.

​

FAQ

import anthropic

client = anthropic.Anthropic()

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