使用 Anthropic Claude 模型產生結構化輸出內容

結構化輸出內容可讓您限制 Claude 模型生成的輸出內容，使其完全符合特定 JSON 結構定義。這項功能有助於確保 Claude 模型的回覆一律採用下游應用程式、資料庫和處理管道所需的精確格式。

結構化輸出內容提供兩項互補功能，您可以在同一項要求中單獨或一併使用：

  • JSON 輸出內容 (output_config.format)：將模型的回覆內容限制為符合您提供結構定義的 JSON 物件。需要從文字中擷取結構化資料、生成結構化報表或格式化 API 回應時，請使用這項功能。
  • 嚴格使用工具 (tools[].strict)：確保模型傳遞給工具的引數符合工具的 input_schema。在代理式工作流程中需要型別安全函式呼叫時，請使用這個函式。

詳情請參閱 Anthropic 的「Building with Claude: Structured Outputs」和「Strict tool use」說明文件。

支援的 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 欄位包含符合您在 output_config 中指定結構定義的 JSON 字串。

要求欄位

以下欄位專用於 JSON 輸出。如要瞭解其他要求欄位，請參閱 Claude 訊息 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 結構定義限制說明文件。