Batch-Verarbeitung
Verarbeite große Mengen von Messages-Anfragen asynchron mit der Message Batches API, senke die Kosten um 50 Prozent und erhöhe den Durchsatz.
„Batch processing“ (Stapelverarbeitung) ist ein leistungsstarker Ansatz, um große Mengen von Anfragen effizient zu verarbeiten. Anstatt Anfragen einzeln mit sofortigen Antworten zu verarbeiten, ermöglicht dir die Stapelverarbeitung, mehrere Anfragen gemeinsam zur asynchronen Verarbeitung einzureichen. Dieses Muster ist besonders nützlich, wenn:
- du große Datenmengen verarbeiten musst
- keine sofortigen Antworten erforderlich sind
- du auf Kosteneffizienz optimieren möchtest
- du groß angelegte Evaluierungen oder Analysen durchführst
Die Message Batches API implementiert dieses Muster.
Message Batches API
Die Message Batches API ist eine leistungsstarke, kostengünstige Möglichkeit, große Mengen von MessagesVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren.-Anfragen asynchron zu verarbeiten. Dieser Ansatz eignet sich gut für Aufgaben, die keine sofortigen Antworten erfordern. Die meisten Batches sind in weniger als 1 Stunde abgeschlossen, während die Kosten um 50 Prozent gesenkt und der Durchsatz erhöht wird.
Zusätzlich zu diesem Leitfaden kannst du die API-Referenz direkt erkundenVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren..
Wie die Message Batches API funktioniert
Wenn du eine Anfrage an die Message Batches API sendest:
- Das System erstellt einen neuen Message Batch mit den bereitgestellten Messages-Anfragen.
- Der Batch wird dann asynchron verarbeitet, wobei jede Anfrage unabhängig behandelt wird.
- Du kannst den Status des Batches abfragen und die Ergebnisse abrufen, sobald die Verarbeitung für alle Anfragen beendet ist.
Dies ist besonders nützlich für Massenoperationen, die keine sofortigen Ergebnisse erfordern, wie zum Beispiel:
- Groß angelegte Evaluierungen: Verarbeite Tausende von Testfällen effizient.
- Inhaltsmoderation: Analysiere große Mengen nutzergenerierter Inhalte asynchron.
- Datenanalyse: Generiere Erkenntnisse oder Zusammenfassungen für große Datensätze.
- Massengenerierung von Inhalten: Erstelle große Textmengen für verschiedene Zwecke (zum Beispiel 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 sind. Du kannst auf die 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 kannst du den Batch zwar noch ansehen, aber seine Ergebnisse stehen nicht mehr zum Download zur Verfügung.
- Batches sind auf einen Workspace in der Claude Console beschränkt. Du kannst alle Batches (und deren Ergebnisse) einsehen, die innerhalb des Workspace erstellt wurden, in dem deine Anfrage ausgeführt wird.
- Ratenlimits gelten sowohl für HTTP-Anfragen an die Batches API als auch für die Anzahl der Anfragen innerhalb eines Batches, die auf ihre Verarbeitung warten. Siehe Ratenlimits der Message Batches API. Zusätzlich kann die Verarbeitung je nach aktueller Nachfrage und deinem Anfragevolumen verlangsamt werden. In diesem Fall kann es sein, dass mehr Anfragen nach 24 Stunden ablaufen.
- Aufgrund des hohen Durchsatzes und der parallelen Verarbeitung können Batches das in der Claude Console für deinen Workspace konfigurierte Ausgabenlimit leicht überschreiten.
- Jede Anfrage in einem Batch muss
max_tokensVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren. von mindestens1haben.max_tokens: 0(Cache-Vorwärmung) wird innerhalb eines Batches nicht unterstützt, da ein während der Batch-Verarbeitung geschriebener kurzlebiger Cache-Eintrag wahrscheinlich abläuft, bevor die Folgeanfrage ausgeführt wird.
Unterstützte Modelle
Alle aktiven Modelle unterstützen die Message Batches API.
Was in Batches verarbeitet werden kann
Fast jede Anfrage, die du an die Messages API stellen kannst, kann in einen Batch aufgenommen werden. Dazu gehören:
- Vision
- Tool-Nutzung, einschließlich aller Server-Tools (Websuche, Web-Fetch, Codeausführung, MCP-Konnektoren, Advisor und Tool-Suche)
- Systemnachrichten
- Mehrstufige Unterhaltungen
- Erweitertes Nachdenken
- Die meisten Beta-Funktionen
Da jede Anfrage im Batch unabhängig verarbeitet wird, kannst du verschiedene Arten von Anfragen in einem einzigen Batch mischen.
Eine kleine Anzahl von Messages-API-Parametern wird in Batch-Anfragen nicht unterstützt. Wenn du einen davon angibst, wird ein Validierungsfehler zurückgegeben:
| Parameter | Grund |
|---|---|
stream: true | Batch-Ergebnisse werden als einzelne Datei zurückgegeben, nicht als Stream. |
speed (Fast Mode) | Der Fast Mode optimiert die synchrone Latenz, was für die asynchrone Batch-Verarbeitung nicht relevant ist. |
fallbacks (Serverseitiger Fallback) | Der serverseitige Fallback gilt nicht für Batches. Wie du abgelehnte Anfragen erneut versuchst, erfährst du unter Ablehnungen in Message Batches. |
max_tokens: 0 | Siehe Batch-Einschränkungen. |
Preise
Die Batches API bietet erhebliche Kosteneinsparungen. Die gesamte Nutzung wird mit 50 Prozent der Standard-API-Preise berechnet.
| Modell | Batch-Tokens | |
|---|---|---|
| Name | Eingabe | Ausgabe |
Claude Fable 5.2For demanding reasoning and long-horizon agentic work | 4 $ / | 20 $ / MTok |
Claude Opus 5.5For long-running agentic coding and knowledge work | 2 $ / MTok | 10 $ / MTok |
Claude Sonnet 5.5The best combination of speed and intelligence | 1 $ / MTok | 5 $ / MTok |
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing | 0,05 $ / MTokfür Prompts mit bis zu 100.000 Tokens | 0,25 $ / MTok |
0,25 $ / MTokfür Prompts mit mehr als 100.000 Tokens | 1,25 $ / MTok | |
4 $ / MTok | 20 $ / MTok | |
5 $ / MTok | 25 $ / MTok | |
5 $ / MTok | 25 $ / MTok | |
5 $ / MTok | 25 $ / MTok | |
5 $ / MTok | 25 $ / MTok | |
2,50 $ / MTok | 12,50 $ / MTok | |
2,50 $ / MTok | 12,50 $ / MTok | |
2,50 $ / MTok | 12,50 $ / MTok | |
2,50 $ / MTok | 12,50 $ / MTok | |
2,50 $ / MTok | 12,50 $ / MTok | |
Claude Opus 4.1 | 7,50 $ / MTok | 37,50 $ / MTok |
Claude Opus 4 | 7,50 $ / MTok | 37,50 $ / MTok |
1 $ / MTok | 5 $ / MTok | |
1,50 $ / MTok | 7,50 $ / MTok | |
1,50 $ / MTok | 7,50 $ / MTok | |
Claude Sonnet 4 | 1,50 $ / MTok | 7,50 $ / MTok |
0,50 $ / MTok | 2,50 $ / MTok | |
So verwendest du die Message Batches API
Deinen Batch vorbereiten und erstellen
Ein Message Batch besteht aus einer Liste von Anfragen zur Erstellung einer Message. Eine einzelne Anfrage besteht aus:
- Einer eindeutigen
custom_idVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren. zur Identifizierung der Messages-Anfrage. Sie muss 1 bis 64 Zeichen lang sein und darf nur alphanumerische Zeichen, Bindestriche und Unterstriche enthalten (entsprechend^[a-zA-Z0-9_-]{1,64}$). - Einem
paramsVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren.-Objekt mit den Standardparametern der Messages APIVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren.
Du kannst einen Batch erstellenVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren., indem du diese Liste an den Parameter requests übergibst:
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request
client = anthropic.Anthropic()
message_batch = client.messages.batches.create(
requests=[
Request(
custom_id="my-first-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hello, world",
}
],
),
),
Request(
custom_id="my-second-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hi again, friend",
}
],
),
),
]
)
print(message_batch)In diesem Beispiel werden zwei separate Anfragen zur asynchronen Verarbeitung in einem Batch zusammengefasst. Jede Anfrage hat eine eindeutige custom_id und enthält die Standardparameter, die du für einen Messages-API-Aufruf verwenden würdest.
Wenn ein Batch zum ersten Mal 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
}Deinen Batch verfolgen
Das Feld processing_statusVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren. des Message Batch gibt an, in welcher Verarbeitungsphase sich der Batch befindet. Es beginnt als in_progress und wird dann auf ended aktualisiert, sobald alle Anfragen im Batch verarbeitet wurden und die Ergebnisse bereitstehen. Du kannst den Status deines Batches überwachen, indem du die Console besuchst oder den Abruf-Endpunkt verwendest.
Abfragen des Abschlusses eines Message Batch
Um einen Message Batch abzufragen, benötigst du seine id, die in der Antwort beim Erstellen eines Batches oder beim Auflisten von Batches bereitgestellt wird. Du kannst eine Polling-Schleife implementieren, die den Batch-Status regelmäßig überprüft, bis die Verarbeitung beendet ist:
import time
client = anthropic.Anthropic()
MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
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
Du kannst alle Message Batches in deinem Workspace mit dem List-EndpunktVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren. auflisten. Die Ergebnisse sind paginiert. Das SDK ruft bei Bedarf weitere Seiten ab:
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 beendet ist, hat jede Messages-Anfrage im Batch ein Ergebnis. Es gibt vier Ergebnistypen:
| Ergebnistyp | Beschreibung |
|---|---|
succeeded | Die Anfrage war erfolgreich. Enthält das Nachrichtenergebnis. |
errored | Bei der Anfrage ist ein Fehler aufgetreten, und es wurde keine Nachricht erstellt. Mögliche Fehler sind ungültige Anfragen und interne Serverfehler. Diese Anfragen werden dir nicht in Rechnung gestellt. |
canceled | Der Nutzer hat den Batch abgebrochen, bevor diese Anfrage an das Modell gesendet werden konnte. Diese Anfragen werden dir nicht in Rechnung gestellt. |
expired | Der Batch hat seine 24-stündige Ablaufzeit erreicht, bevor diese Anfrage an das Modell gesendet werden konnte. Diese Anfragen werden dir nicht in Rechnung gestellt. |
Das request_counts-Objekt des Batches zählt die noch in Verarbeitung befindlichen Anfragen sowie die Anfragen für jeden Ergebnistyp.
Die Ergebnisse des Batches stehen über die Eigenschaft results_urlVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren. des Message Batch zum Download bereit und, sofern die Berechtigungen deiner Organisation es erlauben, auch in der Console. Da die Ergebnisse groß sein können, streame die ErgebnisseVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren., anstatt sie alle auf einmal herunterzuladen.
client = anthropic.Anthropic()
# Lies die Ergebnisdatei per Streaming in speichereffizienten Chunks und verarbeite sie einzeln
for result in client.messages.batches.results(
"msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
outcome = result.result
match outcome.type:
case "succeeded":
print(f"Success! {result.custom_id}")
case "errored":
if outcome.error.error.type == "invalid_request_error":
# Request-Body muss korrigiert werden, bevor die Anfrage erneut gesendet wird
print(f"Validation error {result.custom_id}")
else:
# Anfrage kann direkt wiederholt werden
print(f"Server error {result.custom_id}")
case "expired":
print(f"Request expired {result.custom_id}")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 kannst du je nach custom_id und Ergebnistyp unterschiedlich vorgehen. Hier ist ein Beispiel für eine Ergebnismenge:
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-5-5","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-5-5","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 dein Ergebnis einen Fehler enthält, wird sein result.error auf die standardmäßige Fehlerstruktur gesetzt.
Batch-Ergebnisse verwenden die API-Version der Anfrage, mit der der Batch erstellt wurde.
Einen Message Batch abbrechen
Du kannst einen Message Batch, der gerade verarbeitet wird, mit dem Cancel-EndpunktVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren. abbrechen. Unmittelbar nach dem Abbruch ist der processing_status eines Batches canceling. Du kannst dieselbe zuvor beschriebene Polling-Technik 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.
client = anthropic.Anthropic()
MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
message_batch = client.messages.batches.cancel(
MESSAGE_BATCH_ID,
)
print(message_batch)Die Antwort zeigt den Batch im Zustand 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
}Prompt-Caching mit Message Batches verwenden
Die Message Batches API unterstützt „prompt caching“ (Prompt-Caching), wodurch du möglicherweise Kosten und Verarbeitungszeit für Batch-Anfragen reduzieren kannst. Die Preisnachlässe von Prompt-Caching und Message Batches können kombiniert werden, was noch größere Kosteneinsparungen ermöglicht, wenn beide Funktionen zusammen verwendet werden. Da Batch-Anfragen jedoch asynchron und parallel verarbeitet werden, werden Cache-Treffer nach bestem Bemühen bereitgestellt. Nutzer erzielen in der Regel Cache-Trefferraten zwischen 30 Prozent und 98 Prozent, abhängig von ihren Traffic-Mustern.
Um die Wahrscheinlichkeit von Cache-Treffern in deinen Batch-Anfragen zu maximieren:
- Füge identische
cache_control-Blöcke in jede Message-Anfrage innerhalb deines Batches ein. - Sorge für einen stetigen Strom von Anfragen, um zu verhindern, dass Cache-Einträge nach ihrer 5-minütigen Lebensdauer ablaufen.
- Strukturiere deine Anfragen so, dass sie möglichst viele gecachte Inhalte gemeinsam nutzen.
Beispiel für die Implementierung von Prompt-Caching in einem Batch:
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request
client = anthropic.Anthropic()
message_batch = client.messages.batches.create(
requests=[
Request(
custom_id="my-first-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5-5",
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.",
}
],
),
),
Request(
custom_id="my-second-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5-5",
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 Systemnachrichten und den vollständigen Text von Stolz und Vorurteil, markiert mit cache_control, um die Wahrscheinlichkeit von Cache-Treffern zu erhöhen.
Server-Tools und die agentische Schleife
Alle Server-Tools (Websuche, Web-Fetch, Codeausführung, MCP-Konnektoren, Advisor und Tool-Suche) funktionieren in Batch-Anfragen. Der Batch-Worker führt dieselbe serverseitige agentische Schleife aus wie die synchrone Messages API.
Da keine offene Verbindung aufrechterhalten werden muss, kann die Batch-Schleife mehr Iterationen pro Turn ausführen als eine synchrone Anfrage, bevor sie stop_reason: "pause_turn" zurückgibt. Wenn ein Batch-Ergebnis mit pause_turn zurückkommt, wurde der Turn nicht abgeschlossen; du kannst ihn fortsetzen, indem du den pausierten Assistant-Inhalt in einer Folgeanfrage (Batch oder synchron) einreichst, genau wie im Fortsetzungsmuster für pause_turn gezeigt.
Der Batch-Worker drosselt außerdem web_search für jede Organisation, damit eine stark parallelisierte Batch-Verarbeitung das Ratenlimit für die Websuche deiner Organisation nicht ausschöpft. Der Batch wiederholt gedrosselte Anfragen automatisch; du musst dich nicht selbst darum kümmern, aber sehr große Websuche-Batches benötigen möglicherweise mehr Zeit bis zum Abschluss.
Erweiterte Ausgabe (Beta)
Der Beta-Header output-300k-2026-03-24 erhöht die Obergrenze für max_tokens auf 300.000 für Batch-Anfragen mit Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6 oder Claude Haiku 5.5. Füge den Header hinzu, um in einem einzigen Turn Ausgaben zu generieren, die weit über das Standardlimit von 128k max_tokens hinausgehen.
Die erweiterte Ausgabe ist nur in der Message Batches API verfügbar, nicht in der synchronen Messages API.
Verwende die erweiterte Ausgabe für die Generierung langer Texte wie Entwürfe in Buchlänge und technische Dokumentation, erschöpfende strukturierte Datenextraktion, umfangreiche Code-Generierungs-Gerüste und lange Argumentationsketten.
Eine einzelne Generierung mit 300k Token kann über eine Stunde dauern. Plane deine Batch-Einreichungen daher unter Berücksichtigung des 24-stündigen Verarbeitungsfensters. Es gelten die Standard-Batch-Preise (50 Prozent der Standard-API-Preise).
from anthropic.types.beta.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.beta.messages.batch_create_params import Request
client = anthropic.Anthropic()
message_batch = client.beta.messages.batches.create(
betas=["output-300k-2026-03-24"],
requests=[
Request(
custom_id="long-form-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5-5",
max_tokens=300_000,
messages=[
{
"role": "user",
"content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.",
}
],
),
),
],
)
print(message_batch)Best Practices für effektives Batching
So verwendest du die Batches API effektiv:
- Überwache den Status der Batch-Verarbeitung regelmäßig und implementiere eine geeignete Wiederholungslogik für fehlgeschlagene Anfragen.
- Verwende aussagekräftige
custom_id-Werte, um Ergebnisse einfach den Anfragen zuzuordnen, da die Reihenfolge nicht garantiert ist. - Erwäge, sehr große Datensätze zur besseren Handhabbarkeit auf mehrere Batches aufzuteilen.
- Führe einen Probelauf mit einer einzelnen Anfragestruktur über die Messages API durch, um Validierungsfehler zu vermeiden.
Behebung häufiger Probleme
Bei unerwartetem Verhalten:
- Überprüfe, dass die Gesamtgröße der Batch-Anfrage 256 MB nicht überschreitet. Wenn die Anfrage zu groß ist, erhältst du möglicherweise einen 413-Fehler
request_too_large. - Prüfe, ob du für alle Anfragen im Batch unterstützte Modelle verwendest.
- Stelle sicher, dass jede Anfrage im Batch eine eindeutige
custom_idhat. - Stelle sicher, dass seit dem
created_at-Zeitpunkt des Batches (nicht demended_at-Zeitpunkt der Verarbeitung) weniger als 29 Tage vergangen sind. Nach 29 Tagen stehen die Ergebnisse nicht mehr zum Download zur Verfügung. - Bestätige, dass der Batch nicht abgebrochen wurde.
Beachte, 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 über API-Anfragen im selben Workspace oder von Nutzern mit der Berechtigung zum Anzeigen von Workspace-Batches in der Console aufgerufen werden.
-
Verfügbarkeit der Ergebnisse: Batch-Ergebnisse sind 29 Tage nach der Erstellung des Batches verfügbar, sodass ausreichend Zeit für Abruf und Verarbeitung bleibt.
FAQ
Die Verarbeitung von Batches kann bis zu 24 Stunden dauern, viele sind jedoch früher abgeschlossen. Die tatsächliche Verarbeitungszeit hängt von der Größe des Batches, der aktuellen Nachfrage und deinem Anfragevolumen ab. Es ist möglich, dass ein Batch abläuft und nicht innerhalb von 24 Stunden abgeschlossen wird.
Die Liste der unterstützten Modelle findest du unter Unterstützte Modelle.
Ja, die Message Batches API unterstützt nahezu alle in der Messages API verfügbaren Funktionen, einschließlich der meisten Beta-Funktionen. Eine kleine Anzahl von Parametern (stream, speed, fallbacks und max_tokens: 0) wird nicht unterstützt. Die vollständige Liste findest du unter Was in Batches verarbeitet werden kann.
Die Message Batches API bietet einen Rabatt von 50 Prozent auf die gesamte Nutzung im Vergleich zu den Standard-API-Preisen. Dies gilt für Eingabe-Token, Ausgabe-Token und alle speziellen Token. Weitere Informationen zu den Preisen findest du unter Preise.
Nein, sobald ein Batch eingereicht wurde, kann er nicht mehr geändert werden. Wenn du Änderungen vornehmen musst, brich den aktuellen Batch ab und reiche einen neuen ein. Beachte, dass der Abbruch möglicherweise nicht sofort wirksam wird.
Die Message Batches API hat Ratenlimits auf Basis von HTTP-Anfragen sowie Limits für die Anzahl der Anfragen, die noch verarbeitet werden müssen. Siehe Ratenlimits der Message Batches API. Die Nutzung der Batches API wirkt sich nicht auf die Ratenlimits der Messages API aus.
Wenn du die Ergebnisse abrufst, hat jede Anfrage ein result-Feld, das angibt, ob sie succeeded, errored, canceled oder expired ist. Für errored-Ergebnisse werden zusätzliche Fehlerinformationen bereitgestellt. Das Fehlerantwortobjekt findest du in der API-ReferenzVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren..
Die Message Batches API wurde mit starken Maßnahmen für Datenschutz und Datentrennung entwickelt:
- Batches und ihre Ergebnisse sind innerhalb des Workspace isoliert, in dem sie erstellt wurden. Das bedeutet, dass nur API-Anfragen im selben Workspace darauf zugreifen können.
- Jede Anfrage innerhalb eines Batches wird unabhängig verarbeitet, ohne Datenlecks zwischen den Anfragen.
- Ergebnisse sind nur für einen begrenzten Zeitraum (29 Tage) verfügbar und unterliegen Anthropics Richtlinie zur Datenaufbewahrung.
- Das Herunterladen von Batch-Ergebnissen in der Console kann auf Organisationsebene oder pro Workspace deaktiviert werden.
Ja, es ist möglich, Prompt-Caching mit der Message Batches API zu verwenden. Da asynchrone Batch-Anfragen jedoch parallel und in beliebiger Reihenfolge verarbeitet werden können, werden Cache-Treffer nach bestem Bemühen bereitgestellt.
Verfügbarkeit
Claude API
- APIs
- Messages API
- Managed Agents Nicht unterstützt
- Modelle
- Alle Modelle
Claude Platform on AWS
- APIs
- Messages API
- Managed Agents Nicht unterstützt
- Modelle
- Alle Modelle
Claude Models on Google Cloud (Anthropic managed)
- APIs
- Messages API
- Managed Agents Nicht unterstützt
- Modelle
- Alle Modelle
Datenverarbeitung
Übersicht über die DatenverarbeitungZutreffende Endpunkte
/v1/messages/batches
29 Tage Aufbewahrung; asynchrone Speicherung erforderlich. Mehr erfahren
Die Stapelverarbeitung speichert Anfrage- und Antwortdaten bis zu 29 Tage nach der Erstellung des Batches. Du kannst einen Message Batch nach der Verarbeitung jederzeit über den Endpunkt DELETE /v1/messages/batches/{batch_id}Vorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren. löschen. Um einen laufenden Batch zu löschen, brich ihn zuerst ab. Die asynchrone Verarbeitung erfordert die serverseitige Speicherung sowohl der Eingaben als auch der Ausgaben bis zum Abschluss des Batches und zum Abruf der Ergebnisse.
Nächste Schritte
Erhalte natürliche Zitate für RAG-Anwendungen, indem du Suchergebnisse mit Quellenangabe bereitstellst.
Reduziere Kosten und Latenz, indem du Prompt-Präfixe cachst, die von mehreren Anfragen in einem Batch gemeinsam genutzt werden.
War diese Seite hilfreich?