Structured outputs for Anthropic Claude models on Amazon Bedrock

Amazon Bedrock 上 Anthropic Claude 模型的结构化输出 | 人工智能

Amazon Bedrock 上 Anthropic Claude 模型的结构化输出

Amazon Bedrock 现在支持所有 Anthropic Claude 模型的结构化输出，适用于 bedrock-runtime 和 bedrock-mantle 两个端点（模型可用的区域均适用）。

无论您是通过 Boto3 和 bedrock-runtime API 调用 Claude，还是通过 Messages API 和 bedrock-mantle 端点调用，现在都可以获得符合预定义结构的 JSON 响应。您不再需要自定义解析、重试逻辑或后处理。

实际应用场景

通过 Amazon Bedrock 上的 Claude 结构化输出功能，您可以跨行业自动化可靠且符合模式的任务。例如：从财务收益报告和合规文件中提取所有必要字段、将临床笔记解析为电子健康记录（EHR）、使用一致且验证过的结果丰富产品目录。您还可以分析合同中的关键条款、各方和义务，或在智能支持工单路由中实现意图、情感和实体始终与应用程序数据模型匹配。

Amazon Bedrock 上结构化输出的变化

结构化输出通过约束解码在生成 token 时强制执行 JSON 模式，而非事后处理。模型不会生成违反模式的 token。这将输出格式从概率性转变为确定性。

目前两个互补机制已同时适用于 Amazon Bedrock 的所有端点：

| 功能 | 目的 | 用例 | |------|------|------| | JSON Schema 输出格式 | 控制模型响应结构 | 数据提取、报告生成、API 响应 | | 严格工具使用 | 验证工具参数与模式 | 代理工作流、函数调用、多步骤自动化 |

对您的意义

每个响应都是有效的 JSON，因此您将不再遇到 JSON.parse() 错误或解析异常。响应也具有类型安全性：字段类型受到强制约束，必填字段始终存在。由于输出始终符合您的模式，您无需重试处理模式违规，使集成更加可靠。结构化输出还将响应限制为模式定义的字段，这减少了输出 token 数量，可降低高吞吐量工作负载的推理成本。这些特性使结构化输出具备生产就绪能力，因此您可以大规模部署而无需额外的模式验证代码。

支持的模型和可用性

结构化输出支持批量推理，因此您可以通过异步处理大量请求，同时仍能接收符合模式的输出。在 bedrock-runtime 端点上，它还支持跨区域推理，因此您可以在不同 AWS 区域使用该功能而无需额外设置。如果需要实时响应，还可以将结构化响应作为类型化事件进行流式传输。

实现原理

当您使用 JSON 模式发起请求时，后台将发生以下过程：

• 模式验证 – Amazon Bedrock 会验证您的 JSON 模式是否符合支持的 JSON Schema Draft 2020-12 子集。
• 语法编译 – 对于新 schema，Amazon Bedrock 会编译语法工件（首次请求可能需要稍长时间）。
• 缓存 – 编译后的语法会缓存 24 小时，使后续请求更快。
• 约束生成 – 模型生成符合您 schema 的有效 JSON token。

性能注意事项

出于性能考虑，使用新 schema 的首次请求可能会稍慢，因为 Amazon Bedrock 会在生成前编译语法工件。在初始编译完成后，后续使用相同 schema 的请求开销极小，因为编译后的语法会被缓存。该缓存作用域限定于您的账户，自首次访问起有效期为 24 小时。修改 JSON schema 的结构会导致缓存失效并触发全新编译，而仅修改名称或描述字段则不会影响已缓存的语法。

入门：通过 InvokeModel API（bedrock-runtime）实现结构化输出

InvokeModel API 使用 Anthropic 原生请求体，因此 schema 以 JSON 对象形式放在 output_config.format 中，而非 JSON 字符串。以下示例演示了如何使用 boto3 和 Anthropic Claude 模型从客户邮件中提取结构化潜在客户数据：

Python

import boto3
import json

REGION = "us-east-1" # 选择您偏好的区域
bedrock_runtime = boto3.client(service_name="bedrock-runtime", region_name=REGION)

# 定义结构化输出的 JSON schema
schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "description": "客户姓名"},
        "email": {"type": "string", "description": "客户电子邮件地址"},
        "plan_interest": {"type": "string", "description": "感兴趣的计划"},
        "demo_requested": {"type": "boolean", "description": "是否请求了演示"}
    },
    "required": ["name", "email", "plan_interest", "demo_requested"],
    "additionalProperties": False
}

# 通过 InvokeModel API 发起结构化输出请求
#（重用 Converse 示例中定义的 schema）
response = bedrock_runtime.invoke_model(
    modelId="global.anthropic.claude-sonnet-5-5",
    body=json.dumps({
        "anthropic_version": "bedrock-2023-05-31",
        "max_tokens": 512,
        "messages": [
            {"role": "user", "content": (
                "Paulo Santos ([email protected]) 对我们的企业计划感兴趣 "
                "并希望在下周二下午 2 点安排演示。"
            )}
        ],
        "output_config": {"format": {"type": "json_schema", "schema": schema}}
    })
)

body = json.loads(response["body"].read())

# 在解析前检查停止原因
if body["stop_reason"] == "end_turn":
    result_text = next(b["text"] for b in body["content"] if b["type"] == "text")
    print(json.dumps(json.loads(result_text), indent=2))
elif body["stop_reason"] == "max_tokens":
    print("响应被截断：增加 max_tokens 并重试。")

JSON

{
    "name": "Paulo Santos",
    "email": "[email protected]",
    "plan_interest": "Enterprise",
    "demo_requested": true
}

响应符合您的 schema，无需额外验证。

有关其他 API 使用示例（包括 Messages API），请参阅配套的示例笔记本。

用于智能体工作流的严格工具使用

Amazon Bedrock Mantle 专为带有服务器端工具、后台推理和有状态对话的智能体应用而设计。通过在 bedrock-mantle 端点启用严格工具使用，现在可以确保工具参数与输入 schema 完全匹配。以下示例展示了如何定义具有严格 schema 强制的工具：

Import json
from anthropic import AnthropicBedrockMantle

重用 Messages API 示例中创建的客户端

client = AnthropicBedrockMantle(aws_region="us-east-1")

message = client.messages.create( model="anthropic.claude-sonnet-5", max_tokens=512, messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}], tools=[ { "name": "get_weather", "description": "Get the current weather for a specified location", "strict": True, "input_schema": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g., San Francisco, CA" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "Temperature unit" } }, "required": ["location", "unit"], "additionalProperties": False } } ] )

工具输入符合模式定义

for block in message.content: if block.type == "tool_use": print(f"Tool: {block.name}") print(f"Input: {json.dumps(block.input, indent=2)}")

将 strict: true 设置为 true 可以确保模型的工具输入完全匹配您的模式。location 字段始终是字符串，unit 字段只能是 celsius 或 fahrenheit。模型无法添加超出您模式定义的字段，因此工具输入仅包含您模式中指定的内容。

这对于在 Amazon Bedrock Mantle 上的智能体使用场景特别有价值，模型可以使用服务器端工具（如网络搜索和代码解释器）协调多步骤的工作流程。

## Claude 结构化输出的最佳应用场景

在以下三种常见模式中，结构化输出最能减少错误处理的复杂性：

- 数据提取：从发票、合同、电子邮件和转录文本中提取字段到始终符合您模式的 JSON 中，可直接加载到数据库或客户关系管理（CRM）系统中。

- 可靠的智能体工具调用：在生成时验证工具参数与其模式，确保多步骤智能体工作流程不会因输入格式错误而失败。

- 大规模分类：按意图、优先级和情感对工单、潜在客户或内容进行分类，用于路由、审核和评估。

Claude Haiku 5.5 可可靠处理快速且重复性的工作负载，如摘要、数据压缩、数据库查询和分类请求。以下示例展示了如何使用 Invoke API 和 Haiku 5.5 对传入数据进行分类和路由：

import boto3 import json

REGION = "us-east-1" # 选择您首选的区域 bedrock_runtime = boto3.client(service_name="bedrock-runtime", region_name=REGION)

# 分类模式：枚举类型将输出限制为固定标签集
schema = {
    "type": "object",
    "properties": {
        "category": {
            "type": "string",
            "enum": ["billing", "technical", "account", "sales", "other"],
            "description": "票务的主要分类"
        },
        "priority": {
            "type": "string",
            "enum": ["low", "medium", "high", "urgent"],
            "description": "基于业务影响的紧急程度"
        },
        "sentiment": {
            "type": "string",
            "enum": ["positive", "neutral", "negative"],
            "description": "客户情绪"
        },
        "escalate": {"type": "boolean", "description": "是否需要立即人工审核"},
        "reason": {"type": "string", "description": "分类的简要理由"}
    },
    "required": ["category", "priority", "sentiment", "escalate", "reason"],
    "additionalProperties": False
}

ticket = (
    "我们的生产API调用自今早以来一直出现500错误。 "
    "我们每分钟都在丢失订单。 这是本月第二次停机！"
)

# 通过InvokeModel API使用结构化输出发起请求
response = bedrock_runtime.invoke_model(
    modelId="global.anthropic.claude-haiku-5-5",
    body=json.dumps({
        "anthropic_version": "bedrock-2023-05-31",
        "max_tokens": 512,
        "system": "你是一个支持票务分类器。请准确分类票务。",
        "messages": [
            {"role": "user", "content": f"分类此支持票务:\n\n{ticket}"}
        ],
        "output_config": {"format": {"type": "json_schema", "schema": schema}}
    })
)

body = json.loads(response["body"].read())

# 解析前检查停止原因
if body["stop_reason"] == "end_turn":
    result_text = next(b["text"] for b in body["content"] if b["type"] == "text")
    result = json.loads(result_text)
    print(json.dumps(result, indent=2))
    # 根据保证有效的标签路由票务
    if result["escalate"]:
        print(f"升级给值班人员: {result['category']} / {result['priority']}")
elif body["stop_reason"] == "max_tokens":
    print("响应被截断: 增加max_tokens并重试。")

要求和最佳实践

要在Amazon Bedrock上有效使用结构化输出，请遵循以下指南：

• 在所有对象中设置additionalProperties: false : 这是结构化输出正常工作的必要条件。如果没有它，您的模式将不被接受。

• 使用描述性的字段名称和描述 : 模型使用属性名称和描述来理解需要提取的数据。像customer_email这样的清晰名称比field1等通用名称表现更好。

• 对受约束值使用enum : 当字段具有有限的有效值集时，使用enum来限制选项。

• 从基础开始，然后逐步增加复杂性 : 从所需的最小字段开始，逐步增加复杂性。基本模式编译速度更快，更容易调试，并且由于模式计入Converse API的有效载荷大小，可以保持请求有效载荷精简。

• 重用模式以利用缓存 : 构建应用程序时要重用模式。24小时语法缓存可提高重复查询的性能。

• 检查每个响应中的停止原因：可能导致不符合规范响应的两种情况是拒绝（模型因安全原因拒绝响应）和令牌限制（在完成响应前达到最大令牌数）。在代码中处理这两种情况。

• 部署前使用真实数据进行测试：将你的模式与生产环境代表输入进行验证。真实数据中的边界情况通常会暴露模式设计问题。

如需了解其他最佳实践和模式设计建议，请参阅《Amazon Bedrock用户指南》中的结构化输出章节。

支持的JSON Schema功能

• 所有基本类型：object、array、string、integer、number、boolean、null。

• enum（仅限字符串、数字、布尔值或null）。

• const、anyOf、allOf（存在限制）。

• $ref、$def和definitions（仅限内部引用）。

• 字符串格式：date-time、time、date、duration、email、hostname、uri、ipv4、ipv6、uuid。

• 数组最小项（仅支持0和1的值）。

不支持的功能

这些关键字虽然被API接受，但生成过程中不会强制执行。包含这些关键字的请求会返回成功响应，模型仍可能返回违反这些约束的值。请在应用程序中验证这些约束，而不是依赖模式来强制执行。

• 递归模式。

• 外部$ref引用。

• 数值约束（minimum、maximum、multipleOf）。

• 字符串约束（minLength、maxLength）。

• additionalProperties设置为除false以外的其他值。

结论

Amazon Bedrock上的Anthropic Claude模型结构化输出为生产级AI应用提供了所需的可靠性。该功能现已在bedrock-runtime和bedrock-mantle端点同时提供。通过结合JSON Schema输出格式和严格的工具使用，您可以构建无需额外验证的数据管道。您还可以创建可靠的智能代理工作流和生产级AI应用，无需自定义解析或重试逻辑。

Amazon Bedrock上的Claude结构化输出功能现已正式发布。如需了解更多详情，请参阅Amazon Bedrock文档并查看我们的示例笔记本。

验证后的、符合模式的JSON可以改进您组织中的哪些工作流程？在评论区分享您的反馈和问题。

作者简介

'\"`