Output terstruktur dengan model Claude dari Anthropic

Output terstruktur memungkinkan Anda membatasi output yang dihasilkan model Claude agar sesuai dengan skema JSON tertentu. Hal ini berguna untuk memastikan bahwa respons dari model Claude Anda selalu dalam format yang tepat yang diperlukan untuk aplikasi, database, dan pipeline pemrosesan hilir.

Output terstruktur menyediakan dua fitur pelengkap yang dapat Anda gunakan secara terpisah atau bersama-sama dalam permintaan yang sama:

• Output JSON (output_config.format): Membatasi respons teks model ke objek JSON yang cocok dengan skema yang Anda berikan. Gunakan ini saat Anda perlu mengekstrak data terstruktur dari teks, membuat laporan terstruktur, atau memformat respons API.
• Penggunaan alat yang ketat (tools[].strict): Menjamin bahwa argumen yang diteruskan model ke alat cocok dengan input_schema alat tersebut. Gunakan ini saat Anda memerlukan panggilan fungsi yang aman untuk jenis dalam alur kerja agentic.

Untuk mengetahui informasi selengkapnya, lihat dokumentasi Anthropic tentang Membangun dengan Claude: Output Terstruktur dan Penggunaan alat yang ketat.

Model Claude dari Anthropic yang didukung

Gemini Enterprise Agent Platform mendukung output terstruktur untuk semua model Anthropic Claude 4.5 dan yang lebih baru.

Mengontrol akses ke output terstruktur

Secara default, output terstruktur dinonaktifkan oleh batasan kebijakan organisasi constraints/vertexai.allowedPartnerModelFeatures. Untuk mengaktifkan output terstruktur, Anda harus mengonfigurasi batasan ini untuk secara eksplisit mengizinkan fitur structured_outputs.

Selain itu, Anda dapat mengonfigurasi batasan kebijakan organisasi constraints/vertexai.allowedModels untuk membatasi akses ke model Claude.

Untuk mengetahui petunjuk mendetail tentang cara mengonfigurasi batasan kebijakan organisasi, lihat Mengontrol akses ke model Model Garden.

Mengirim permintaan output terstruktur

Untuk meminta output JSON, kirim permintaan POST ke endpoint model penayang dan sertakan parameter output_config dalam isi permintaan Anda. Parameter output_config menentukan skema JSON yang harus dipatuhi oleh respons model.

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

{
  "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 -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"

$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

{
  "id": "msg_vrtx_01ABcdEFghIJklMNopQRstUV",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-7",
  "content": [
    {
      "type": "text",
      "text": "{\"name\": \"John Smith\", \"email\": \"john@example.com\", \"plan_interest\": \"Enterprise\", \"demo_requested\": true}"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 78,
    "output_tokens": 42
  }
}

Kolom permintaan

Kolom berikut khusus untuk output JSON. Untuk mengetahui informasi tentang kolom permintaan lainnya, lihat referensi API pesan Claude.

• output_config: Blok konfigurasi tingkat teratas yang mengontrol struktur respons model.
• output_config.format: Definisi format untuk output. Hanya jenis json_schema yang didukung.
• output_config.format.type: Jenis format output yang akan diterapkan. Tetapkan ke json_schema untuk membatasi respons ke objek JSON.

• output_config.format.schema: Skema JSON yang menentukan struktur respons model yang diperlukan. Output terstruktur mendukung Skema JSON standar dengan beberapa batasan, seperti mengharuskan additionalProperties disetel ke false untuk objek dan tidak mendukung batasan numerik atau panjang string. Untuk mengetahui daftar lengkap fitur yang didukung dan tidak didukung, lihat dokumentasi batasan Skema JSON Anthropic. Dalam skema, Anda biasanya menentukan:

  • type: Jenis JSON dari nilai di tingkat ini (paling umum object untuk skema root).
  • properties: Peta nama kolom ke definisi jenisnya, yang mendeskripsikan setiap kolom yang harus ditampilkan model.
  • required: Daftar nama properti yang harus disertakan model dalam responsnya.
  • additionalProperties: Nilai boolean yang, jika disetel ke false, akan mencegah model menyertakan kolom apa pun yang tidak dideklarasikan di properties.

Menggunakan alat secara ketat

Penggunaan alat yang ketat memastikan bahwa argumen yang diteruskan model ke alat cocok dengan input_schema alat. Tanpa mode ketat, model mungkin memanggil alat dengan argumen yang salah ketik (misalnya, "2", bukan 2) atau menghilangkan kolom wajib diisi, yang dapat merusak fungsi hilir dan memerlukan logika coba lagi. Dengan mengaktifkan mode ketat, API menggunakan pengambilan sampel yang dibatasi tata bahasa untuk memastikan bahwa:

• Alat name selalu menjadi salah satu alat yang Anda berikan.
• Alat input selalu sesuai dengan input_schema alat.

Gunakan penggunaan alat yang ketat saat Anda perlu memvalidasi parameter alat, membangun alur kerja agen, memastikan panggilan fungsi yang aman untuk jenis, atau menangani alat kompleks dengan properti bertumpuk.

Untuk mengaktifkan penggunaan alat yang ketat, tetapkan "strict": true sebagai kolom tingkat teratas dalam definisi alat Anda, bersama dengan name, description, dan input_schema.

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

{
  "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 -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"

$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

{
  "id": "msg_vrtx_01ABcdEFghIJklMNopQRstUV",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-7",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_vrtx_01TAJCTkxe8HhRoaQ69N4ouP",
      "name": "get_weather",
      "input": {
        "location": "San Francisco, CA",
        "unit": "fahrenheit"
      }
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 412,
    "output_tokens": 64
  }
}

Kolom penggunaan alat yang ketat

Kolom berikut khusus untuk penggunaan alat yang ketat. Untuk mengetahui informasi tentang kolom definisi alat lainnya, lihat dokumentasi Define tools Anthropic.

• tools[].strict: Boolean yang, jika disetel ke true, mengaktifkan pengambilan sampel yang dibatasi tata bahasa untuk alat. Jika strict adalah true, input alat model dibatasi agar sesuai dengan skema di input_schema. Nilai defaultnya adalah false.

• tools[].input_schema: Skema JSON yang menentukan argumen yang dapat diteruskan model ke alat. Jika strict adalah true, skema harus sesuai dengan subset Skema JSON yang sama dengan yang digunakan output JSON. Secara khusus, Anda harus:

  • Setel additionalProperties ke false pada setiap objek dalam skema.
  • Mencantumkan setiap properti dalam array required.

  Untuk mengetahui daftar lengkap fitur yang didukung dan tidak didukung, lihat dokumentasi batasan Skema JSON Anthropic.