结构化输出

结构化输出限制 Claude 的响应遵循特定的模式，确保有效的、可解析的输出用于下游处理。使用 JSON 输出（output_format）获取结构化数据响应，或使用严格工具使用（strict: true）确保对工具名称和输入进行模式验证。

为什么使用结构化输出

如果没有结构化输出，Claude 可能会生成格式错误的 JSON 响应或无效的工具输入，从而破坏您的应用程序。即使进行仔细的提示，您也可能会遇到：

• 来自无效 JSON 语法的解析错误
• 缺少必需字段
• 数据类型不一致
• 需要错误处理和重试的模式违规

结构化输出通过约束解码保证模式兼容的响应：

• 始终有效：不再有 JSON.parse() 错误
• 类型安全：保证字段类型和必需字段
• 可靠：不需要因模式违规而重试
• 两种模式：JSON 用于数据提取等任务，严格工具用于复杂工具和代理工作流等情况

快速开始

何时使用 JSON 输出与严格工具使用

为您的用例选择正确的模式：

为什么严格工具使用对代理很重要

构建可靠的代理系统需要保证模式一致性。无效的工具参数会破坏您的函数和工作流。Claude 可能会返回不兼容的类型（"2" 而不是 2）或缺少字段，导致运行时错误。

严格工具使用保证类型安全的参数：

• 函数每次都接收正确类型的参数
• 无需验证和重试工具调用
• 生产就绪的代理在规模上一致工作

例如，假设预订系统需要 passengers: int。在没有严格模式的情况下，Claude 可能会提供 passengers: "two" 或 passengers: "2"。使用 strict: true，您可以保证 passengers: 2。

结构化输出如何工作

在 SDK 中使用 JSON 输出

Python 和 TypeScript SDK 提供了帮助程序，使使用 JSON 输出变得更容易，包括模式转换、自动验证和与流行模式库的集成。

使用 Pydantic 和 Zod

对于 Python 和 TypeScript 开发人员，您可以使用熟悉的模式定义工具（如 Pydantic 和 Zod），而不是编写原始 JSON 模式。

from pydantic import BaseModel
from anthropic import Anthropic, transform_schema

class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
    demo_requested: bool

client = Anthropic()

# With .create() - requires transform_schema()
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm."
        }
    ],
    output_format={
        "type": "json_schema",
        "schema": transform_schema(ContactInfo),
    }
)

print(response.content[0].text)

# With .parse() - can pass Pydantic model directly
response = client.beta.messages.parse(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm."
        }
    ],
    output_format=ContactInfo,
)

print(response.parsed_output)

SDK 特定方法

Python：client.beta.messages.parse()（推荐）

parse() 方法自动转换您的 Pydantic 模型，验证响应，并返回 parsed_output 属性。

Python：transform_schema() 帮助程序

用于在发送前手动转换模式，或当您想修改 Pydantic 生成的模式时。与 client.beta.messages.parse() 不同，后者自动转换提供的模式，这给了您转换后的模式，以便您可以进一步自定义它。

SDK 转换如何工作

Python 和 TypeScript SDK 都自动转换具有不支持功能的模式：

1. 删除不支持的约束（例如 minimum、maximum、minLength、maxLength）
2. 更新描述与约束信息（例如"必须至少 100"），当约束不直接支持结构化输出时
3. 为所有对象添加 additionalProperties: false
4. 过滤字符串格式为仅支持的列表
5. 验证响应对照您的原始模式（包含所有约束）

这意味着 Claude 接收一个简化的模式，但您的代码仍然通过验证强制执行所有约束。

示例： 具有 minimum: 100 的 Pydantic 字段在发送的模式中变成普通整数，但描述更新为"必须至少 100"，SDK 根据原始约束验证响应。

常见用例

重要考虑事项

语法编译和缓存

结构化输出使用带有编译语法工件的约束采样。这引入了一些需要注意的性能特征：

• 首次请求延迟：第一次使用特定模式时，在编译语法时会有额外的延迟
• 自动缓存：编译的语法从上次使用起缓存 24 小时，使后续请求快得多
• 缓存失效：如果您更改以下内容，缓存将失效：
  • JSON 模式结构
  • 请求中的工具集（使用结构化输出和工具使用时）
  • 仅更改 name 或 description 字段不会使缓存失效

提示修改和令牌成本

使用结构化输出时，Claude 自动接收一个额外的系统提示，解释预期的输出格式。这意味着：

• 您的输入令牌计数将略高
• 注入的提示像任何其他系统提示一样花费您令牌
• 更改 output_format 参数将使该对话线程的任何 prompt cache 失效

JSON Schema 限制

结构化输出支持标准 JSON Schema，但有一些限制。JSON 输出和严格工具使用都共享这些限制。

无效输出

虽然结构化输出在大多数情况下保证模式合规性，但在某些情况下输出可能不匹配您的模式：

拒绝（stop_reason: "refusal"）

Claude 即使在使用结构化输出时也保持其安全性和有用性属性。如果 Claude 出于安全原因拒绝请求：

• 响应将具有 stop_reason: "refusal"
• 您将收到 200 状态代码
• 您将被计费生成的令牌
• 输出可能不匹配您的模式（拒绝优先）

达到令牌限制（stop_reason: "max_tokens"）

如果响应因达到 max_tokens 限制而被截断：

• 响应将具有 stop_reason: "max_tokens"
• 输出可能不完整且不匹配您的模式
• 使用更高的 max_tokens 值重试以获得完整的结构化输出

模式验证错误

如果您的模式使用不支持的功能或过于复杂，您将收到 400 错误：

"模式中的递归定义过多"

• 原因：模式具有过多或循环递归定义
• 解决方案：简化模式结构，减少嵌套深度

"模式过于复杂"

• 原因：模式超过复杂性限制
• 解决方案：分解为较小的模式，简化结构，或减少标记为 strict: true 的工具数量

对于有效模式的持续问题，请 联系支持 并提供您的模式定义。

功能兼容性

适用于：

• 批处理：以 50% 折扣大规模处理结构化输出
• 令牌计数：计数令牌而不编译
• 流式传输：像普通响应一样流式传输结构化输出
• 组合使用：在同一请求中一起使用 JSON 输出（output_format）和严格工具使用（strict: true）

不兼容：

• 引用：引用需要将引用块与文本交错，这与严格 JSON 模式约束冲突。如果启用了引用的 output_format，返回 400 错误。
• 消息预填充：与 JSON 输出不兼容