Membangun dengan pemikiran yang diperluas

Cara kerja pemikiran yang diperluas

Ketika pemikiran yang diperluas diaktifkan, Claude membuat blok konten thinking di mana ia mengeluarkan penalaran internalnya. Claude menggabungkan wawasan dari penalaran ini sebelum menyusun respons akhir.

Respons API akan mencakup blok konten thinking, diikuti oleh blok konten text.

Berikut adalah contoh format respons default:

Untuk informasi lebih lanjut tentang format respons pemikiran yang diperluas, lihat Referensi API Pesan.

Cara menggunakan pemikiran yang diperluas

Berikut adalah contoh penggunaan pemikiran yang diperluas dalam API Pesan:

Untuk mengaktifkan pemikiran yang diperluas, tambahkan objek thinking, dengan parameter type diatur ke enabled dan budget_tokens ke anggaran token yang ditentukan untuk pemikiran yang diperluas.

Parameter budget_tokens menentukan jumlah maksimum token yang diizinkan Claude gunakan untuk proses penalaran internalnya. Dalam model Claude 4, batas ini berlaku untuk token pemikiran penuh, dan bukan untuk keluaran ringkasan. Anggaran yang lebih besar dapat meningkatkan kualitas respons dengan memungkinkan analisis yang lebih menyeluruh untuk masalah kompleks, meskipun Claude mungkin tidak menggunakan seluruh anggaran yang dialokasikan, terutama pada rentang di atas 32k.

budget_tokens harus diatur ke nilai yang kurang dari max_tokens. Namun, ketika menggunakan pemikiran yang disisipi dengan alat, Anda dapat melampaui batas ini karena batas token menjadi seluruh jendela konteks Anda (200k token).

Pemikiran ringkasan

Dengan pemikiran yang diperluas diaktifkan, API Pesan untuk model Claude 4 mengembalikan ringkasan dari proses pemikiran penuh Claude. Pemikiran ringkasan memberikan manfaat intelijen penuh dari pemikiran yang diperluas, sambil mencegah penyalahgunaan.

Berikut adalah beberapa pertimbangan penting untuk pemikiran ringkasan:

• Anda dikenakan biaya untuk token pemikiran penuh yang dihasilkan oleh permintaan asli, bukan token ringkasan.
• Jumlah token keluaran yang ditagih akan tidak cocok dengan jumlah token yang Anda lihat dalam respons.
• Beberapa baris pertama dari keluaran pemikiran lebih verbose, memberikan penalaran terperinci yang sangat membantu untuk tujuan rekayasa prompt.
• Saat Anthropic berusaha meningkatkan fitur pemikiran yang diperluas, perilaku ringkasan dapat berubah.
• Ringkasan mempertahankan ide-ide kunci dari proses pemikiran Claude dengan latensi tambahan minimal, memungkinkan pengalaman pengguna yang dapat dialirkan dan migrasi mudah dari Claude Sonnet 3.7 ke model Claude 4.
• Ringkasan diproses oleh model yang berbeda dari yang Anda targetkan dalam permintaan Anda. Model pemikiran tidak melihat keluaran ringkasan.

Pemikiran streaming

Anda dapat melakukan streaming respons pemikiran yang diperluas menggunakan server-sent events (SSE).

Ketika streaming diaktifkan untuk pemikiran yang diperluas, Anda menerima konten pemikiran melalui acara thinking_delta.

Untuk dokumentasi lebih lanjut tentang streaming melalui API Pesan, lihat Pesan Streaming.

Berikut adalah cara menangani streaming dengan pemikiran:

Contoh keluaran streaming:

Pemikiran yang diperluas dengan penggunaan alat

Pemikiran yang diperluas dapat digunakan bersama dengan penggunaan alat, memungkinkan Claude untuk bernalar melalui pemilihan alat dan pemrosesan hasil.

Ketika menggunakan pemikiran yang diperluas dengan penggunaan alat, perhatikan batasan berikut:

1. Batasan pilihan alat: Penggunaan alat dengan pemikiran hanya mendukung tool_choice: {"type": "auto"} (default) atau tool_choice: {"type": "none"}. Menggunakan tool_choice: {"type": "any"} atau tool_choice: {"type": "tool", "name": "..."} akan menghasilkan kesalahan karena opsi ini memaksa penggunaan alat, yang tidak kompatibel dengan pemikiran yang diperluas.

2. Mempertahankan blok pemikiran: Selama penggunaan alat, Anda harus meneruskan blok thinking kembali ke API untuk pesan asisten terakhir. Sertakan blok yang lengkap dan tidak dimodifikasi kembali ke API untuk mempertahankan kontinuitas penalaran.

Mengalihkan mode pemikiran dalam percakapan

Anda tidak dapat mengalihkan pemikiran di tengah giliran asisten, termasuk selama loop penggunaan alat. Seluruh giliran asisten harus beroperasi dalam mode pemikiran tunggal:

• Jika pemikiran diaktifkan, giliran asisten akhir harus dimulai dengan blok pemikiran.
• Jika pemikiran dinonaktifkan, giliran asisten akhir tidak boleh berisi blok pemikiran apa pun

Dari perspektif model, loop penggunaan alat adalah bagian dari giliran asisten. Giliran asisten tidak selesai sampai Claude menyelesaikan respons penuhnya, yang mungkin mencakup beberapa panggilan alat dan hasil.

Sebagai contoh, urutan ini semuanya bagian dari giliran asisten tunggal:

Meskipun ada beberapa pesan API, loop penggunaan alat secara konseptual adalah bagian dari satu respons asisten yang berkelanjutan.

Skenario kesalahan umum

Anda mungkin mengalami kesalahan ini:

Ini biasanya terjadi ketika:

1. Anda memiliki pemikiran dinonaktifkan selama urutan penggunaan alat
2. Anda ingin mengaktifkan pemikiran lagi
3. Pesan asisten terakhir Anda berisi blok penggunaan alat tetapi tidak ada blok pemikiran

Panduan praktis

✗ Tidak valid: Mengalihkan pemikiran segera setelah penggunaan alat

✓ Valid: Selesaikan giliran asisten terlebih dahulu

Praktik terbaik: Rencanakan strategi pemikiran Anda di awal setiap giliran daripada mencoba mengalihkan di tengah giliran.

Mempertahankan blok pemikiran

Selama penggunaan alat, Anda harus meneruskan blok thinking kembali ke API, dan Anda harus menyertakan blok yang lengkap dan tidak dimodifikasi kembali ke API. Ini sangat penting untuk mempertahankan aliran penalaran model dan integritas percakapan.

Ketika Claude memanggil alat, ia menghentikan konstruksi respons untuk menunggu informasi eksternal. Ketika hasil alat dikembalikan, Claude akan melanjutkan membangun respons yang ada. Ini memerlukan pemeliharaan blok pemikiran selama penggunaan alat, untuk beberapa alasan:

1. Kontinuitas penalaran: Blok pemikiran menangkap penalaran langkah demi langkah Claude yang menyebabkan permintaan alat. Ketika Anda memposting hasil alat, menyertakan pemikiran asli memastikan Claude dapat melanjutkan penalarannya dari tempat ia berhenti.

2. Pemeliharaan konteks: Meskipun hasil alat muncul sebagai pesan pengguna dalam struktur API, mereka adalah bagian dari aliran penalaran yang berkelanjutan. Mempertahankan blok pemikiran mempertahankan aliran konseptual ini di seluruh panggilan API beberapa. Untuk informasi lebih lanjut tentang manajemen konteks, lihat panduan kami tentang jendela konteks.

Penting: Ketika memberikan blok thinking, seluruh urutan blok thinking berturut-turut harus cocok dengan keluaran yang dihasilkan oleh model selama permintaan asli; Anda tidak dapat mengatur ulang atau memodifikasi urutan blok ini.

Pemikiran yang tersisip

Pemikiran yang diperluas dengan penggunaan alat dalam model Claude 4 mendukung pemikiran yang tersisip, yang memungkinkan Claude untuk berpikir di antara panggilan alat dan membuat penalaran yang lebih canggih setelah menerima hasil alat.

Dengan pemikiran yang tersisip, Claude dapat:

• Bernalar tentang hasil panggilan alat sebelum memutuskan apa yang harus dilakukan selanjutnya
• Menghubungkan beberapa panggilan alat dengan langkah-langkah penalaran di antaranya
• Membuat keputusan yang lebih bernuansa berdasarkan hasil perantara

Untuk mengaktifkan pemikiran yang tersisip, tambahkan header beta interleaved-thinking-2025-05-14 ke permintaan API Anda.

Berikut adalah beberapa pertimbangan penting untuk pemikiran yang tersisip:

• Dengan pemikiran yang tersisip, budget_tokens dapat melebihi parameter max_tokens, karena mewakili total anggaran di semua blok pemikiran dalam satu giliran asisten.
• Pemikiran yang tersisip hanya didukung untuk alat yang digunakan melalui Messages API.
• Pemikiran yang tersisip didukung untuk model Claude 4 saja, dengan header beta interleaved-thinking-2025-05-14.
• Panggilan langsung ke Claude API memungkinkan Anda melewatkan interleaved-thinking-2025-05-14 dalam permintaan ke model apa pun, tanpa efek.
• Di platform pihak ketiga (misalnya, Amazon Bedrock dan Vertex AI), jika Anda melewatkan interleaved-thinking-2025-05-14 ke model apa pun selain Claude Opus 4.5, Claude Opus 4.1, Opus 4, atau Sonnet 4, permintaan Anda akan gagal.

Pemikiran yang diperluas dengan penyimpanan prompt

Penyimpanan prompt dengan pemikiran memiliki beberapa pertimbangan penting:

Penghapusan konteks blok pemikiran

• Blok pemikiran dari giliran sebelumnya dihapus dari konteks, yang dapat mempengaruhi titik henti cache
• Saat melanjutkan percakapan dengan penggunaan alat, blok pemikiran disimpan dalam cache dan dihitung sebagai token input saat dibaca dari cache
• Ini menciptakan pertukaran: meskipun blok pemikiran tidak mengonsumsi ruang jendela konteks secara visual, mereka tetap dihitung terhadap penggunaan token input Anda saat disimpan dalam cache
• Jika pemikiran menjadi dinonaktifkan, permintaan akan gagal jika Anda melewatkan konten pemikiran dalam giliran penggunaan alat saat ini. Dalam konteks lain, konten pemikiran yang dilewatkan ke API hanya diabaikan

Pola invalidasi cache

• Perubahan pada parameter pemikiran (diaktifkan/dinonaktifkan atau alokasi anggaran) membatalkan titik henti cache pesan
• Pemikiran yang tersisip memperkuat invalidasi cache, karena blok pemikiran dapat terjadi di antara beberapa panggilan alat
• Prompt sistem dan alat tetap disimpan dalam cache meskipun ada perubahan parameter pemikiran atau penghapusan blok

Memahami perilaku penyimpanan blok pemikiran

Saat menggunakan pemikiran yang diperluas dengan penggunaan alat, blok pemikiran menunjukkan perilaku penyimpanan cache tertentu yang mempengaruhi penghitungan token:

Cara kerjanya:

1. Penyimpanan cache hanya terjadi ketika Anda membuat permintaan berikutnya yang mencakup hasil alat
2. Ketika permintaan berikutnya dibuat, riwayat percakapan sebelumnya (termasuk blok pemikiran) dapat disimpan dalam cache
3. Blok pemikiran yang disimpan dalam cache ini dihitung sebagai token input dalam metrik penggunaan Anda saat dibaca dari cache
4. Ketika blok pengguna hasil non-alat disertakan, semua blok pemikiran sebelumnya diabaikan dan dihapus dari konteks

Alur contoh terperinci:

Permintaan 1:

Respons 1:

Permintaan 2:

Respons 2:

Permintaan 2 menulis cache dari konten permintaan (bukan respons). Cache mencakup pesan pengguna asli, blok pemikiran pertama, blok penggunaan alat, dan hasil alat.

Permintaan 3:

Untuk Claude Opus 4.5 dan yang lebih baru, semua blok pemikiran sebelumnya disimpan secara default. Untuk model yang lebih lama, karena blok pengguna hasil non-alat disertakan, semua blok pemikiran sebelumnya diabaikan. Permintaan ini akan diproses sama dengan:

Poin kunci:

• Perilaku penyimpanan cache ini terjadi secara otomatis, bahkan tanpa penanda cache_control eksplisit
• Perilaku ini konsisten apakah menggunakan pemikiran reguler atau pemikiran yang tersisip

Token maksimal dan ukuran jendela konteks dengan pemikiran yang diperluas

Dalam model Claude yang lebih lama (sebelum Claude Sonnet 3.7), jika jumlah token prompt dan max_tokens melebihi jendela konteks model, sistem akan secara otomatis menyesuaikan max_tokens agar sesuai dengan batas konteks. Ini berarti Anda dapat mengatur nilai max_tokens yang besar dan sistem akan secara diam-diam menguranginya sesuai kebutuhan.

Dengan model Claude 3.7 dan 4, max_tokens (yang mencakup anggaran pemikiran Anda saat pemikiran diaktifkan) diberlakukan sebagai batas ketat. Sistem sekarang akan mengembalikan kesalahan validasi jika token prompt + max_tokens melebihi ukuran jendela konteks.

Jendela konteks dengan pemikiran yang diperluas

Saat menghitung penggunaan jendela konteks dengan pemikiran diaktifkan, ada beberapa pertimbangan yang perlu diperhatikan:

• Blok pemikiran dari giliran sebelumnya dihapus dan tidak dihitung terhadap jendela konteks Anda
• Pemikiran giliran saat ini dihitung terhadap batas max_tokens untuk giliran itu

Diagram di bawah menunjukkan manajemen token khusus saat pemikiran yang diperluas diaktifkan:

Jendela konteks yang efektif dihitung sebagai:

Kami merekomendasikan menggunakan API penghitungan token untuk mendapatkan penghitungan token yang akurat untuk kasus penggunaan spesifik Anda, terutama saat bekerja dengan percakapan multi-giliran yang mencakup pemikiran.

Jendela konteks dengan pemikiran yang diperluas dan penggunaan alat

Saat menggunakan pemikiran yang diperluas dengan penggunaan alat, blok pemikiran harus secara eksplisit dipertahankan dan dikembalikan dengan hasil alat.

Perhitungan jendela konteks yang efektif untuk pemikiran yang diperluas dengan penggunaan alat menjadi:

Diagram di bawah mengilustrasikan manajemen token untuk pemikiran yang diperluas dengan penggunaan alat:

Mengelola token dengan pemikiran yang diperluas

Mengingat perilaku jendela konteks dan max_tokens dengan model Claude 3.7 dan 4 pemikiran yang diperluas, Anda mungkin perlu:

• Lebih aktif memantau dan mengelola penggunaan token Anda
• Menyesuaikan nilai max_tokens saat panjang prompt Anda berubah
• Berpotensi menggunakan endpoint penghitungan token lebih sering
• Menyadari bahwa blok pemikiran sebelumnya tidak terakumulasi dalam jendela konteks Anda

Perubahan ini telah dilakukan untuk memberikan perilaku yang lebih dapat diprediksi dan transparan, terutama karena batas token maksimal telah meningkat secara signifikan.

Enkripsi pemikiran

Konten pemikiran penuh dienkripsi dan dikembalikan dalam bidang signature. Bidang ini digunakan untuk memverifikasi bahwa blok pemikiran dihasilkan oleh Claude saat dilewatkan kembali ke API.

Berikut adalah beberapa pertimbangan penting tentang enkripsi pemikiran:

• Saat streaming respons, tanda tangan ditambahkan melalui signature_delta di dalam acara content_block_delta tepat sebelum acara content_block_stop.
• Nilai signature secara signifikan lebih panjang dalam model Claude 4 dibandingkan dengan model sebelumnya.
• Bidang signature adalah bidang buram dan tidak boleh diinterpretasikan atau diurai - bidang ini hanya ada untuk tujuan verifikasi.
• Nilai signature kompatibel di seluruh platform (Claude API, Amazon Bedrock, dan Vertex AI). Nilai yang dihasilkan di satu platform akan kompatibel dengan platform lain.

Redaksi pemikiran

Kadang-kadang penalaran internal Claude akan ditandai oleh sistem keamanan kami. Ketika ini terjadi, kami mengenkripsi sebagian atau seluruh blok thinking dan mengembalikannya kepada Anda sebagai blok redacted_thinking. Blok redacted_thinking didekripsi ketika diteruskan kembali ke API, memungkinkan Claude untuk melanjutkan responsnya tanpa kehilangan konteks.

Saat membangun aplikasi yang menghadap pelanggan yang menggunakan pemikiran yang diperluas:

• Sadari bahwa blok pemikiran yang diredaksi berisi konten terenkripsi yang tidak dapat dibaca manusia
• Pertimbangkan untuk memberikan penjelasan sederhana seperti: "Beberapa penalaran internal Claude telah dienkripsi secara otomatis untuk alasan keamanan. Ini tidak mempengaruhi kualitas respons."
• Jika menampilkan blok pemikiran kepada pengguna, Anda dapat memfilter blok yang diredaksi sambil mempertahankan blok pemikiran normal
• Bersikap transparan bahwa menggunakan fitur pemikiran yang diperluas dapat sesekali menghasilkan beberapa penalaran yang dienkripsi
• Implementasikan penanganan kesalahan yang sesuai untuk mengelola pemikiran yang diredaksi dengan anggun tanpa merusak UI Anda

Berikut adalah contoh yang menunjukkan blok pemikiran normal dan yang diredaksi:

Saat melewatkan blok thinking dan redacted_thinking kembali ke API dalam percakapan multi-putaran, Anda harus menyertakan blok yang lengkap dan tidak dimodifikasi kembali ke API untuk giliran asisten terakhir. Ini sangat penting untuk mempertahankan aliran penalaran model. Kami menyarankan untuk selalu melewatkan semua blok pemikiran ke API. Untuk detail lebih lanjut, lihat bagian Preserving thinking blocks di atas.

Perbedaan pemikiran di seluruh versi model

Messages API menangani pemikiran secara berbeda di seluruh model Claude Sonnet 3.7 dan Claude 4, terutama dalam perilaku redaksi dan ringkasan.

Lihat tabel di bawah untuk perbandingan yang dipadatkan:

Preservasi blok pemikiran di Claude Opus 4.5

Claude Opus 4.5 memperkenalkan perilaku default baru: blok pemikiran dari giliran asisten sebelumnya dipertahankan dalam konteks model secara default. Ini berbeda dari model sebelumnya, yang menghapus blok pemikiran dari putaran sebelumnya.

Manfaat preservasi blok pemikiran:

• Optimasi cache: Saat menggunakan tool use, blok pemikiran yang dipertahankan memungkinkan cache hits karena diteruskan kembali dengan hasil tool dan di-cache secara inkremental di seluruh giliran asisten, menghasilkan penghematan token dalam alur kerja multi-langkah
• Tidak ada dampak kecerdasan: Mempertahankan blok pemikiran tidak memiliki efek negatif pada kinerja model

Pertimbangan penting:

• Penggunaan konteks: Percakapan panjang akan mengonsumsi lebih banyak ruang konteks karena blok pemikiran dipertahankan dalam konteks
• Perilaku otomatis: Ini adalah perilaku default untuk Claude Opus 4.5—tidak diperlukan perubahan kode atau header beta
• Kompatibilitas mundur: Untuk memanfaatkan fitur ini, terus lewatkan blok pemikiran yang lengkap dan tidak dimodifikasi kembali ke API seperti yang Anda lakukan untuk tool use

Harga

Untuk informasi harga lengkap termasuk tarif dasar, penulisan cache, cache hits, dan token output, lihat halaman harga.

Proses pemikiran dikenakan biaya untuk:

• Token yang digunakan selama pemikiran (token output)
• Blok pemikiran dari giliran asisten terakhir yang disertakan dalam permintaan berikutnya (token input)
• Token output teks standar

Saat menggunakan pemikiran yang diringkas:

• Token input: Token dalam permintaan asli Anda (mengecualikan token pemikiran dari putaran sebelumnya)
• Token output (ditagih): Token pemikiran asli yang dihasilkan Claude secara internal
• Token output (terlihat): Token pemikiran yang diringkas yang Anda lihat dalam respons
• Tidak ada biaya: Token yang digunakan untuk menghasilkan ringkasan

Praktik terbaik dan pertimbangan untuk pemikiran yang diperluas

Bekerja dengan anggaran pemikiran

• Optimasi anggaran: Anggaran minimum adalah 1.024 token. Kami menyarankan untuk memulai dengan minimum dan meningkatkan anggaran pemikiran secara bertahap untuk menemukan rentang optimal untuk kasus penggunaan Anda. Jumlah token yang lebih tinggi memungkinkan penalaran yang lebih komprehensif tetapi dengan hasil yang berkurang tergantung pada tugas. Meningkatkan anggaran dapat meningkatkan kualitas respons dengan mengorbankan latensi yang meningkat. Untuk tugas-tugas penting, uji pengaturan yang berbeda untuk menemukan keseimbangan optimal. Perhatikan bahwa anggaran pemikiran adalah target daripada batas ketat—penggunaan token aktual dapat bervariasi berdasarkan tugas.
• Titik awal: Mulai dengan anggaran pemikiran yang lebih besar (16k+ token) untuk tugas-tugas kompleks dan sesuaikan berdasarkan kebutuhan Anda.
• Anggaran besar: Untuk anggaran pemikiran di atas 32k, kami merekomendasikan menggunakan batch processing untuk menghindari masalah jaringan. Permintaan yang mendorong model untuk berpikir di atas 32k token menyebabkan permintaan yang berjalan lama yang mungkin mengalami batas waktu sistem dan batas koneksi terbuka.
• Pelacakan penggunaan token: Pantau penggunaan token pemikiran untuk mengoptimalkan biaya dan kinerja.

Pertimbangan kinerja

• Waktu respons: Bersiaplah untuk waktu respons yang berpotensi lebih lama karena pemrosesan tambahan yang diperlukan untuk proses penalaran. Faktor dalam bahwa menghasilkan blok pemikiran dapat meningkatkan waktu respons keseluruhan.
• Persyaratan streaming: Streaming diperlukan ketika max_tokens lebih besar dari 21.333. Saat streaming, bersiaplah untuk menangani blok konten pemikiran dan teks saat tiba.

Kompatibilitas fitur

• Pemikiran tidak kompatibel dengan modifikasi temperature atau top_k serta forced tool use.
• Ketika pemikiran diaktifkan, Anda dapat mengatur top_p ke nilai antara 1 dan 0,95.
• Anda tidak dapat mengisi respons sebelumnya ketika pemikiran diaktifkan.
• Perubahan pada anggaran pemikiran membatalkan awalan prompt yang di-cache yang mencakup pesan. Namun, prompt sistem yang di-cache dan definisi tool akan terus berfungsi ketika parameter pemikiran berubah.

Panduan penggunaan

• Pemilihan tugas: Gunakan pemikiran yang diperluas untuk tugas-tugas yang sangat kompleks yang mendapat manfaat dari penalaran langkah demi langkah seperti matematika, pengkodean, dan analisis.
• Penanganan konteks: Anda tidak perlu menghapus blok pemikiran sebelumnya sendiri. API Claude secara otomatis mengabaikan blok pemikiran dari putaran sebelumnya dan mereka tidak disertakan saat menghitung penggunaan konteks.
• Prompt engineering: Tinjau extended thinking prompting tips kami jika Anda ingin memaksimalkan kemampuan pemikiran Claude.

Langkah berikutnya