Keluaran terstruktur

Keluaran terstruktur membatasi respons Claude untuk mengikuti skema tertentu, memastikan keluaran yang valid dan dapat diurai untuk pemrosesan hilir. Keluaran terstruktur menyediakan dua fitur yang saling melengkapi:

• Keluaran JSON (output_config.format): Dapatkan respons Claude dalam format JSON tertentu
• Penggunaan alat yang ketat (strict: true): Jamin validasi skema pada nama alat dan input

Anda dapat menggunakan fitur-fitur ini secara independen atau bersama-sama dalam permintaan yang sama.

Mengapa menggunakan keluaran terstruktur

Tanpa keluaran terstruktur, Claude dapat menghasilkan respons JSON yang salah bentuk atau input alat yang tidak valid yang merusak aplikasi Anda. Bahkan dengan prompt yang hati-hati, Anda mungkin mengalami:

• Kesalahan penguraian dari sintaks JSON yang tidak valid
• Bidang yang diperlukan hilang
• Tipe data yang tidak konsisten
• Pelanggaran skema yang memerlukan penanganan kesalahan dan percobaan ulang

Keluaran terstruktur menjamin respons yang sesuai dengan skema melalui decoding terbatas:

• Selalu valid: Tidak ada lagi kesalahan JSON.parse()
• Aman tipe: Tipe bidang dan bidang yang diperlukan dijamin
• Andal: Tidak perlu percobaan ulang untuk pelanggaran skema

Keluaran JSON

Keluaran JSON mengontrol format respons Claude, memastikan Claude mengembalikan JSON yang valid sesuai dengan skema Anda. Gunakan keluaran JSON ketika Anda perlu:

• Mengontrol format respons Claude
• Mengekstrak data dari gambar atau teks
• Menghasilkan laporan terstruktur
• Format respons API

Mulai cepat

Format respons: JSON yang valid sesuai dengan skema Anda di response.content[0].text

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

Cara kerjanya

Bekerja dengan output JSON di SDK

SDK menyediakan helper yang memudahkan pekerjaan dengan output JSON, termasuk transformasi skema, validasi otomatis, dan integrasi dengan perpustakaan skema populer.

Menggunakan definisi skema native

Alih-alih menulis skema JSON mentah, Anda dapat menggunakan alat definisi skema yang familiar di bahasa Anda:

• Python: Model Pydantic dengan client.messages.parse()
• TypeScript: Skema Zod dengan zodOutputFormat() atau literal JSON Schema yang diketik dengan jsonSchemaOutputFormat()
• Java: Kelas Java biasa dengan derivasi skema otomatis melalui outputConfig(Class<T>)
• Ruby: Kelas Anthropic::BaseModel dengan output_config: {format: Model}
• PHP: Kelas yang mengimplementasikan StructuredOutputModel dengan outputConfig: ['format' => MyClass::class]
• CLI, C#, : Skema JSON mentah dilewatkan melalui

Metode spesifik SDK

Setiap SDK menyediakan helper yang membuat pekerjaan dengan output terstruktur lebih mudah. Lihat halaman SDK individual untuk detail lengkap.

Cara kerja transformasi SDK

SDK Python, TypeScript, Ruby, dan PHP secara otomatis mengubah skema dengan fitur yang tidak didukung:

1. Hapus batasan yang tidak didukung (misalnya, minimum, maximum, minLength, maxLength)
2. Perbarui deskripsi dengan informasi batasan (misalnya, "Harus minimal 100"), ketika batasan tidak langsung didukung dengan output terstruktur
3. Tambahkan additionalProperties: false ke semua objek
4. Filter format string ke daftar yang didukung saja
5. Validasi respons terhadap skema asli Anda (dengan semua batasan)

Ini berarti Claude menerima skema yang disederhanakan, tetapi kode Anda masih memberlakukan semua batasan melalui validasi.

Contoh: Field Pydantic dengan minimum: 100 menjadi integer biasa dalam skema yang dikirim, tetapi SDK memperbarui deskripsi menjadi "Harus minimal 100" dan memvalidasi respons terhadap batasan asli.

Kasus penggunaan umum

Penggunaan alat yang ketat

Untuk menegakkan kepatuhan JSON Schema pada input alat dengan pengambilan sampel yang dibatasi tata bahasa, lihat Penggunaan alat yang ketat.

Menggunakan kedua fitur bersama-sama

Output JSON dan penggunaan alat ketat menyelesaikan masalah yang berbeda dan bekerja bersama:

• Output JSON mengontrol format respons Claude (apa yang Claude katakan)
• Penggunaan alat ketat memvalidasi parameter alat (bagaimana Claude memanggil fungsi Anda)

Ketika digabungkan, Claude dapat memanggil alat dengan parameter yang dijamin valid DAN mengembalikan respons JSON terstruktur. Ini berguna untuk alur kerja agentic di mana Anda memerlukan panggilan alat yang andal dan output akhir yang terstruktur.

Pertimbangan penting

Kompilasi tata bahasa dan caching

Output terstruktur menggunakan pengambilan sampel terbatas dengan artefak tata bahasa yang dikompilasi. Ini memperkenalkan beberapa karakteristik kinerja yang perlu diperhatikan:

• Latensi permintaan pertama: Pertama kali Anda menggunakan skema tertentu, ada latensi tambahan saat tata bahasa dikompilasi
• Caching otomatis: Tata bahasa yang dikompilasi di-cache selama 24 jam dari penggunaan terakhir, membuat permintaan berikutnya jauh lebih cepat
• Invalidasi cache: Cache dibatalkan jika Anda mengubah:
  • Struktur skema JSON
  • Set alat dalam permintaan Anda (saat menggunakan output terstruktur dan penggunaan alat bersama-sama)
  • Mengubah hanya bidang name atau description tidak membatalkan cache

Modifikasi prompt dan biaya token

Saat menggunakan output terstruktur, Claude secara otomatis menerima prompt sistem tambahan yang menjelaskan format output yang diharapkan. Ini berarti:

• Jumlah token input Anda sedikit lebih tinggi
• Prompt yang disuntikkan menghabiskan token Anda seperti prompt sistem lainnya
• Mengubah parameter output_config.format akan membatalkan prompt cache apa pun untuk utas percakapan tersebut

Batasan JSON Schema

Output terstruktur mendukung JSON Schema standar dengan beberapa batasan. Baik output JSON maupun penggunaan alat ketat berbagi batasan ini.

Pengurutan properti

Saat menggunakan output terstruktur, properti dalam objek mempertahankan pengurutan yang ditentukan dari skema Anda, dengan satu peringatan penting: properti yang diperlukan muncul terlebih dahulu, diikuti oleh properti opsional.

Misalnya, diberikan skema ini:

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

Output akan mengurutkan properti sebagai:

1. name (diperlukan, dalam urutan skema)
2. email (diperlukan, dalam urutan skema)
3. notes (opsional, dalam urutan skema)
4. age (opsional, dalam urutan skema)

Ini berarti output mungkin terlihat seperti:

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

Jika urutan properti dalam output penting untuk aplikasi Anda, tandai semua properti sebagai diperlukan, atau pertimbangkan pengurutan ulang ini dalam logika parsing Anda.

Output tidak valid

Meskipun output terstruktur menjamin kepatuhan skema dalam sebagian besar kasus, ada skenario di mana output mungkin tidak cocok dengan skema Anda:

Penolakan (stop_reason: "refusal")

Claude mempertahankan properti keselamatan dan kegunaannya bahkan saat menggunakan output terstruktur. Jika Claude menolak permintaan karena alasan keselamatan:

• Respons memiliki stop_reason: "refusal"
• Anda akan menerima kode status 200
• Anda akan ditagih untuk token yang dihasilkan
• Output mungkin tidak cocok dengan skema Anda karena pesan penolakan mengambil alih batasan skema

Batas token tercapai (stop_reason: "max_tokens")

Jika respons terpotong karena mencapai batas max_tokens:

• Respons memiliki stop_reason: "max_tokens"
• Output mungkin tidak lengkap dan tidak cocok dengan skema Anda
• Coba lagi dengan nilai max_tokens yang lebih tinggi untuk mendapatkan output terstruktur yang lengkap

Batasan kompleksitas skema

Output terstruktur bekerja dengan mengkompilasi skema JSON Anda menjadi tata bahasa yang membatasi output Claude. Skema yang lebih kompleks menghasilkan tata bahasa yang lebih besar yang membutuhkan waktu lebih lama untuk dikompilasi. Untuk melindungi dari waktu kompilasi yang berlebihan, API memberlakukan beberapa batasan kompleksitas.

Batasan eksplisit

Batasan berikut berlaku untuk semua permintaan dengan output_config.format atau strict: true:

Batasan internal tambahan

Di luar batasan eksplisit di atas, ada batasan internal tambahan pada ukuran tata bahasa yang dikompilasi. Batasan ini ada karena kompleksitas skema tidak berkurang menjadi dimensi tunggal: fitur seperti parameter opsional, tipe union, objek bersarang, dan jumlah alat berinteraksi satu sama lain dengan cara yang dapat membuat tata bahasa yang dikompilasi secara tidak proporsional besar.

Ketika batasan ini terlampaui, Anda akan menerima kesalahan 400 dengan pesan "Schema is too complex for compilation." Kesalahan ini berarti kompleksitas gabungan skema Anda melebihi apa yang dapat dikompilasi secara efisien, bahkan jika setiap batasan individual di atas terpenuhi. Sebagai penghenti terakhir, API juga memberlakukan waktu tunggu kompilasi 180 detik. Skema yang melewati semua pemeriksaan eksplisit tetapi menghasilkan tata bahasa yang dikompilasi sangat besar mungkin mencapai waktu tunggu ini.

Tips untuk mengurangi kompleksitas skema

Jika Anda mencapai batasan kompleksitas, coba strategi ini secara berurutan:

1. Tandai hanya alat penting sebagai ketat. Jika Anda memiliki banyak alat, cadangkan untuk alat di mana pelanggaran skema menyebabkan masalah nyata, dan andalkan kepatuhan alami Claude untuk alat yang lebih sederhana.

2. Kurangi parameter opsional. Buat parameter required jika memungkinkan. Setiap parameter opsional kira-kira menggandakan sebagian dari ruang keadaan tata bahasa. Jika parameter selalu memiliki default yang masuk akal, pertimbangkan untuk membuatnya diperlukan dan memiliki Claude memberikan default itu secara eksplisit.

3. Sederhanakan struktur bersarang. Objek bersarang dalam dengan bidang opsional menambah kompleksitas. Ratakan struktur jika memungkinkan.

4. Pisahkan menjadi beberapa permintaan. Jika Anda memiliki banyak alat ketat, pertimbangkan untuk membaginya di seluruh permintaan terpisah atau sub-agen.

Untuk masalah berkelanjutan dengan skema yang valid, hubungi dukungan dengan definisi skema Anda.

Retensi data

Prompt dan respons diproses dengan ZDR saat menggunakan output terstruktur. Namun, skema JSON itu sendiri disimpan dalam cache sementara selama hingga 24 jam sejak penggunaan terakhir untuk tujuan optimasi. Tidak ada data prompt atau respons yang disimpan di luar respons API.

Output terstruktur memenuhi syarat HIPAA, tetapi PHI tidak boleh disertakan dalam definisi skema JSON. API mengkompilasi skema JSON menjadi tata bahasa yang disimpan dalam cache terpisah dari konten pesan, dan skema yang disimpan dalam cache ini tidak menerima perlindungan PHI yang sama seperti prompt dan respons. Jangan sertakan PHI dalam nama properti skema, nilai enum, nilai const, atau ekspresi reguler pattern. PHI hanya boleh muncul dalam konten pesan (prompt dan respons), di mana dilindungi di bawah perlindungan HIPAA.

Untuk kelayakan ZDR dan HIPAA di semua fitur, lihat API dan retensi data.

Kompatibilitas fitur

Bekerja dengan:

• Pemrosesan batch: Proses output terstruktur dalam skala besar dengan diskon 50%
• Penghitungan token: Hitung token tanpa kompilasi
• Streaming: Stream output terstruktur seperti respons normal
• Penggunaan gabungan: Gunakan output JSON (output_config.format) dan penggunaan alat ketat (strict: true) bersama-sama dalam permintaan yang sama

Tidak kompatibel dengan:

• Kutipan: Kutipan memerlukan interleaving blok kutipan dengan teks, yang bertentangan dengan batasan skema JSON ketat. Mengembalikan kesalahan 400 jika kutipan diaktifkan dengan output_config.format.
• Prefilling Pesan: Tidak kompatibel dengan output JSON