Nachrichten-Batches (Beta)

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, reduziert die Kosten um 50% und erhöht gleichzeitig den Durchsatz.

Sie können zusätzlich zu diesem Leitfaden 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 Batch wird dann asynchron verarbeitet, wobei jede Anfrage unabhängig bearbeitet 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 zum Beispiel:

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

​

Batch-Einschränkungen

• Ein Message Batch ist auf entweder 10.000 Message-Anfragen oder 32 MB Größe beschränkt, je nachdem, was zuerst erreicht wird.
• Der Batch benötigt bis zu 24 Stunden für die Generierung von Antworten, obwohl die Verarbeitung auch früher enden kann. Die Ergebnisse für Ihren Batch sind erst verfügbar, wenn die Verarbeitung des gesamten Batches beendet ist. Batches verfallen, wenn die Verarbeitung nicht innerhalb von 24 Stunden abgeschlossen ist.
• Batch-Ergebnisse sind 29 Tage nach der Erstellung verfügbar. Danach können Sie den Batch zwar noch einsehen, aber seine Ergebnisse stehen nicht mehr zum Download zur Verfügung.
• Batches sind auf einen Workspace beschränkt. Sie können alle Batches - und deren Ergebnisse - einsehen, die innerhalb des Workspace erstellt wurden, zu dem Ihr API-Schlüssel gehört.
• Ratenlimits gelten für die Batches API HTTP-Anfragen und nicht für die Anzahl der Anfragen in einem Batch. Zusätzlich können wir die Verarbeitung basierend auf der aktuellen Nachfrage und Ihrem Anfragevolumen verlangsamen. In diesem Fall können Sie möglicherweise mehr Anfragen sehen, die nach 24 Stunden ablaufen.
• Aufgrund des hohen Durchsatzes und der parallelen Verarbeitung können Batches 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 gebatcht werden kann

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

• Vision
• Tool-Nutzung
• Systemnachrichten
• Mehrzügige 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. Alle Nutzung wird mit 50% der Standard-API-Preise berechnet.

​

Wie man die Message Batches API verwendet

​

Batch 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 Batch 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 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
}

​

Ihren Batch verfolgen

Das Feld processing_status des Message Batch zeigt an, in welcher Phase der Verarbeitung sich der Batch befindet. Es beginnt mit in_progress und wird dann zu ended aktualisiert, sobald alle Anfragen im Batch verarbeitet wurden und die Ergebnisse bereit sind. Sie können den Status Ihres Batches überwachen, indem Sie die Console besuchen oder den Abruf-Endpunkt verwenden:

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

​

Batch-Ergebnisse abrufen

Sobald die Batch-Verarbeitung beendet 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 sowohl in der Console als auch unter der results_url des 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":"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}}}}

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

​

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 sie besser verwalten zu können.
• Führen Sie einen Testlauf einer einzelnen Anfrageform mit der Messages API durch, um Validierungsfehler zu vermeiden.

​

Fehlerbehebung häufiger Probleme

Bei unerwartetem Verhalten:

• Überprüfen Sie, ob die Gesamtgröße der Batch-Anfrage 32 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 Batch verwenden.
• Stellen Sie sicher, dass jede Anfrage im Batch eine eindeutige custom_id hat.
• Stellen Sie sicher, dass seit der Batch created_at Zeit (nicht Verarbeitung ended_at) 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 beeinflusst.

​

Batch-Speicherung und Datenschutz

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

• Ergebnisverfügbarkeit: Batch-Ergebnisse sind 29 Tage nach der Batch-Erstellung 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"],
    ...
)