消息批处理(测试版)
消息批处理 API 是一种强大且经济高效的方式,用于异步处理大量的消息请求。这种方法非常适合不需要即时响应的任务,可以降低50%的成本同时提高吞吐量。
消息批处理 API 处于测试阶段
我们很高兴地宣布批处理 API 现已进入公开测试阶段!要访问此功能,您需要在 API 请求中包含 anthropic-beta: message-batches-2024-09-24
标头,或在 SDK 调用中使用 client.beta.messages.batches
。
我们将在接下来的几周内对这个公开测试版进行迭代,因此我们非常感谢您的反馈。请使用此表单分享您的想法和建议。
除了本指南外,您还可以直接浏览 API 参考文档。
消息批处理 API 的工作原理
当您向消息批处理 API 发送请求时:
- 系统会使用提供的消息请求创建一个新的消息批处理。
- 然后批处理会异步处理,每个请求都独立处理。
- 您可以轮询批处理的状态,并在所有请求处理完成后检索结果。
这对于不需要即时结果的批量操作特别有用,例如:
- 大规模评估:高效处理数千个测试用例。
- 内容审核:异步分析大量用户生成的内容。
- 数据分析:为大型数据集生成见解或摘要。
- 批量内容生成:为各种目的创建大量文本(例如,产品描述、文章摘要)。
批处理限制
- 一个消息批处理限制为10,000个消息请求或32 MB大小,以先达到的为准。
- 批处理最多需要24小时生成响应,但处理可能会提前结束。在整个批处理结束之前,您的批处理结果将不可用。如果处理在24小时内未完成,批处理将过期。
- 批处理结果在创建后29天内可用。之后,您仍然可以查看批处理,但其结果将不再可供下载。
- 批处理的范围限定在工作区内。您可以查看在您的 API 密钥所属工作区内创建的所有批处理及其结果。
- 速率限制适用于批处理 API 的 HTTP 请求,而不是批处理中的请求数量。此外,我们可能会根据当前需求和您的请求量来减慢处理速度。在这种情况下,您可能会看到更多请求在24小时后过期。
- 由于高吞吐量和并发处理,批处理可能会略微超过您工作区配置的支出限制。
支持的模型
消息批处理 API 目前支持:
- Claude 3.5 Sonnet (
claude-3-5-sonnet-20240620
和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
)
可以批处理的内容
您可以在批处理中包含任何可以向消息 API 发出的请求。这包括:
- 视觉
- 工具使用
- 系统消息
- 多轮对话
- 任何测试版功能
由于批处理中的每个请求都是独立处理的,您可以在单个批处理中混合使用不同类型的请求。
定价
批处理 API 提供显著的成本节省。所有使用费用按标准 API 价格的50%收取。
模型 | 批处理输入 | 批处理输出 |
---|---|---|
Claude 3.5 Sonnet | $1.50 / MTok | $7.50 / MTok |
Claude 3 Opus | $7.50 / MTok | $37.50 / MTok |
Claude 3 Haiku | $0.125 / MTok | $0.625 / MTok |
如何使用消息批处理 API
准备和创建您的批处理
消息批处理由一系列创建消息的请求组成。单个请求的结构包括:
- 用于识别消息请求的唯一
custom_id
- 包含标准消息 API参数的
params
对象
您可以通过将此列表传入 requests
参数来创建批处理:
在此示例中,两个独立的请求被批处理在一起进行异步处理。每个请求都有一个唯一的 custom_id
并包含您用于消息 API 调用的标准参数。
使用消息 API 测试您的批处理请求
每个消息请求的 params
对象的验证是异步执行的,验证错误会在整个批处理结束时返回。您可以先通过消息 API验证请求格式,以确保您正确构建输入。
当首次创建批处理时,响应的处理状态将为 in_progress
。
跟踪您的批处理
消息批处理的 processing_status
字段表示批处理所处的处理阶段。它最初为 in_progress
,然后在批处理中的所有请求完成处理且结果准备就绪时更新为 ended
。您可以通过访问控制台或使用检索端点来监控批处理的状态:
您可以轮询此端点以了解处理何时结束。
检索批处理结果
一旦批处理结束,批处理中的每个消息请求都会有一个结果。有4种结果类型:
结果类型 | 描述 |
---|---|
succeeded | 请求成功。包含消息结果。 |
errored | 请求遇到错误且未创建消息。可能的错误包括无效请求和内部服务器错误。这些请求不会收费。 |
canceled | 用户在此请求发送到模型之前取消了批处理。这些请求不会收费。 |
expired | 批处理在此请求发送到模型之前达到24小时过期时间。这些请求不会收费。 |
您可以通过批处理的 request_counts
查看结果概览,它显示了有多少请求达到了这四种状态。
批处理的结果可以在控制台和消息批处理的 results_url
上下载。由于结果可能很大,建议流式传输结果而不是一次性下载所有内容。
结果将以 .jsonl
格式呈现,其中每行都是一个有效的 JSON 对象,代表消息批处理中单个请求的结果。对于每个流式传输的结果,您可以根据其 custom_id
和结果类型执行不同的操作。以下是一个结果示例:
如果您的结果有错误,其 result.error
将设置为我们标准的错误格式。
批处理结果可能与输入顺序不匹配
批处理结果可以按任何顺序返回,可能与创建批处理时的请求顺序不匹配。在上面的示例中,第二个批处理请求的结果在第一个之前返回。要正确匹配结果与其对应的请求,请始终使用 custom_id
字段。
有效批处理的最佳实践
要充分利用批处理 API:
- 定期监控批处理处理状态并为失败的请求实施适当的重试逻辑。
- 使用有意义的
custom_id
值,以便轻松匹配结果与请求,因为顺序不能保证。 - 考虑将非常大的数据集分成多个批处理以便更好地管理。
- 使用消息 API 对单个请求格式进行预演以避免验证错误。
常见问题故障排除
如果遇到意外行为:
- 验证总批处理请求大小不超过32 MB。如果请求大小太大,您可能会收到413
request_too_large
错误。 - 检查批处理中的所有请求是否使用支持的模型。
- 确保批处理中的每个请求都有唯一的
custom_id
。 - 确保自批处理
created_at
(不是处理ended_at
)时间以来不超过29天。如果超过29天,结果将不再可见。 - 确认批处理未被取消。
请注意,批处理中一个请求的失败不会影响其他请求的处理。
批处理存储和隐私
-
工作区隔离:批处理在创建它们的工作区内是隔离的。它们只能由与该工作区关联的 API 密钥或有权在控制台中查看工作区批处理的用户访问。
-
结果可用性:批处理结果在创建后29天内可用,为检索和处理提供充足的时间。
常见问题
Was this page helpful?