Output terstruktur

Output terstruktur membatasi respons Claude untuk mengikuti skema tertentu, memastikan output yang valid dan dapat diurai untuk pemrosesan hilir. Gunakan output JSON (output_format) untuk respons data terstruktur, atau penggunaan alat ketat (strict: true) untuk validasi skema yang dijamin pada nama alat dan input.

Mengapa menggunakan output terstruktur

Tanpa output 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

Output 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
• Dua mode: JSON untuk tugas seperti ekstraksi data, dan alat ketat untuk situasi seperti alat kompleks dan alur kerja agen

Mulai cepat

Kapan menggunakan output JSON vs penggunaan alat ketat

Pilih mode yang tepat untuk kasus penggunaan Anda:

Mengapa penggunaan alat ketat penting untuk agen

Membangun sistem agen yang andal memerlukan kepatuhan skema yang dijamin. Parameter alat yang tidak valid merusak fungsi dan alur kerja Anda. Claude mungkin mengembalikan tipe yang tidak kompatibel ("2" bukan 2) atau bidang yang hilang, menyebabkan kesalahan runtime.

Penggunaan alat ketat menjamin parameter yang aman tipe:

• Fungsi menerima argumen yang diketik dengan benar setiap saat
• Tidak perlu memvalidasi dan mencoba ulang panggilan alat
• Agen siap produksi yang bekerja secara konsisten dalam skala

Misalnya, anggaplah sistem pemesanan memerlukan passengers: int. Tanpa mode ketat, Claude mungkin memberikan passengers: "two" atau passengers: "2". Dengan strict: true, Anda dijamin passengers: 2.

Cara kerja output terstruktur

Bekerja dengan output JSON di SDK

SDK Python dan TypeScript menyediakan pembantu yang memudahkan bekerja dengan output JSON, termasuk transformasi skema, validasi otomatis, dan integrasi dengan perpustakaan skema populer.

Menggunakan Pydantic dan Zod

Untuk pengembang Python dan TypeScript, Anda dapat menggunakan alat definisi skema yang familiar seperti Pydantic dan Zod alih-alih menulis skema JSON mentah.

Metode khusus SDK

Python: client.beta.messages.parse() (Direkomendasikan)

Metode parse() secara otomatis mengubah model Pydantic Anda, memvalidasi respons, dan mengembalikan atribut parsed_output.

Python: Pembantu transform_schema()

Untuk ketika Anda perlu secara manual mengubah skema sebelum mengirim, atau ketika Anda ingin memodifikasi skema yang dihasilkan Pydantic. Tidak seperti client.beta.messages.parse(), yang secara otomatis mengubah skema yang disediakan, ini memberi Anda skema yang diubah sehingga Anda dapat menyesuaikannya lebih lanjut.

Cara kerja transformasi SDK

SDK Python dan TypeScript 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 setidaknya 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: Bidang Pydantic dengan minimum: 100 menjadi integer biasa dalam skema yang dikirim, tetapi deskripsi diperbarui menjadi "Harus setidaknya 100", dan SDK memvalidasi respons terhadap batasan asli.

Kasus penggunaan umum

Pertimbangan penting

Kompilasi tata bahasa dan caching

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

• Latensi permintaan pertama: Pertama kali Anda menggunakan skema tertentu, akan 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)
  • 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 akan sedikit lebih tinggi
• Prompt yang disuntikkan membebani Anda token seperti prompt sistem lainnya
• Mengubah parameter output_format akan membatalkan prompt cache apa pun untuk utas percakapan itu

Batasan JSON Schema

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

Output yang tidak valid

Meskipun output terstruktur menjamin kepatuhan skema dalam sebagian besar kasus, ada skenario di mana output mungkin tidak sesuai 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 akan memiliki stop_reason: "refusal"
• Anda akan menerima kode status 200
• Anda akan ditagih untuk token yang dihasilkan
• Output mungkin tidak sesuai dengan skema Anda (penolakan diutamakan)

Batas token tercapai (stop_reason: "max_tokens")

Jika respons terpotong karena mencapai batas max_tokens:

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

Kesalahan validasi skema

Jika skema Anda menggunakan fitur yang tidak didukung atau terlalu kompleks, Anda akan menerima kesalahan 400:

"Terlalu banyak definisi rekursif dalam skema"

• Penyebab: Skema memiliki definisi rekursif yang berlebihan atau siklik
• Solusi: Sederhanakan struktur skema, kurangi kedalaman nesting

"Skema terlalu kompleks"

• Penyebab: Skema melebihi batas kompleksitas
• Solusi: Pecah menjadi skema yang lebih kecil, sederhanakan struktur, atau kurangi jumlah alat yang ditandai sebagai strict: true

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

Kompatibilitas fitur

Bekerja dengan:

• Pemrosesan batch: Proses output terstruktur dalam skala dengan diskon 50%
• Penghitungan token: Hitung token tanpa kompilasi
• Streaming: Stream output terstruktur seperti respons normal
• Penggunaan gabungan: Gunakan output JSON (output_format) dan penggunaan alat ketat (strict: true) bersama 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_format.
• Prefilling Pesan: Tidak kompatibel dengan output JSON