Die Stapelverarbeitung ist ein leistungsfähiger Ansatz zur effizienten Verarbeitung großer Mengen von Anfragen. Anstatt Anfragen einzeln mit sofortigen Antworten zu verarbeiten, ermöglicht die Stapelverarbeitung die gemeinsame Übermittlung 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 großangelegte Auswertungen oder Analysen durchführen

Die Message Batches API ist unsere erste Implementierung dieses Musters.

​

Message Batches API

Die Message Batches API ist eine leistungsstarke, kosteneffektive Möglichkeit zur asynchronen Verarbeitung großer Mengen von Messages-Anfragen. Dieser Ansatz eignet sich gut für Aufgaben, die keine sofortigen Antworten erfordern, wobei die meisten Stapel in weniger als 1 Stunde abgeschlossen werden, während die Kosten um 50% reduziert und der Durchsatz erhöht wird.

Sie können zusätzlich zu dieser Anleitung direkt die API-Referenz erkunden.

​

Wie die Message Batches API funktioniert

Wenn Sie eine Anfrage an die Message Batches API senden:

1. Erstellt das System einen neuen Message Batch mit den bereitgestellten Messages-Anfragen.
2. Der Stapel wird dann asynchron verarbeitet, wobei jede Anfrage unabhängig bearbeitet wird.
3. Sie können den Status des Stapels abfragen und Ergebnisse abrufen, wenn die Verarbeitung aller Anfragen beendet ist.

Dies ist besonders nützlich für Massenvorgänge, die keine sofortigen Ergebnisse erfordern, wie:

• Großangelegte Auswertungen: Effiziente Verarbeitung tausender Testfälle.
• Inhaltsmoderation: Asynchrone Analyse großer Mengen nutzergenerierter Inhalte.
• Datenanalyse: Generierung von Erkenntnissen oder Zusammenfassungen für große Datensätze.
• Masseninhaltserstellung: Erstellung großer Textmengen für verschiedene Zwecke (z.B. Produktbeschreibungen, Artikelzusammenfassungen).

​

Stapelbeschränkungen

• Ein Message Batch ist auf entweder 100.000 Message-Anfragen oder 256 MB Größe beschränkt, je nachdem, was zuerst erreicht wird.
• Wir verarbeiten jeden Stapel so schnell wie möglich, wobei die meisten Stapel innerhalb von 1 Stunde abgeschlossen werden. Sie können auf die Stapelergebnisse zugreifen, wenn alle Nachrichten abgeschlossen sind oder nach 24 Stunden, je nachdem, was zuerst eintritt. Stapel verfallen, wenn die Verarbeitung nicht innerhalb von 24 Stunden abgeschlossen ist.
• Stapelergebnisse sind 29 Tage nach der Erstellung verfügbar. Danach können Sie den Stapel noch anzeigen, aber seine Ergebnisse stehen nicht mehr zum Download zur Verfügung.
• Stapel sind auf einen Workspace beschränkt. Sie können alle Stapel und deren Ergebnisse einsehen, die innerhalb des Workspace erstellt wurden, zu dem Ihr API-Schlüssel gehört.
• Ratenbegrenzungen gelten sowohl für Batches API HTTP-Anfragen als auch für die Anzahl der Anfragen innerhalb eines Stapels, die auf Verarbeitung warten. Siehe Message Batches API Ratenbegrenzungen. Zusätzlich können wir die Verarbeitung basierend auf der aktuellen Nachfrage und Ihrem Anfragevolumen verlangsamen. In diesem Fall können Sie mehr Anfragen sehen, die nach 24 Stunden ablaufen.
• Aufgrund des hohen Durchsatzes und der gleichzeitigen Verarbeitung können Stapel das konfigurierte Ausgabenlimit Ihres Workspace leicht überschreiten.

​

Unterstützte Modelle

Die Message Batches API unterstützt derzeit:

• Claude 3.5 Sonnet (claude-3-5-sonnet-20240620 und 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)

​

Was gestapelt werden kann

Jede Anfrage, die Sie an die Messages API stellen können, kann in einem Stapel enthalten sein. Dies umfasst:

• Vision
• Tool-Nutzung
• Systemnachrichten
• Mehrzügige Konversationen
• Alle Beta-Funktionen

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

​

Preisgestaltung

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

​

Wie man die Message Batches API verwendet

​

Stapel vorbereiten und erstellen

Ein Message Batch besteht aus einer Liste von Anfragen zum Erstellen einer Nachricht. Die Form einer einzelnen Anfrage besteht aus:

• Einer eindeutigen custom_id zur Identifizierung der Messages-Anfrage
• Einem params-Objekt mit den Standard Messages API-Parametern

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

In diesem Beispiel werden zwei separate Anfragen für die asynchrone 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 Stapel zuerst erstellt wird, hat die Antwort einen Verarbeitungsstatus von 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
}

​

Ihren Stapel verfolgen

Das processing_status-Feld des Message Batch zeigt die Phase der Stapelverarbeitung an. Es beginnt als in_progress, dann wird es zu ended aktualisiert, sobald alle Anfragen im Stapel die Verarbeitung abgeschlossen haben und die Ergebnisse bereit sind. Sie können den Status Ihres Stapels überwachen, indem Sie die Console besuchen oder den Abruf-Endpunkt verwenden:

Sie können diesen Endpunkt abfragen, um zu erfahren, wann die Verarbeitung beendet wurde.

​

Stapelergebnisse abrufen

Sobald die Stapelverarbeitung beendet ist, hat jede Messages-Anfrage im Stapel ein Ergebnis. Es gibt 4 Ergebnistypen:

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

Die Ergebnisse des Stapels stehen sowohl in der Console als auch unter der results_url auf dem Message Batch zum Download zur Verfügung. Aufgrund der potenziell großen Größe der Ergebnisse wird empfohlen, Ergebnisse zu streamen, anstatt sie alle auf einmal herunterzuladen.

Die Ergebnisse werden im .jsonl-Format sein, 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 reagieren. Hier ist ein Beispiel für Ergebnisse:

{"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":"Hallo nochmal! Schön, Sie zu sehen. Wie kann ich Ihnen heute helfen? Gibt es etwas Bestimmtes, worüber Sie sprechen möchten, oder haben Sie Fragen?"}],"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":"Hallo! Wie kann ich Ihnen heute helfen? Fragen Sie ruhig, wenn Sie Fragen haben oder wenn es etwas gibt, worüber Sie sprechen möchten."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}

Wenn Ihr Ergebnis einen Fehler hat, wird sein result.error auf unsere Standard-Fehlerform gesetzt.

​

Verwendung von Prompt-Caching mit Message Batches

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

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

1. Fügen Sie identische cache_control-Blöcke in jede Message-Anfrage innerhalb Ihres Stapels 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 sie möglichst viele zwischengespeicherte Inhalte teilen

Beispiel für die Implementierung von Prompt-Caching in einem Stapel:

In diesem Beispiel enthalten beide Anfragen im Stapel identische Systemnachrichten 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 effektive Stapelverarbeitung

Um das Beste aus der Batches API herauszuholen:

• Überwachen Sie den Stapelverarbeitungsstatus 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 Stapel aufzuteilen, um sie besser verwalten zu können.
• Testen Sie eine einzelne Anfrageform mit der Messages API, um Validierungsfehler zu vermeiden.

​

Fehlerbehebung häufiger Probleme

Bei unerwartetem Verhalten:

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

Beachten Sie, dass das Fehlschlagen einer Anfrage in einem Stapel die Verarbeitung anderer Anfragen nicht beeinflusst.

​

Stapelspeicherung und Datenschutz

• Workspace-Isolation: Stapel sind innerhalb des Workspace isoliert, in dem sie erstellt wurden. Sie können nur mit API-Schlüsseln zugegriffen werden, die diesem Workspace zugeordnet sind, oder von Benutzern mit der Berechtigung, Workspace-Stapel in der Console einzusehen.

• Ergebnisverfügbarkeit: Stapelergebnisse sind 29 Tage nach der Stapelerstellung verfügbar, was ausreichend Zeit für Abruf und Verarbeitung bietet.

​

FAQ

import anthropic

client = anthropic.Anthropic()

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