结构化输出

结构化输出约束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参数将使该对话线程的任何提示缓存失效

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输出不兼容