使用 Anthropic Claude 模型生成结构化输出

借助结构化输出，您可以限制 Claude 模型生成的输出，使其完全符合特定的 JSON 架构。这有助于确保 Claude 模型的回答始终采用下游应用、数据库和处理流水线所需的精确格式。

结构化输出提供两项互补的功能，您可以在同一请求中单独使用或一起使用：

  • JSON 输出 (output_config.format)：将模型的文本回答限制为与您提供的架构匹配的 JSON 对象。当您需要从文本中提取结构化数据、生成结构化报告或设置 API 响应的格式时，请使用此功能。
  • 严格使用工具 (tools[].strict)：保证模型传递给工具的实参与工具的 input_schema 相匹配。当您需要在智能体工作流中进行类型安全的功能调用时，请使用此功能。

如需了解详情，请参阅 Anthropic 的使用 Claude 构建：结构化输出和严格的工具使用文档。

受支持的 Anthropic Claude 模型

Gemini Enterprise Agent Platform 支持所有 Anthropic Claude 4.5 及更高版本的模型的结构化输出。

控制对结构化输出的访问权限

默认情况下，组织政策限制条件 constraints/vertexai.allowedPartnerModelFeatures 会停用结构化输出。如需启用结构化输出，您必须配置此限制，以明确允许使用 structured_outputs 功能。

此外，您还可以配置组织政策限制条件 constraints/vertexai.allowedModels，以限制对 Claude 模型的访问权限。

如需详细了解如何配置组织政策限制条件，请参阅控制对 Model Garden 模型的访问权限。

发送结构化输出请求

如需请求 JSON 输出，请向发布方模型端点发送 POST 请求，并在请求正文中添加 output_config 参数。output_config 参数用于指定模型回答必须符合的 JSON 架构。

REST

以下示例展示了如何向 Agent Platform API 发送请求，以从非结构化电子邮件中提取结构化联系信息。响应仅限于包含 name、email、plan_interest 和 demo_requested 字段的 JSON 对象。

在使用任何请求数据之前，请先进行以下替换：

  • LOCATION：支持 Anthropic Claude 模型的区域。如需使用全球端点，请参阅指定全球端点。
  • MODEL：受支持的 Claude 模型，例如 claude-opus-4-7。
  • ROLE：与消息关联的角色。您可以指定 user 或 assistant。第一条消息必须使用 user 角色。Claude 模型使用交替的 user 和 assistant 回合运行。如果最终消息使用 assistant 角色，则回答内容会立即从该消息中的内容继续。您可以使用它来限制模型的部分回答。
  • CONTENT：user 或 assistant 消息的内容（如文本）。例如 Extract the key information from this email: John Smith (john@example.com) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm.
  • MAX_TOKENS：响应中可生成的词元数量上限。一个词元约为　3.5 个字符。100 个词元对应大约 60-80 个单词。

    指定较低的值可获得较短的回答，指定较高的值可获得可能较长的回答。

  • STREAM：一个布尔值，用于指定是否流式传输回答。设置为 true 可流式传输回答，设置为 false 可一次性返回所有回答。结构化输出通常通过 false 返回。

该示例使用以下结构化输出字段。如需详细了解每个字段，请参阅请求字段部分。

  • output_config：用于控制模型回答结构的顶级配置块。
  • output_config.format.type：设置为 json_schema 可将响应限制为符合所提供架构的 JSON 对象。
  • output_config.format.schema：一种 JSON 架构，用于定义模型响应的必需结构。架构必须符合受支持的 JSON 架构子集。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict

请求 JSON 正文： 

{
  "anthropic_version": "vertex-2023-10-16",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_TOKENS,
  "stream": STREAM,
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "email": {"type": "string"},
          "plan_interest": {"type": "string"},
          "demo_requested": {"type": "boolean"}
        },
        "required": ["name", "email", "plan_interest", "demo_requested"],
        "additionalProperties": false
      }
    }
  }
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict"

PowerShell

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应。content 块的 text 字段包含一个 JSON 字符串，该字符串符合您在 output_config 中指定的架构。

请求字段

以下字段是 JSON 输出特有的。如需了解其他请求字段，请参阅 Claude messages API 参考文档。

  • output_config：用于控制模型回答结构的顶级配置块。
  • output_config.format：输出的格式定义。仅支持 json_schema 类型。
  • output_config.format.type：要强制执行的输出格式类型。将此属性设置为 json_schema 可将响应限制为 JSON 对象。

  • output_config.format.schema：一个 JSON 架构，用于定义模型回答的必需结构。结构化输出支持标准 JSON 架构，但有一些限制，例如要求将对象的 additionalProperties 设置为 false，并且不支持数值或字符串长度限制。如需查看受支持和不受支持的功能的完整列表，请参阅 Anthropic 的 JSON 架构限制文档。在架构中，您通常会指定：

    • type：相应层级的值的 JSON 类型（根架构最常见的是 object）。
    • properties：一个字段名称到其类型定义的映射，用于描述模型必须返回的每个字段。
    • required：模型必须在其响应中包含的属性名称列表。
    • additionalProperties：一个布尔值，设置为 false 时，可防止模型包含未在 properties 中声明的任何字段。

严格使用工具

严格的工具使用可确保模型传递给工具的实参与工具的 input_schema 相匹配。如果不使用严格模式，模型可能会使用类型错误的实参（例如，"2" 而不是 2）调用工具，或者省略必需字段，这可能会导致下游函数中断，并需要重试逻辑。启用严格模式后，API 会使用语法约束采样来确保：

  • 工具 name 始终是您提供的工具之一。
  • 工具 input 始终符合工具的 input_schema。

当您需要验证工具参数、构建代理工作流、确保类型安全的功能调用或处理具有嵌套属性的复杂工具时，请使用严格的工具使用。

如需启用严格的工具使用，请将 "strict": true 设置为工具定义中的顶级字段，与 name、description 和 input_schema 并列。

REST

以下示例展示了如何向 Agent Platform API 发送请求，以定义严格的 get_weather 工具。模型保证会使用 location 字符串和可选的 unit（值为 celsius 或 fahrenheit）来调用工具。

在使用任何请求数据之前，请先进行以下替换：

  • LOCATION：支持 Anthropic Claude 模型的区域。如需使用全球端点，请参阅指定全球端点。
  • MODEL：受支持的 Claude 模型，例如 claude-opus-4-7。
  • ROLE：与消息关联的角色。第一条消息必须使用 user 角色。
  • CONTENT：user 或 assistant 消息的内容（如文本）。例如 What is the weather in San Francisco?
  • MAX_TOKENS：响应中可生成的词元数量上限。一个词元约为　3.5 个字符。100 个词元对应大约 60-80 个单词。

    指定较低的值可获得较短的回答，指定较高的值可获得可能较长的回答。

  • STREAM：一个布尔值，用于指定是否流式传输回答。设置为 true 可流式传输回答，设置为 false 可一次性返回所有回答。

该示例使用以下严格的工具使用字段。如需详细了解每个字段，请参阅严格的工具使用字段部分。

  • tools[].strict：一个布尔值，设置为 true 时，可为该工具启用语法约束采样。模型保证会使用与 input_schema 匹配的实参调用工具。
  • tools[].input_schema：一种 JSON 架构，用于定义模型可以传递给工具的实参。如果 strict 为 true，则架构必须符合与 JSON 输出的 output_config 架构相同的受支持的 JSON 架构子集。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict

请求 JSON 正文： 

{
  "anthropic_version": "vertex-2023-10-16",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_TOKENS,
  "stream": STREAM,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "strict": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, for example San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"]
          }
        },
        "required": ["location"],
        "additionalProperties": false
      }
    }
  ]
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict"

PowerShell

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应。tool_use 内容块包含一个 input 字段，该字段的键和值类型保证与工具的 input_schema 相匹配。

严格的工具使用字段

以下字段专门用于严格的工具使用。如需了解其他工具定义字段，请参阅 Anthropic 的定义工具文档。

  • tools[].strict：一个布尔值，设置为 true 时，可为该工具启用语法约束采样。当 strict 为 true 时，模型工具输入会受到限制，以匹配 input_schema 中的架构。默认值为 false。

  • tools[].input_schema：一种 JSON 架构，用于定义模型可以传递给工具的实参。当 strict 为 true 时，架构必须符合 JSON 输出所使用的相同 JSON 架构子集。具体而言，您必须执行以下操作：

    • 将架构中每个对象的 additionalProperties 设置为 false。
    • 列出 required 数组中的每个属性。

    如需查看受支持和不受支持的功能的完整列表，请参阅 Anthropic 的 JSON 架构限制文档。