Die Stapelverarbeitung ist ein leistungsstarker Ansatz zur effizienten Verarbeitung großer Anfragemengen. Anstatt Anfragen einzeln mit sofortigen Antworten zu verarbeiten, ermöglicht die Stapelverarbeitung die gemeinsame Einreichung mehrerer Anfragen zur asynchronen Verarbeitung. Dieses Muster ist besonders nützlich, wenn:

• Sie große Datenmengen verarbeiten müssen
• Sofortige Antworten nicht erforderlich sind
• Sie die Kosteneffizienz optimieren möchten
• Sie umfangreiche Auswertungen oder Analysen durchführen

Die Message Batches API ist Anthropics erste Implementierung dieses Musters.

Message Batches API

Die Message Batches API ist eine leistungsstarke, kostengünstige Möglichkeit, große Mengen von Messages-Anfragen asynchron zu verarbeiten. Dieser Ansatz eignet sich gut für Aufgaben, die keine sofortigen Antworten erfordern, wobei die meisten Batches in weniger als 1 Stunde abgeschlossen werden und dabei die Kosten um 50 % reduziert und der Durchsatz erhöht wird.

Sie können die API-Referenz direkt erkunden, zusätzlich zu diesem Leitfaden.

Funktionsweise der Message Batches API

Wenn Sie eine Anfrage an die Message Batches API senden:

1. Das System erstellt einen neuen Message Batch mit den bereitgestellten Messages-Anfragen.
2. Der Batch wird dann asynchron verarbeitet, wobei jede Anfrage unabhängig behandelt wird.
3. Sie können den Status des Batches abfragen und Ergebnisse abrufen, wenn die Verarbeitung aller Anfragen abgeschlossen ist.

Dies ist besonders nützlich für Massenoperationen, die keine sofortigen Ergebnisse erfordern, wie z. B.:

• Großangelegte Auswertungen: Tausende von Testfällen effizient verarbeiten.
• Inhaltsmoderation: Große Mengen benutzergenerierter Inhalte asynchron analysieren.
• Datenanalyse: Erkenntnisse oder Zusammenfassungen für große Datensätze generieren.
• Masseninhaltsgenerierung: Große Textmengen für verschiedene Zwecke erstellen (z. B. Produktbeschreibungen, Artikelzusammenfassungen).

Batch-Einschränkungen

• Ein Message Batch ist auf entweder 100.000 Message-Anfragen oder 256 MB Größe begrenzt, je nachdem, was zuerst erreicht wird.
• Das System verarbeitet jeden Batch so schnell wie möglich, wobei die meisten Batches innerhalb von 1 Stunde abgeschlossen werden. Sie können auf Batch-Ergebnisse zugreifen, wenn alle Nachrichten abgeschlossen sind oder nach 24 Stunden, je nachdem, was zuerst eintritt. Batches laufen ab, wenn die Verarbeitung nicht innerhalb von 24 Stunden abgeschlossen wird.
• Batch-Ergebnisse sind 29 Tage nach der Erstellung verfügbar. Danach können Sie den Batch noch anzeigen, aber seine Ergebnisse stehen nicht mehr zum Download zur Verfügung.
• Batches sind auf einen Workspace beschränkt. Sie können alle Batches (und ihre Ergebnisse) anzeigen, die innerhalb des Workspace erstellt wurden, zu dem Ihr API-Schlüssel gehört.
• Rate-Limits gelten sowohl für Batches API HTTP-Anfragen als auch für die Anzahl der Anfragen innerhalb eines Batches, die auf die Verarbeitung warten. Siehe Message Batches API Rate-Limits. Darüber hinaus kann die Verarbeitung je nach aktueller Nachfrage und Ihrem Anfragevolumen verlangsamt werden. In diesem Fall können mehr Anfragen nach 24 Stunden ablaufen.
• Aufgrund des hohen Durchsatzes und der gleichzeitigen Verarbeitung können Batches das konfigurierte Ausgabenlimit Ihres Workspace leicht überschreiten.

Unterstützte Modelle

Alle aktiven Modelle unterstützen die Message Batches API.

Was in Batches verarbeitet werden kann

Jede Anfrage, die Sie an die Messages API stellen können, kann in einem Batch enthalten sein. Dazu gehören:

• Vision
• Tool use
• System-Nachrichten
• Mehrstufige Konversationen
• Alle Beta-Funktionen

Da jede Anfrage im Batch unabhängig verarbeitet wird, können Sie verschiedene Arten von Anfragen innerhalb eines einzelnen Batches mischen.

Preisgestaltung

Die Batches API bietet erhebliche Kosteneinsparungen. Die gesamte Nutzung wird zu 50 % der Standard-API-Preise berechnet.

Verwendung der Message Batches API

Batch vorbereiten und erstellen

Ein Message Batch besteht aus einer Liste von Anfragen zur Erstellung einer Message. Die Struktur einer einzelnen Anfrage umfasst:

• Eine eindeutige custom_id zur Identifizierung der Messages-Anfrage
• Ein params-Objekt mit den Standard-Messages API-Parametern

Sie können einen Batch erstellen, indem Sie diese Liste in den requests-Parameter übergeben:

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 diesem Beispiel werden zwei separate Anfragen zur asynchronen Verarbeitung zusammengefasst. Jede Anfrage hat eine eindeutige custom_id und enthält die Standardparameter, die Sie für einen Messages API-Aufruf verwenden würden.

Wenn ein Batch erstmals erstellt wird, hat die Antwort den Verarbeitungsstatus 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
}

Batch verfolgen

Das Feld processing_status des Message Batch gibt die Verarbeitungsphase des Batches an. Es beginnt als in_progress und wird dann zu ended aktualisiert, sobald alle Anfragen im Batch die Verarbeitung abgeschlossen haben und die Ergebnisse bereit sind. Sie können den Status Ihres Batches überwachen, indem Sie die Konsole besuchen oder den Abruf-Endpunkt verwenden.

Abfragen des Message Batch-Abschlusses

Um einen Message Batch abzufragen, benötigen Sie seine id, die in der Antwort beim Erstellen eines Batches oder beim Auflisten von Batches angegeben wird. Sie können eine Abfrageschleife implementieren, die den Batch-Status regelmäßig überprüft, bis die Verarbeitung abgeschlossen ist:

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)

Alle Message Batches auflisten

Sie können alle Message Batches in Ihrem Workspace mit dem Listenendpunkt auflisten. Die API unterstützt Paginierung und ruft bei Bedarf automatisch weitere Seiten ab:

import anthropic

client = anthropic.Anthropic()

# Ruft bei Bedarf automatisch weitere Seiten ab.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

Batch-Ergebnisse abrufen

Sobald die Batch-Verarbeitung abgeschlossen ist, hat jede Messages-Anfrage im Batch ein Ergebnis. Es gibt 4 Ergebnistypen:

Sie sehen eine Übersicht Ihrer Ergebnisse mit den request_counts des Batches, die zeigen, wie viele Anfragen jeden dieser vier Zustände erreicht haben.

Die Ergebnisse des Batches stehen zum Download unter der results_url-Eigenschaft des Message Batch zur Verfügung und, wenn die Organisationsberechtigung es erlaubt, in der Konsole. Aufgrund der potenziell großen Größe der Ergebnisse wird empfohlen, die Ergebnisse zu streamen, anstatt sie alle auf einmal herunterzuladen.

#!/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

Die Ergebnisse liegen im .jsonl-Format vor, wobei jede Zeile ein gültiges JSON-Objekt ist, das das Ergebnis einer einzelnen Anfrage im Message Batch darstellt. Für jedes gestreamte Ergebnis können Sie je nach custom_id und Ergebnistyp unterschiedlich vorgehen. Hier ist ein Beispielsatz von Ergebnissen:

{"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}}}}

Wenn Ihr Ergebnis einen Fehler enthält, wird result.error auf die standardmäßige Fehlerform gesetzt.

Einen Message Batch abbrechen

Sie können einen Message Batch, der gerade verarbeitet wird, mit dem Abbruch-Endpunkt abbrechen. Unmittelbar nach dem Abbruch hat der processing_status eines Batches den Wert canceling. Sie können die oben beschriebene Abfragetechnik verwenden, um zu warten, bis der Abbruch abgeschlossen ist. Abgebrochene Batches enden mit dem Status ended und können Teilergebnisse für Anfragen enthalten, die vor dem Abbruch verarbeitet wurden.

import anthropic

client = anthropic.Anthropic()

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

Die Antwort zeigt den Batch im Status 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
}

Verwendung von Prompt-Caching mit Message Batches

Die Message Batches API unterstützt Prompt-Caching, wodurch Sie potenziell Kosten und Verarbeitungszeit für Batch-Anfragen reduzieren können. Die Preisnachlässe durch Prompt-Caching und Message Batches können sich stapeln und bieten noch größere Kosteneinsparungen, wenn beide Funktionen zusammen verwendet werden. Da Batch-Anfragen jedoch asynchron und gleichzeitig verarbeitet werden, werden Cache-Treffer nach bestem Bemühen bereitgestellt. Benutzer erleben typischerweise Cache-Trefferquoten zwischen 30 % und 98 %, abhängig von ihren Traffic-Mustern.

Um die Wahrscheinlichkeit von Cache-Treffern in Ihren Batch-Anfragen zu maximieren:

1. Fügen Sie identische cache_control-Blöcke in jede Message-Anfrage innerhalb Ihres Batches ein
2. Halten Sie einen stetigen Strom von Anfragen aufrecht, um zu verhindern, dass Cache-Einträge nach ihrer 5-minütigen Lebensdauer ablaufen
3. Strukturieren Sie Ihre Anfragen so, dass so viel gecachter Inhalt wie möglich geteilt wird

Beispiel für die Implementierung von Prompt-Caching in einem 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 diesem Beispiel enthalten beide Anfragen im Batch identische System-Nachrichten und den vollständigen Text von Stolz und Vorurteil, der mit cache_control markiert ist, um die Wahrscheinlichkeit von Cache-Treffern zu erhöhen.

Best Practices für effektives Batching

Um das Beste aus der Batches API herauszuholen:

• Überwachen Sie den Batch-Verarbeitungsstatus regelmäßig und implementieren Sie geeignete Wiederholungslogik für fehlgeschlagene Anfragen.
• Verwenden Sie aussagekräftige custom_id-Werte, um Ergebnisse leicht mit Anfragen abzugleichen, da die Reihenfolge nicht garantiert ist.
• Erwägen Sie, sehr große Datensätze in mehrere Batches aufzuteilen, um die Verwaltbarkeit zu verbessern.
• Führen Sie einen Probelauf einer einzelnen Anfrage-Form mit der Messages API durch, um Validierungsfehler zu vermeiden.

Fehlerbehebung bei häufigen Problemen

Bei unerwartetem Verhalten:

• Überprüfen Sie, ob die Gesamtgröße der Batch-Anfrage 256 MB nicht überschreitet. Wenn die Anfragegröße zu groß ist, erhalten Sie möglicherweise einen 413-request_too_large-Fehler.
• Stellen Sie sicher, dass Sie unterstützte Modelle für alle Anfragen im Batch verwenden.
• Stellen Sie sicher, dass jede Anfrage im Batch eine eindeutige custom_id hat.
• Stellen Sie sicher, dass seit dem created_at-Zeitpunkt des Batches (nicht dem ended_at-Zeitpunkt der Verarbeitung) weniger als 29 Tage vergangen sind. Wenn mehr als 29 Tage vergangen sind, sind die Ergebnisse nicht mehr einsehbar.
• Bestätigen Sie, dass der Batch nicht abgebrochen wurde.

Beachten Sie, dass das Fehlschlagen einer Anfrage in einem Batch die Verarbeitung anderer Anfragen nicht beeinträchtigt.

Batch-Speicherung und Datenschutz

• Workspace-Isolierung: Batches sind innerhalb des Workspace isoliert, in dem sie erstellt wurden. Sie können nur von API-Schlüsseln zugegriffen werden, die mit diesem Workspace verknüpft sind, oder von Benutzern mit der Berechtigung, Workspace-Batches in der Console anzuzeigen.

• Ergebnisverfügbarkeit: Batch-Ergebnisse sind 29 Tage nach der Erstellung des Batches verfügbar, was ausreichend Zeit für den Abruf und die Verarbeitung bietet.

Datenspeicherung

Die Batch-Verarbeitung speichert Anfrage- und Antwortdaten bis zu 29 Tage nach der Batch-Erstellung. Sie können einen Message-Batch jederzeit nach der Verarbeitung mit dem Endpunkt DELETE /v1/messages/batches/{batch_id} löschen. Die asynchrone Verarbeitung erfordert eine serverseitige Speicherung sowohl der Eingaben als auch der Ausgaben bis zum Abschluss des Batches und dem Abruf der Ergebnisse.

Informationen zur ZDR-Berechtigung für alle Funktionen finden Sie unter API und Datenspeicherung.

FAQ