批量处理是一种高效处理大量请求的强大方法。与逐个处理请求并立即响应不同，批量处理允许您将多个请求一起提交进行异步处理。这种模式在以下情况下特别有用：

• 需要处理大量数据
• 不需要立即响应
• 希望优化成本效率
• 正在进行大规模评估或分析

消息批处理 API 是我们对这种模式的首次实现。

​

消息批处理 API

消息批处理 API 是一种强大、经济高效的方式，可以异步处理大量消息请求。这种方法非常适合不需要立即响应的任务，大多数批处理在不到1小时内完成，同时将成本降低50%并提高吞吐量。

除了本指南外，您还可以直接查看 API 参考文档。

​

消息批处理 API 的工作原理

当您向消息批处理 API 发送请求时：

1. 系统会使用提供的消息请求创建一个新的消息批处理。
2. 然后批处理会异步处理，每个请求独立处理。
3. 您可以轮询批处理的状态，并在所有请求处理完成后检索结果。

这对于不需要立即结果的批量操作特别有用，例如：

• 大规模评估：高效处理数千个测试用例。
• 内容审核：异步分析大量用户生成的内容。
• 数据分析：为大型数据集生成见解或摘要。
• 批量内容生成：为各种目的创建大量文本（例如，产品描述、文章摘要）。

​

批处理限制

• 一个消息批处理限制为100,000个消息请求或256 MB大小，以先达到者为准。
• 我们尽可能快地处理每个批次，大多数批次在1小时内完成。当所有消息完成处理或24小时后（以先到者为准），您将能够访问批处理结果。如果处理在24小时内未完成，批处理将过期。
• 批处理结果在创建后29天内可用。之后，您仍然可以查看批处理，但其结果将不再可供下载。
• 批处理的范围限定在工作区内。您可以查看API密钥所属工作区内创建的所有批处理及其结果。
• 速率限制适用于批处理API HTTP请求和等待处理的批处理中的请求数量。请参阅消息批处理API速率限制。此外，我们可能会根据当前需求和您的请求量减慢处理速度。在这种情况下，您可能会看到更多请求在24小时后过期。
• 由于高吞吐量和并发处理，批处理可能会略微超过您工作区配置的支出限制。

​

支持的模型

消息批处理API目前支持：

• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
• Claude Sonnet 3.5 (claude-3-5-sonnet-20240620 和 claude-3-5-sonnet-20241022)
• Claude Haiku 3.5 (claude-3-5-haiku-20241022)
• Claude Haiku 3 (claude-3-haiku-20240307)
• Claude Opus 3 (claude-3-opus-20240229)

​

可以批处理的内容

您可以向消息API发出的任何请求都可以包含在批处理中。这包括：

• 视觉
• 工具使用
• 系统消息
• 多轮对话
• 任何测试版功能

由于批处理中的每个请求都是独立处理的，您可以在单个批处理中混合不同类型的请求。

​

定价

批处理API提供显著的成本节约。所有使用费用按标准API价格的50%收取。

​

如何使用消息批处理API

​

准备并创建您的批处理

消息批处理由一系列创建消息的请求组成。单个请求的结构包括：

• 用于标识消息请求的唯一custom_id
• 包含标准消息API参数的params对象

您可以通过将此列表传递到requests参数中来创建批处理：

在此示例中，两个单独的请求被批处理在一起进行异步处理。每个请求都有一个唯一的custom_id，并包含您用于消息API调用的标准参数。

当批处理首次创建时，响应的处理状态为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
}

​

跟踪您的批处理

消息批处理的processing_status字段指示批处理所处的处理阶段。它开始时为in_progress，然后在批处理中的所有请求完成处理且结果准备就绪时更新为ended。您可以通过访问控制台或使用检索端点来监控批处理的状态：

您可以轮询此端点以了解处理何时结束。

​

检索批处理结果

一旦批处理结束，批处理中的每个消息请求都将有一个结果。有4种结果类型：

您将在批处理的request_counts中看到结果概览，显示有多少请求达到了这四种状态中的每一种。

批处理的结果可以从消息批处理的results_url属性下载，如果组织权限允许，也可以在控制台中下载。由于结果可能很大，建议流式传输结果而不是一次性下载所有内容。

结果将采用.jsonl格式，其中每一行都是一个有效的JSON对象，表示消息批处理中单个请求的结果。对于每个流式结果，您可以根据其custom_id和结果类型执行不同的操作。以下是一个结果示例：

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-20250514","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-20250514","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}}}}

如果您的结果有错误，其result.error将设置为我们标准的错误格式。

​

在消息批处理中使用提示缓存

消息批处理API支持提示缓存，允许您潜在地减少批处理请求的成本和处理时间。提示缓存和消息批处理的价格折扣可以叠加，当两者一起使用时提供更大的成本节约。然而，由于批处理请求是异步和并发处理的，缓存命中是尽力而为的。用户通常会经历30%到98%的缓存命中率，取决于他们的流量模式。

要最大化批处理请求中的缓存命中可能性：

1. 在批处理中的每个消息请求中包含相同的cache_control块
2. 保持稳定的请求流，防止缓存条目在5分钟的生命周期后过期
3. 构建您的请求，使其共享尽可能多的缓存内容

在批处理中实现提示缓存的示例：

在此示例中，批处理中的两个请求都包含相同的系统消息和《傲慢与偏见》的全文，并标记了cache_control以增加缓存命中的可能性。

​

有效批处理的最佳实践

要充分利用批处理API：

• 定期监控批处理处理状态，并为失败的请求实施适当的重试逻辑。
• 使用有意义的custom_id值，以便轻松匹配结果与请求，因为顺序不能保证。
• 考虑将非常大的数据集分成多个批处理，以便更好地管理。
• 使用消息API对单个请求格式进行干运行，以避免验证错误。

​

常见问题故障排除

如果遇到意外行为：

• 验证总批处理请求大小不超过256 MB。如果请求大小太大，您可能会收到413 request_too_large错误。
• 检查批处理中的所有请求是否使用支持的模型。
• 确保批处理中的每个请求都有唯一的custom_id。
• 确保自批处理created_at（不是处理ended_at）时间以来不到29天。如果已经过去了29天，结果将不再可见。
• 确认批处理未被取消。

请注意，批处理中一个请求的失败不会影响其他请求的处理。

​

批处理存储和隐私

• 工作区隔离：批处理在创建它们的工作区内是隔离的。它们只能由与该工作区关联的API密钥访问，或者由有权限在控制台中查看工作区批处理的用户访问。

• 结果可用性：批处理结果在创建后29天内可用，为检索和处理提供充足的时间。

​

常见问题