Explicit cache khusus untuk model seri Qwen4. Gunakan cache otomatis atau titik henti cache untuk menentukan awalan input yang akan digunakan kembali, lalu tetapkan masa berlaku cache 5 menit atau 1 jam untuk mengurangi komputasi berulang, latensi, dan biaya input.
Dalam skenario seperti percakapan multi-putaran, tanya jawab dokumen panjang, dan agent, permintaan yang berurutan sering kali memiliki banyak konten awal yang sama, misalnya prompt sistem, deskripsi alat, atau dokumen referensi. Dengan explicit cache (Qwen4), permintaan berikutnya dalam periode validitas dapat membaca konten tersebut langsung dari cache tanpa menghitung ulang, sehingga latensi respons dan biaya input berkurang.
Explicit cache menggunakan titik henti cache untuk menentukan awalan konten yang akan digunakan kembali, dan cache hit bersifat deterministik: selama awalannya identik dan masih dalam periode validitas, permintaan berikutnya dapat membaca cache. Implicit cache, yang mengidentifikasi awalan umum secara otomatis, tidak menjamin cache hit.
Qwen4 menambahkan cache otomatis dan TTL cache di atas penggunaan dasar. Untuk detailnya, lihat Penggunaan lanjutan.
Cache dibuat dan dibaca per titik henti. Pada cache otomatis, sistem menempatkan titik henti di akhir input. Pada titik henti cache, Anda menandainya pada blok konten. Awalan cache untuk setiap titik henti adalah seluruh input dari awal permintaan hingga akhir blok konten yang berisi titik henti tersebut.
Saat menerima permintaan, sistem menggunakan setiap titik henti sebagai titik akhir, menelusuri mundur hingga 20 blok konten, dan memilih awalan identik terpanjang yang sudah di-cache:
Tetapkan titik henti cache pada blok konten yang ingin digunakan kembali. Sistem menggunakan akhir blok konten tersebut sebagai titik henti dan memperlakukan seluruh input dari awal permintaan hingga titik itu sebagai awalan cache: permintaan pertama membuat cache, dan permintaan berikutnya dengan awalan yang sama dalam periode validitas akan membacanya. Awalan cache harus berisi setidaknya 1.024 token.
Jika prompt terdiri dari beberapa bagian yang berubah dengan frekuensi berbeda, Anda dapat menetapkan titik henti untuk setiap bagian. Misalnya, prompt layanan pelanggan biasanya mencakup persona sistem (jarang berubah), hasil pengambilan basis pengetahuan (berubah sesuai topik pertanyaan), dan riwayat percakapan (terus bertambah). Jika Anda menetapkan titik henti di akhir setiap bagian, persona sistem tetap dapat menghasilkan cache hit meskipun konten basis pengetahuan berubah.
Setiap permintaan menyimpan paling banyak 4 titik henti terakhir yang valid. Titik henti tambahan tidak berlaku. Saat cache otomatis diaktifkan, titik henti otomatis menggunakan salah satu dari 4 slot tersebut.
Sistem hanya membuat atau memperpanjang titik henti dalam permintaan saat ini. Setelah titik henti berpindah, periode validitas titik henti sebelumnya tidak diperpanjang, meskipun cache-nya dibaca.
Misalnya, dengan TTL yang sama, titik henti pada permintaan sebelumnya berada di token 2.048, dan permintaan saat ini memindahkan titik henti ke token 3.072 tanpa mempertahankan titik henti sebelumnya. Jika titik henti sebelumnya berada dalam jangkauan penelusuran dan belum kedaluwarsa, permintaan saat ini membaca 2.048 token pertama dari cache dan menyimpan 1.024 token berikutnya ke cache. Sistem hanya membuat atau memperpanjang titik henti pada token 3.072. Cache pada token 2.048 tidak diperpanjang.
Qwen4 menambahkan dua kemampuan berikut di atas penggunaan dasar. Anda dapat menggabungkannya:
Dengan cache otomatis, sistem menempatkan titik henti secara otomatis di akhir input setiap permintaan, sehingga Anda tidak perlu memindahkan titik henti saat percakapan bertambah. Titik henti otomatis tidak menyertakan akhiran templat yang digunakan untuk mulai menghasilkan respons. Cache otomatis dapat digunakan bersama dengan titik henti cache yang dijelaskan pada Penggunaan dasar. Jika sudah ada titik henti manual di akhir input, titik henti tidak ditempatkan dua kali.
Contoh lengkap berikut mengaktifkan cache otomatis dan mengirim permintaan dokumen panjang yang sama dua kali: permintaan pertama membuat cache, dan permintaan kedua membacanya.
Outputnya serupa dengan berikut. Jumlah token sebenarnya bergantung pada panjang dokumen:
Input pada permintaan kedua identik dengan permintaan pertama, sehingga permintaan kedua membaca cache yang dibuat oleh permintaan pertama.
Masa berlaku cache (TTL) dapat berupa
Untuk permintaan pertama, atau setelah cache kedaluwarsa, cache dibuat dengan TTL permintaan saat ini. Saat permintaan menghasilkan hit pada cache yang valid, perpanjangan dan penagihan mengikuti aturan berikut:
Contoh di atas mengasumsikan permintaan serial dengan awalan yang sama. Saat beberapa permintaan menulis ke cache yang sama secara bersamaan, permintaan tersebut dapat saling menimpa, dan waktu kedaluwarsa terakhir tidak dijamin dipertahankan.
Titik henti cache hanya memengaruhi cara token input ditagih. Token output ditagih dengan harga standar.
Jika awalan cache pada permintaan saat ini berisi cache valid yang sudah ada, bagian yang sudah ada ditagih sebagai pembacaan cache, dan hanya bagian baru yang ditagih sebagai penulisan cache. Untuk penagihan saat TTL ditingkatkan dari 5m ke 1h, lihat Aturan perpanjangan.
Ya. Tanpa parameter cache, implicit cache digunakan. Sistem mengidentifikasi awalan umum secara otomatis, tetapi cache hit tidak dijamin. Untuk menghasilkan cache hit secara andal, tetapkan titik henti cache atau aktifkan cache otomatis.
TTL hanya berlaku untuk explicit cache. Jika Anda hanya menetapkan
Tidak. Waktu kedaluwarsa baru adalah yang lebih lambat antara waktu kedaluwarsa semula dan waktu perpanjangan permintaan saat ini, dan cache mempertahankan tingkat 1h. Untuk detailnya, lihat Aturan perpanjangan.
Halaman ini menjelaskan versi Qwen4 dari explicit cache yang sudah ada: penggunaan titik henti pada blok konten tetap sama, dengan tambahan cache otomatis dan TTL cache. Hubungannya dengan dua mode cache di Context Cache:
- Explicit cache: gunakan titik henti cache untuk menentukan awalan input, dengan cache hit yang deterministik. Inilah yang dijelaskan di halaman ini.
- Implicit cache: saat tidak ada parameter cache yang ditetapkan, awalan umum diidentifikasi secara otomatis, dan cache hit tidak dijamin. Untuk detailnya, lihat Implicit cache.
- Penanda blok konten
cache_controlpada API Chat Completions yang kompatibel dengan OpenAI tetap didukung dan penggunaannya sama denganprompt_cache_breakpoint. Untuk detailnya, lihat Penggunaan dasar.
Cara kerja
Cache dibuat dan dibaca per titik henti. Pada cache otomatis, sistem menempatkan titik henti di akhir input. Pada titik henti cache, Anda menandainya pada blok konten. Awalan cache untuk setiap titik henti adalah seluruh input dari awal permintaan hingga akhir blok konten yang berisi titik henti tersebut.
Saat menerima permintaan, sistem menggunakan setiap titik henti sebagai titik akhir, menelusuri mundur hingga 20 blok konten, dan memilih awalan identik terpanjang yang sudah di-cache:
- Cache hit: awalan yang sudah di-cache dibaca dan diperpanjang berdasarkan TTL permintaan saat ini.
- Cache miss: konten dari awal permintaan hingga titik henti dibuat sebagai cache baru. Jika sebagian awalan sudah menghasilkan cache hit, hanya bagian baru yang di-cache.
Penggunaan dasar
Tetapkan titik henti cache pada blok konten yang ingin digunakan kembali. Sistem menggunakan akhir blok konten tersebut sebagai titik henti dan memperlakukan seluruh input dari awal permintaan hingga titik itu sebagai awalan cache: permintaan pertama membuat cache, dan permintaan berikutnya dengan awalan yang sama dalam periode validitas akan membacanya. Awalan cache harus berisi setidaknya 1.024 token.
- Kompatibel OpenAI Chat Completions
- Kompatibel OpenAI Responses
- Anthropic compatible
Tambahkan Penanda blok konten Pada permintaan kedua,
prompt_cache_breakpoint dengan nilai {"mode": "explicit"} ke blok konten yang akan di-cache di messages. content pada pesan yang memiliki titik henti harus berupa array:"cache_control": {"type": "ephemeral"} yang sudah ada tetap didukung dan penggunaannya sama dengan prompt_cache_breakpoint. Untuk pengguna yang sama, cache dengan awalan identik dapat digunakan kembali di antara kedua penanda tersebut. Untuk integrasi baru, kami merekomendasikan prompt_cache_breakpoint.Contoh berikut mengirim dua permintaan: permintaan pertama membuat cache, dan permintaan kedua mempertahankan awalan yang sama serta hanya mengubah pertanyaan untuk membaca cache.Python
cached_tokens adalah jumlah token yang dibaca dari cache, dan cache_write_tokens adalah jumlah token yang dibuat oleh permintaan ini. Jika awalan tidak berubah, cache_write_tokens bernilai 0. Angka-angka tersebut hanya ilustrasi, dan nilai sebenarnya bergantung pada panjang dokumen.Menggunakan beberapa titik henti
Jika prompt terdiri dari beberapa bagian yang berubah dengan frekuensi berbeda, Anda dapat menetapkan titik henti untuk setiap bagian. Misalnya, prompt layanan pelanggan biasanya mencakup persona sistem (jarang berubah), hasil pengambilan basis pengetahuan (berubah sesuai topik pertanyaan), dan riwayat percakapan (terus bertambah). Jika Anda menetapkan titik henti di akhir setiap bagian, persona sistem tetap dapat menghasilkan cache hit meskipun konten basis pengetahuan berubah.
Setiap permintaan menyimpan paling banyak 4 titik henti terakhir yang valid. Titik henti tambahan tidak berlaku. Saat cache otomatis diaktifkan, titik henti otomatis menggunakan salah satu dari 4 slot tersebut.
Perpanjangan saat titik henti berpindah
Sistem hanya membuat atau memperpanjang titik henti dalam permintaan saat ini. Setelah titik henti berpindah, periode validitas titik henti sebelumnya tidak diperpanjang, meskipun cache-nya dibaca.
Misalnya, dengan TTL yang sama, titik henti pada permintaan sebelumnya berada di token 2.048, dan permintaan saat ini memindahkan titik henti ke token 3.072 tanpa mempertahankan titik henti sebelumnya. Jika titik henti sebelumnya berada dalam jangkauan penelusuran dan belum kedaluwarsa, permintaan saat ini membaca 2.048 token pertama dari cache dan menyimpan 1.024 token berikutnya ke cache. Sistem hanya membuat atau memperpanjang titik henti pada token 3.072. Cache pada token 2.048 tidak diperpanjang.
Penggunaan lanjutan
Qwen4 menambahkan dua kemampuan berikut di atas penggunaan dasar. Anda dapat menggabungkannya:
- Cache otomatis: sistem menempatkan titik henti secara otomatis di akhir input, cocok untuk percakapan multi-putaran.
- TTL cache: pilih 5 menit atau 1 jam.
Cache otomatis
Dengan cache otomatis, sistem menempatkan titik henti secara otomatis di akhir input setiap permintaan, sehingga Anda tidak perlu memindahkan titik henti saat percakapan bertambah. Titik henti otomatis tidak menyertakan akhiran templat yang digunakan untuk mulai menghasilkan respons. Cache otomatis dapat digunakan bersama dengan titik henti cache yang dijelaskan pada Penggunaan dasar. Jika sudah ada titik henti manual di akhir input, titik henti tidak ditempatkan dua kali.
- Kompatibel OpenAI Chat Completions
- Kompatibel OpenAI Responses
- Anthropic compatible
Tetapkan Nilai
prompt_cache_options di tingkat atas permintaan dan atur mode ke implicit. Dengan SDK Python OpenAI, teruskan melalui extra_body:prompt_cache_options.mode dan perilaku yang sesuai adalah sebagai berikut:| Pengaturan | Titik henti otomatis | Perilaku cache |
|---|---|---|
mode bernilai implicit | Ditempatkan | Titik henti otomatis di akhir input dan titik henti manual sama-sama berlaku |
mode bernilai explicit, dengan titik henti manual | Tidak ditempatkan | Membuat atau membaca cache pada titik henti manual |
mode bernilai explicit, tanpa titik henti manual | Tidak ditempatkan | Menggunakan implicit cache |
prompt_cache_options dihilangkan, null, atau {}, atau hanya ttl yang ditetapkan | Tidak ditempatkan | Meng-cache pada titik henti manual jika ada; jika tidak, menggunakan implicit cache |
Saat
mode bernilai implicit, cache titik henti otomatis digunakan dan mengikuti aturan TTL serta penagihan di halaman ini. Ini berbeda dari implicit cache yang digunakan saat tidak ada parameter cache yang ditetapkan. Menetapkan mode ke explicit hanya berarti tidak ada titik henti otomatis yang ditempatkan. Ini tidak menonaktifkan implicit cache. mode hanya berlaku untuk permintaan saat ini.- Kompatibel OpenAI Chat Completions
- Kompatibel OpenAI Responses
- Anthropic compatible
Menetapkan TTL cache
Masa berlaku cache (TTL) dapat berupa 5m (5 menit) atau 1h (1 jam). Defaultnya adalah 5m. Saat cache menghasilkan hit dalam periode validitas, cache diperpanjang secara otomatis. Untuk detailnya, lihat Aturan perpanjangan.
- Kompatibel OpenAI Chat Completions
- Kompatibel OpenAI Responses
- Anthropic compatible
Tetapkan di Jika
prompt_cache_options.ttl pada tingkat atas permintaan. Nilai ini berlaku untuk semua titik henti dalam permintaan:prompt_cache_options.ttl tidak ditetapkan, ttl dari penanda cache_control terakhir dalam permintaan akan digunakan. Jika penanda tersebut tidak memiliki ttl, atau permintaan tidak memiliki penanda cache_control, TTL adalah 5m.TTL hanya berlaku untuk explicit cache. Saat menetapkan ttl, tetapkan juga titik henti cache atau aktifkan cache otomatis.Aturan perpanjangan
Untuk permintaan pertama, atau setelah cache kedaluwarsa, cache dibuat dengan TTL permintaan saat ini. Saat permintaan menghasilkan hit pada cache yang valid, perpanjangan dan penagihan mengikuti aturan berikut:
- Waktu kedaluwarsa yang lebih lambat dipertahankan, bersama dengan tingkat yang lebih tinggi. Waktu kedaluwarsa baru kira-kira adalah yang lebih lambat antara waktu kedaluwarsa semula dan waktu mulai pemrosesan cache untuk permintaan saat ini ditambah TTL saat ini. Misalnya, permintaan pada 12:03 yang menghasilkan hit pada cache 5m yang kedaluwarsa pada 12:05 memperpanjang kedaluwarsa menjadi sekitar 12:08. Sebagai contoh lain, saat permintaan 5m menghasilkan hit pada cache 1h yang valid, perpanjangan dihitung berdasarkan 5m, tetapi cache tetap mempertahankan tingkat 1h, dan permintaan 1h berikutnya dalam periode validitas tetap ditagih sebagai pembacaan cache.
- Saat meningkatkan dari 5m ke 1h, bagian yang ditingkatkan ditagih sebagai pembuatan cache 1h. Saat permintaan 1h menghasilkan hit pada cache 5m yang valid, bagian yang menghasilkan hit dibuat ulang dengan TTL 1h dan tidak lagi ditagih sebagai pembacaan. Jika sebagian awalan sudah memiliki cache 1h yang valid, bagian tersebut tetap ditagih sebagai pembacaan, dan hanya bagian yang tersisa serta awalan baru yang ditagih sebagai pembuatan. Dalam semua kasus lain (permintaan 5m menghasilkan hit pada cache 5m, permintaan 5m menghasilkan hit pada cache 1h, atau permintaan 1h menghasilkan hit pada cache 1h), bagian yang menghasilkan hit ditagih sebagai pembacaan.
| Permintaan | TTL permintaan ini | Kedaluwarsa sebelum permintaan | Kedaluwarsa setelah permintaan (perkiraan) | Penagihan dan tingkat |
|---|---|---|---|---|
| Dikirim pada 12:20 | 5m | 13:00 | 13:00 | Pembacaan cache. 12:25 lebih awal dari kedaluwarsa semula, sehingga kedaluwarsa tetap sama. Tidak dipersingkat maupun diperpanjang hingga 13:20. |
| Dikirim pada 12:58 | 5m | 13:00 | 13:03 | Pembacaan cache. Kedaluwarsa diperpanjang menjadi 5 menit setelah permintaan ini dimulai, dan cache tetap mempertahankan tingkat 1h. |
| Dikirim pada 13:01 | 1h | 13:03 | 14:01 | Pembacaan cache. Cache sudah berada pada tingkat 1h, sehingga tidak ada pembuatan akibat peningkatan. |
Melihat penggunaan cache
usage dalam respons mengembalikan jumlah token yang dibaca dari cache dan ditulis ke cache. Untuk output streaming dengan API Chat Completions yang kompatibel dengan OpenAI, tetapkan stream_options ke {"include_usage": true} dan baca penggunaan dari chunk terakhir yang berisi usage.
- Kompatibel OpenAI Chat Completions
- Kompatibel OpenAI Responses
- Anthropic compatible
Berikut adalah
Pada contoh di atas, input yang tidak menggunakan cache adalah 2304 − 0 − 2048 = 256 token. Semua kolom cache adalah jumlah token mentah dan tidak menyertakan pengali penagihan. Saat Anda mengirim permintaan dengan awalan yang sama lagi dalam periode validitas,
usage saat cache dibuat untuk pertama kalinya (input teks saja, mode non-thinking):| Kolom | Deskripsi |
|---|---|
prompt_tokens | Jumlah total token input, termasuk pembacaan cache, penulisan cache, dan input yang tidak menggunakan cache. Tidak dikurangi oleh cache hit. |
total_tokens | Jumlah prompt_tokens dan completion_tokens |
prompt_tokens_details.cached_tokens | Jumlah token yang dibaca dari cache |
prompt_tokens_details.cache_write_tokens | Jumlah token yang ditulis ke cache |
prompt_tokens_details.cache_creation_input_tokens | Jumlah token yang ditulis ke cache. Sama dengan cache_write_tokens. Jangan menjumlahkan keduanya. |
prompt_tokens_details.cache_type | Jenis explicit cache. Selalu ephemeral. |
prompt_tokens_details.cache_creation | Jumlah token yang ditulis ke cache menurut TTL. Jumlah ephemeral_5m_input_tokens dan ephemeral_1h_input_tokens sama dengan jumlah token yang ditulis ke cache. |
cached_tokens bernilai 2048, cache_write_tokens, cache_creation_input_tokens, dan kedua item dalam cache_creation bernilai 0, serta prompt_tokens tetap 2304.Detail input untuk gambar, audio, dan video dikembalikan berdasarkan input sebenarnya. Detail output seperti thinking dikembalikan berdasarkan model dan konfigurasi. Kolom yang tidak berlaku dihilangkan, bukan dikembalikan sebagai 0.Praktik terbaik
- Gunakan cache otomatis untuk percakapan multi-putaran. Titik henti otomatis bergerak maju saat percakapan bertambah, sehingga Anda tidak perlu menyesuaikan titik henti di setiap putaran.
- Tempatkan konten tetap di awal. Tempatkan konten yang tidak berubah, seperti prompt sistem, definisi alat, dan dokumen referensi, di awal input. Tempatkan konten yang berubah pada setiap permintaan, seperti stempel waktu dan pertanyaan pengguna, di akhir.
- Tempatkan titik henti pada blok konten terakhir yang identik di semua permintaan. Jangan menempatkan titik henti pada blok konten yang berubah pada setiap permintaan. Jika tidak, setiap permintaan akan membuat cache baru dan tidak pernah membacanya.
- Tambahkan ke riwayat, jangan menulis ulang. Memodifikasi, menghapus, atau mengubah urutan pesan sebelumnya atau definisi alat akan mencegah cache berikutnya menghasilkan hit.
- Gunakan beberapa titik henti untuk konten yang berubah dengan frekuensi berbeda. Misalnya, jika definisi alat jarang berubah tetapi dokumen referensi diperbarui setiap hari, tetapkan titik henti di akhir masing-masing.
- Tambahkan titik henti saat satu putaran menambahkan banyak blok konten. Setiap titik henti menelusuri mundur hingga 20 blok konten. Jika satu putaran menambahkan konten melebihi jangkauan ini, tambahkan titik henti di tengah.
- Pilih TTL berdasarkan interval penggunaan kembali. Gunakan
5mjika konten digunakan kembali dalam 5 menit, karena setiap hit memperpanjang cache. Gunakan1hjika interval penggunaan kembali antara 5 menit dan 1 jam. - Pantau cache hit dengan kolom penggunaan. Rasio cache hit sama dengan jumlah token yang dibaca dari cache dibagi jumlah total token input. Jika rasio cache hit rendah, periksa apakah posisi awalan dan titik henti stabil.
Penagihan
Titik henti cache hanya memengaruhi cara token input ditagih. Token output ditagih dengan harga standar.
| Jenis token input | Penagihan |
|---|---|
| Penulisan cache, TTL 5m | Sekitar 125% dari harga token input |
| Penulisan cache, TTL 1h | Sekitar 200% dari harga token input |
| Pembacaan cache | Qwen4-Max |
| Tidak dibaca dari cache dan tidak ditulis ke cache | Harga token input |
Batasan
- Hanya model seri Qwen4 yang didukung.
- Prefiks cache harus berisi setidaknya 1.024 token. Prefiks yang lebih pendek tidak membuat cache; permintaan tetap berhasil, dan detail penulisan cache berdasarkan TTL tidak dikembalikan.
- Setiap permintaan menyimpan paling banyak 4 titik henti terakhir yang valid. Saat cache otomatis diaktifkan, titik henti otomatis menggunakan salah satunya.
- Dengan setiap titik henti sebagai titik akhir, sistem menelusuri mundur hingga 20 blok konten. Jika cache yang akan di-hit berjarak lebih dari 20 blok konten dari titik henti, cache tersebut tidak dapat di-hit.
- TTL hanya dapat berupa
5matau1h.
FAQ
T: Dapatkah permintaan menghasilkan cache hit tanpa parameter cache apa pun?
Ya. Tanpa parameter cache, implicit cache digunakan. Sistem mengidentifikasi awalan umum secara otomatis, tetapi cache hit tidak dijamin. Untuk menghasilkan cache hit secara andal, tetapkan titik henti cache atau aktifkan cache otomatis.
T: Mengapa periode validitas cache tidak berubah saat saya hanya menetapkan TTL?
TTL hanya berlaku untuk explicit cache. Jika Anda hanya menetapkan prompt_cache_options.ttl di API Chat Completions yang kompatibel dengan OpenAI, permintaan menggunakan implicit cache. Tambahkan titik henti manual juga, atau tetapkan prompt_cache_options.mode ke implicit.