结构化输出

结构化输出限制 Claude 的响应遵循特定的模式，确保有效的、可解析的输出用于下游处理。结构化输出提供两个互补的功能：

• JSON 输出 (output_config.format)：获取 Claude 特定 JSON 格式的响应
• 严格工具使用 (strict: true)：保证工具名称和输入的模式验证

您可以在同一请求中独立使用这些功能或一起使用。

为什么使用结构化输出

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

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

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

• 始终有效：不再有 JSON.parse() 错误
• 类型安全：保证字段类型和必需字段
• 可靠：不需要为模式违规重试

JSON 输出

JSON 输出控制 Claude 的响应格式，确保 Claude 返回与您的模式匹配的有效 JSON。在以下情况下使用 JSON 输出：

• 控制 Claude 的响应格式
• 从图像或文本中提取数据
• 生成结构化报告
• 格式化 API 响应

快速开始

响应格式： 与您的模式匹配的有效 JSON，位于 response.content[0].text 中

{
  "name": "John Smith",
  "email": "[email protected]",
  "plan_interest": "Enterprise",
  "demo_requested": true
}

工作原理

在 SDK 中使用 JSON 输出

SDK 提供了辅助工具，使得使用 JSON 输出变得更加容易，包括模式转换、自动验证以及与流行模式库的集成。

使用原生模式定义

与其编写原始 JSON 模式，你可以在你的语言中使用熟悉的模式定义工具：

• Python：使用 client.messages.parse() 的 Pydantic 模型
• TypeScript：使用 zodOutputFormat() 的 Zod 模式或使用 jsonSchemaOutputFormat() 的类型化 JSON Schema 字面量
• Java：通过 outputConfig(Class<T>) 进行自动模式推导的普通 Java 类
• Ruby：使用 output_config: {format: Model} 的 Anthropic::BaseModel 类
• PHP：实现 StructuredOutputModel 的类，使用 outputConfig: ['format' => MyClass::class]
• CLI、C#、Go：通过 output_config 传递的原始 JSON 模式

SDK 特定方法

每个 SDK 都提供了辅助工具，使得使用结构化输出变得更加容易。有关完整详情，请参阅各个 SDK 页面。

SDK 转换如何工作

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

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

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

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

常见用例

严格工具使用

有关使用语法约束采样在工具输入上强制执行 JSON Schema 合规性的信息，请参阅严格工具使用。

同时使用两个功能

JSON 输出和严格工具使用解决不同的问题并协同工作：

• JSON 输出控制 Claude 的响应格式（Claude 说什么）
• 严格工具使用验证工具参数（Claude 如何调用您的函数）

结合使用时，Claude 可以使用保证有效的参数调用工具，并返回结构化的 JSON 响应。这对于需要可靠工具调用和结构化最终输出的代理工作流很有用。

重要考虑事项

语法编译和缓存

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

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

提示修改和令牌成本

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

• 您的输入令牌计数略高
• 注入的提示像任何其他系统提示一样消耗令牌
• 更改 output_config.format 参数将使该对话线程的任何提示缓存失效

JSON Schema 限制

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

属性排序

使用结构化输出时，对象中的属性保持从您的模式定义的顺序，但有一个重要的注意事项：必需属性首先出现，然后是可选属性。

例如，给定此模式：

{
  "type": "object",
  "properties": {
    "notes": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

输出将按以下顺序排列属性：

1. name（必需，按模式顺序）
2. email（必需，按模式顺序）
3. notes（可选，按模式顺序）
4. age（可选，按模式顺序）

这意味着输出可能如下所示：

{
  "name": "John Smith",
  "email": "[email protected]",
  "notes": "Interested in enterprise plan",
  "age": 35
}

如果输出中的属性顺序对您的应用程序很重要，请将所有属性标记为必需，或在您的解析逻辑中考虑此重新排序。

无效输出

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

拒绝（stop_reason: "refusal"）

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

• 响应具有 stop_reason: "refusal"
• 您将收到 200 状态代码
• 您将被计费生成的令牌
• 输出可能不匹配您的模式，因为拒绝消息优先于模式约束

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

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

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

模式复杂性限制

结构化输出通过将您的 JSON 模式编译为限制 Claude 输出的语法来工作。更复杂的模式会产生更大的语法，编译时间更长。为了防止过度的编译时间，API 强制执行多个复杂性限制。

显式限制

以下限制适用于所有具有 output_config.format 或 strict: true 的请求：

额外的内部限制

除了上述显式限制外，编译语法大小还有额外的内部限制。这些限制存在是因为模式复杂性不能简化为单一维度：可选参数、联合类型、嵌套对象和工具数量等功能以可能使编译语法不成比例地大的方式相互作用。

当超过这些限制时，您将收到 400 错误，消息为"Schema is too complex for compilation"。这些错误意味着您的模式的组合复杂性超过了可以有效编译的范围，即使每个上述单独的限制都得到满足。作为最后的防止措施，API 还强制执行编译超时 180 秒。通过所有显式检查但产生非常大的编译语法的模式可能会触发此超时。

减少模式复杂性的提示

如果您遇到复杂性限制，请按顺序尝试这些策略：

1. **仅将关键工具标记为严格。**如果您有许多工具，请为模式违规会导致真正问题的工具保留它，并依靠 Claude 对更简单工具的自然遵守。

2. **减少可选参数。**尽可能使参数 required。每个可选参数大约会使语法状态空间的一部分翻倍。如果参数总是有合理的默认值，请考虑使其成为必需的，并让 Claude 明确提供该默认值。

3. **简化嵌套结构。**具有可选字段的深层嵌套对象会加剧复杂性。尽可能展平结构。

4. **分成多个请求。**如果您有许多严格工具，请考虑将它们分散到单独的请求或子代理中。

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

数据保留

使用结构化输出时，提示和响应使用 ZDR 处理。但是，JSON 模式本身会临时缓存长达 24 小时（自上次使用以来）以用于优化目的。API 响应之外不保留任何提示或响应数据。

结构化输出符合 HIPAA 资格，但JSON 模式定义中不得包含 PHI。API 将 JSON 模式编译为与消息内容分开缓存的语法，这些缓存的模式不会获得与提示和响应相同的 PHI 保护。不要在模式属性名称、enum 值、const 值或 pattern 正则表达式中包含 PHI。PHI 应仅出现在消息内容（提示和响应）中，其中受 HIPAA 保护措施保护。

有关所有功能的 ZDR 和 HIPAA 资格，请参阅 API 和数据保留。

功能兼容性

适用于：

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

不兼容：

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