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.
CatatanHalaman 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.
Cache hit memerlukan awalan yang sepenuhnya identik, dan cache hanya digunakan kembali di antara permintaan dari pengguna yang sama. Untuk meningkatkan rasio cache hit, tempatkan konten yang tidak berubah di awal dan konten yang berubah pada setiap permintaan setelah titik henti.
Jika tidak menetapkan parameter cache apa pun, sistem menggunakan implicit cache untuk mengidentifikasi awalan umum secara otomatis, tetapi cache hit tidak dijamin. Untuk menggunakan kembali konten tertentu secara andal, aktifkan cache otomatis atau tetapkan titik henti 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
Tambahkan 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:
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": long_text,
"prompt_cache_breakpoint": {"mode": "explicit"}, # <-- Titik henti cache
},
{"type": "text", "text": "Ringkas dokumen ini."}, # Konten setelah titik henti tidak termasuk dalam cache ini
],
}
],
Penanda blok konten "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.
PeringatanGunakan hanya salah satu dari prompt_cache_breakpoint dan cache_control dalam satu permintaan.
Contoh berikut mengirim dua permintaan: permintaan pertama membuat cache, dan permintaan kedua mempertahankan awalan yang sama serta hanya mengubah pertanyaan untuk membaca cache.
import os
from openai import OpenAI
client = OpenAI(
# Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
# Berikut adalah URL untuk wilayah Tiongkok (Singapura). Saat memanggil, ganti WorkspaceId dengan ID ruang kerja yang sebenarnya. URL berbeda di setiap wilayah.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
# Dokumen panjang yang akan digunakan kembali. Awalan cache harus berisi setidaknya 1024 token.
long_text = "<Dokumen panjang tetap>" * 400
def ask(question):
completion = client.chat.completions.create(
model="qwen4-max",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": long_text, "prompt_cache_breakpoint": {"mode": "explicit"}}, # <-- Titik henti cache
{"type": "text", "text": question}, # Konten setelah titik henti dapat berubah setiap kali
],
}
],
extra_body={
"enable_thinking": False,
},
)
return completion.usage.prompt_tokens_details
ask("Ringkas dokumen ini.") # Permintaan pertama: buat cache
details = ask("Sebutkan tiga poin utama dari dokumen ini.") # Permintaan kedua: baca cache
print(f"Cache dibaca: {details.cached_tokens} token, cache dibuat: {details.cache_write_tokens} token")
Pada permintaan kedua, 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.
Kompatibel OpenAI Responses
Gunakan endpoint kompatibel OpenAI /compatible-mode/v1/responses. Tetapkan prompt_cache_options di tingkat teratas permintaan dan prompt_cache_breakpoint pada blok konten pesan di input.
| Kolom | Tipe | Deskripsi |
|---|---|---|
prompt_cache_options | object | Objek opsional untuk mengatur mode cache dan TTL. |
prompt_cache_options.mode | string | Opsional. Mendukung implicit dan explicit; default implicit. implicit mengaktifkan cache eksplisit dan menetapkan breakpoint otomatis di akhir pesan input terakhir; breakpoint manual dan otomatis berlaku bersama. explicit memerlukan breakpoint manual untuk membuat cache dan tidak berlaku jika tidak ada breakpoint. |
prompt_cache_options.ttl | string | Opsional. Mendukung 5m dan 1h; default 5m. |
input[].content[].prompt_cache_breakpoint | object | Objek opsional pada blok konten yang diprioritaskan di atas mode cache tingkat teratas. Mendukung blok bertipe input_text, input_image, dan input_file. |
prompt_cache_breakpoint.mode | string | Wajib saat menetapkan breakpoint. Hanya mendukung explicit. Kirim {"mode": "explicit"} secara eksplisit. |
Contoh berikut mengirim dua permintaan secara berurutan. Dokumen panjang sebelum breakpoint tetap sama; hanya pertanyaan setelahnya yang berubah. Permintaan pertama membuat cache dan permintaan kedua membacanya dalam TTL. Contoh menggunakan qwen4-max. Instal openai dan tetapkan DASHSCOPE_API_KEY serta DASHSCOPE_BASE_URL. Base URL Singapore adalah https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1; ganti {WorkspaceId} dengan ID ruang kerja Anda.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DASHSCOPE_API_KEY"],
base_url=os.environ["DASHSCOPE_BASE_URL"],
)
long_text = "Cache reference: Paris is the capital of France. " * 400
for question in ["Summarize this document.", "What is the capital of France?"]:
response = client.responses.create(
model="qwen4-max",
input=[{
"role": "user",
"content": [
{
"type": "input_text",
"text": long_text,
"prompt_cache_breakpoint": {"mode": "explicit"},
},
{"type": "input_text", "text": question},
],
}],
reasoning={"effort": "none"},
max_output_tokens=128,
extra_body={"prompt_cache_options": {"mode": "explicit", "ttl": "5m"}},
)
print(response.output_text)
print(response.usage.model_dump())
Untuk curl, tetapkan DASHSCOPE_RESPONSES_URL ke Base URL di atas ditambah /responses. Ganti placeholder dokumen dengan dokumen nyata yang berisi setidaknya 1.024 token.
curl "$DASHSCOPE_RESPONSES_URL" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen4-max",
"input": [{
"role": "user",
"content": [
{
"type": "input_text",
"text": "<DOCUMENT_WITH_AT_LEAST_1024_TOKENS>",
"prompt_cache_breakpoint": {"mode": "explicit"}
},
{"type": "input_text", "text": "Summarize this document."}
]
}],
"reasoning": {"effort": "none"},
"max_output_tokens": 128,
"prompt_cache_options": {"mode": "explicit", "ttl": "5m"}
}'
Anthropic compatible
Tambahkan cache_control dengan nilai {"type": "ephemeral"} ke blok konten yang akan di-cache di system atau messages:
system=[
{
"type": "text",
"text": long_text,
"cache_control": {"type": "ephemeral"}, # <-- Titik henti cache
}
],
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
Tetapkan prompt_cache_options di tingkat atas permintaan dan atur mode ke implicit. Dengan SDK Python OpenAI, teruskan melalui extra_body:
completion = client.chat.completions.create(
model="qwen4-max",
messages=[{"role": "user", "content": "Ringkas dokumen ini: " + long_text}],
extra_body={
"enable_thinking": False,
"prompt_cache_options": {"mode": "implicit"}, # <-- Mengaktifkan cache otomatis
},
)
Nilai 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 |
CatatanSaat 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 Responses
Tetapkan prompt_cache_options untuk mengaktifkan cache eksplisit. Default mode adalah implicit: sistem menetapkan breakpoint di akhir pesan input terakhir, dan breakpoint manual juga berlaku.
response = client.responses.create(
model="qwen4-max",
input=[{"role": "user", "content": [{"type": "input_text", "text": long_text}]}],
reasoning={"effort": "none"},
max_output_tokens=128,
extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "1h"}},
)
print(response.usage.model_dump())
Anthropic compatible
Tetapkan cache_control dengan nilai {"type": "ephemeral"} di tingkat atas permintaan. cache_control tingkat atas mengaktifkan cache otomatis dan dapat digunakan bersama dengan cache_control pada blok konten. Dengan SDK Python Anthropic, teruskan melalui extra_body:
message = client.messages.create(
model="qwen4-max",
max_tokens=1024,
messages=[{"role": "user", "content": "Ringkas dokumen ini: " + long_text}],
extra_body={"cache_control": {"type": "ephemeral"}}, # <-- Mengaktifkan cache otomatis di tingkat atas permintaan
)
Contoh lengkap berikut mengaktifkan cache otomatis dan mengirim permintaan dokumen panjang yang sama dua kali: permintaan pertama membuat cache, dan permintaan kedua membacanya.
Kompatibel OpenAI Chat Completions
import os
from openai import OpenAI
client = OpenAI(
# Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
# Berikut adalah URL untuk wilayah Tiongkok (Singapura). Saat memanggil, ganti WorkspaceId dengan ID ruang kerja yang sebenarnya. URL berbeda di setiap wilayah.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
# Dokumen panjang yang akan digunakan kembali. Awalan cache harus berisi setidaknya 1024 token.
long_text = "<Dokumen panjang tetap>" * 400
def ask():
completion = client.chat.completions.create(
model="qwen4-max",
messages=[{"role": "user", "content": "Ringkas dokumen ini: " + long_text}],
extra_body={
"enable_thinking": False,
"prompt_cache_options": {"mode": "implicit"}, # <-- Mengaktifkan cache otomatis
},
)
return completion.usage.prompt_tokens_details
for i in range(1, 3):
details = ask()
print(f"Permintaan {i}: cache dibaca {details.cached_tokens} token, cache dibuat {details.cache_write_tokens} token")
import OpenAI from "openai";
const client = new OpenAI({
// Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan: apiKey: "sk-xxx"
apiKey: process.env.DASHSCOPE_API_KEY,
// Berikut adalah URL untuk wilayah Tiongkok (Singapura). Saat memanggil, ganti WorkspaceId dengan ID ruang kerja yang sebenarnya. URL berbeda di setiap wilayah.
baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
});
// Dokumen panjang yang akan digunakan kembali. Awalan cache harus berisi setidaknya 1024 token.
const longText = "<Dokumen panjang tetap>".repeat(400);
async function ask() {
const completion = await client.chat.completions.create({
model: "qwen4-max",
messages: [{ role: "user", content: "Ringkas dokumen ini: " + longText }],
enable_thinking: false,
prompt_cache_options: { mode: "implicit" }, // <-- Mengaktifkan cache otomatis
});
return completion.usage.prompt_tokens_details;
}
async function main() {
for (let i = 1; i <= 2; i++) {
const details = await ask();
console.log(`Permintaan ${i}: cache dibaca ${details.cached_tokens} token, cache dibuat ${details.cache_write_tokens} token`);
}
}
main().catch(console.error);
# Berikut adalah URL untuk wilayah Tiongkok (Singapura). Saat memanggil, ganti WorkspaceId dengan ID ruang kerja yang sebenarnya. URL berbeda di setiap wilayah.
# Ganti <Dokumen panjang tetap> dengan dokumen panjang berisi setidaknya 1024 token, lalu kirim dua kali dalam periode validitas.
curl -X POST "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen4-max",
"messages": [
{"role": "user", "content": "Ringkas dokumen ini: <Dokumen panjang tetap>"}
],
"enable_thinking": false,
"prompt_cache_options": {"mode": "implicit"}
}'
Kompatibel OpenAI Responses
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DASHSCOPE_API_KEY"],
base_url=os.environ["DASHSCOPE_BASE_URL"],
)
long_text = "Cache reference: Paris is the capital of France. " * 400
for question in ["Summarize this document.", "Summarize this document."]:
response = client.responses.create(
model="qwen4-max",
input=[{
"role": "user",
"content": [
{
"type": "input_text",
"text": long_text,
},
{"type": "input_text", "text": question},
],
}],
reasoning={"effort": "none"},
max_output_tokens=128,
extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "5m"}},
)
print(response.output_text)
print(response.usage.model_dump())
Anthropic compatible
import os
import anthropic
client = anthropic.Anthropic(
# Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
# Berikut adalah URL untuk wilayah Tiongkok (Singapura). Saat memanggil, ganti WorkspaceId dengan ID ruang kerja yang sebenarnya. URL berbeda di setiap wilayah.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic",
)
# Dokumen panjang yang akan digunakan kembali. Awalan cache harus berisi setidaknya 1024 token.
long_text = "<Dokumen panjang tetap>" * 400
def ask():
message = client.messages.create(
model="qwen4-max",
max_tokens=1024,
messages=[{"role": "user", "content": "Ringkas dokumen ini: " + long_text}],
extra_body={"cache_control": {"type": "ephemeral"}}, # <-- Mengaktifkan cache otomatis di tingkat atas permintaan
)
return message.usage
for i in range(1, 3):
usage = ask()
print(f"Permintaan {i}: cache dibaca {usage.cache_read_input_tokens} token, cache dibuat {usage.cache_creation_input_tokens} token")
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
// Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan: apiKey: "sk-xxx"
apiKey: process.env.DASHSCOPE_API_KEY,
// Berikut adalah URL untuk wilayah Tiongkok (Singapura). Saat memanggil, ganti WorkspaceId dengan ID ruang kerja yang sebenarnya. URL berbeda di setiap wilayah.
baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic",
});
// Dokumen panjang yang akan digunakan kembali. Awalan cache harus berisi setidaknya 1024 token.
const longText = "<Dokumen panjang tetap>".repeat(400);
async function ask() {
const message = await client.messages.create({
model: "qwen4-max",
max_tokens: 1024,
messages: [{ role: "user", content: "Ringkas dokumen ini: " + longText }],
cache_control: { type: "ephemeral" }, // <-- Mengaktifkan cache otomatis di tingkat atas permintaan
});
return message.usage;
}
async function main() {
for (let i = 1; i <= 2; i++) {
const usage = await ask();
console.log(`Permintaan ${i}: cache dibaca ${usage.cache_read_input_tokens} token, cache dibuat ${usage.cache_creation_input_tokens} token`);
}
}
main().catch(console.error);
# Berikut adalah URL untuk wilayah Tiongkok (Singapura). Saat memanggil, ganti WorkspaceId dengan ID ruang kerja yang sebenarnya. URL berbeda di setiap wilayah.
# Ganti <Dokumen panjang tetap> dengan dokumen panjang berisi setidaknya 1024 token, lalu kirim dua kali dalam periode validitas.
curl -X POST "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic/v1/messages" \
-H "Content-Type: application/json" \
-H "x-api-key: $DASHSCOPE_API_KEY" \
-d '{
"model": "qwen4-max",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"messages": [
{"role": "user", "content": "Ringkas dokumen ini: <Dokumen panjang tetap>"}
]
}'
Outputnya serupa dengan berikut. Jumlah token sebenarnya bergantung pada panjang dokumen:
Permintaan 1: cache dibaca 0 token, cache dibuat 2048 token
Permintaan 2: cache dibaca 2048 token, cache dibuat 0 token
Input pada permintaan kedua identik dengan permintaan pertama, sehingga permintaan kedua membaca cache yang dibuat oleh permintaan pertama.
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
Tetapkan di prompt_cache_options.ttl pada tingkat atas permintaan. Nilai ini berlaku untuk semua titik henti dalam permintaan:
extra_body={
"prompt_cache_options": {
"mode": "implicit",
"ttl": "1h", # <-- TTL cache adalah 1 jam
},
},
Jika 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.
Kompatibel OpenAI Responses
Tetapkan TTL di prompt_cache_options.ttl tingkat teratas. Mendukung 5m dan 1h; default 5m.
extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "1h"}}
Anthropic compatible
Saat cache otomatis diaktifkan, tetapkan ttl di cache_control tingkat atas. Defaultnya adalah 5m:
extra_body={"cache_control": {"type": "ephemeral", "ttl": "1h"}}, # <-- TTL cache adalah 1 jam
Saat menggunakan titik henti cache, tetapkan ttl di cache_control pada blok konten:
system=[
{
"type": "text",
"text": long_text,
"cache_control": {"type": "ephemeral", "ttl": "1h"}, # <-- TTL cache adalah 1 jam
}
],
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.
Periode validitas dimulai saat pemrosesan cache untuk permintaan saat ini dimulai. Periode ini tidak ditambahkan ke waktu kedaluwarsa semula dan tidak direset saat respons berakhir. Waktu pembuatan respons diperhitungkan dalam periode validitas, dan waktu kedaluwarsa sebenarnya menyediakan sedikit waktu pemrosesan tambahan.
Contoh berikut menunjukkan permintaan berurutan untuk cache yang sama, yang dibuat dengan TTL 1h pada 12:00 dan semula kedaluwarsa pada 13:00:
| 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. |
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.
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
Berikut adalah usage saat cache dibuat untuk pertama kalinya (input teks saja, mode non-thinking):
{
"usage": {
"prompt_tokens": 2304,
"completion_tokens": 128,
"total_tokens": 2432,
"prompt_tokens_details": {
"text_tokens": 2304,
"cached_tokens": 0,
"cache_write_tokens": 2048,
"cache_creation_input_tokens": 2048,
"cache_type": "ephemeral",
"cache_creation": {
"ephemeral_5m_input_tokens": 2048,
"ephemeral_1h_input_tokens": 0
}
},
"completion_tokens_details": {}
}
}
| 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. |
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, 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.
Kompatibel OpenAI Responses
prompt_cache_options di tingkat teratas respons mengembalikan mode (implicit atau explicit) dan ttl (5m atau 1h). Penggunaan cache berada di usage.input_tokens_details. Untuk streaming, baca response.usage dari peristiwa response.completed; jangan gunakan stream_options.include_usage milik Chat Completions.
| Kolom | Deskripsi |
|---|---|
input_tokens | Seluruh token input, termasuk pembacaan cache, penulisan cache, dan input tanpa cache. |
input_tokens_details.cached_tokens | Token yang dibaca dari cache. |
input_tokens_details.cache_write_tokens | Token yang ditulis ke cache. |
input_tokens_details.cache_write_tokens_details.ttl_5m_tokens / ttl_1h_tokens | Token penulisan cache berdasarkan TTL. Jumlah kedua nilai sama dengan cache_write_tokens. |
Kolom berikut dikembalikan oleh endpoint pengujian Beijing saat pertama kali membuat cache 5m. Pada permintaan kedua dengan prefiks sama, cached_tokens bernilai 4488, sedangkan cache_write_tokens dan kedua kolom penulisan TTL bernilai 0.
{
"prompt_cache_options": {
"mode": "explicit",
"ttl": "5m"
},
"usage": {
"input_tokens": 4498,
"input_tokens_details": {
"cached_tokens": 0,
"cache_write_tokens": 4488,
"cache_write_tokens_details": {
"ttl_5m_tokens": 4488,
"ttl_1h_tokens": 0
}
},
"output_tokens": 32,
"output_tokens_details": {
"reasoning_tokens": 32
},
"total_tokens": 4530
}
}
Jangan campurkan kolom Responses input_tokens_details dengan Chat Completions prompt_tokens_details atau Anthropic cache_creation.
Anthropic compatible
Berikut adalah usage saat cache dibuat untuk pertama kalinya dengan cache otomatis diaktifkan dan TTL ditetapkan ke 1h:
{
"usage": {
"input_tokens": 8,
"output_tokens": 128,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 2048,
"cache_creation": {
"ephemeral_5m_input_tokens": 0,
"ephemeral_1h_input_tokens": 2048
},
"prompt_tokens_details": {
"cached_tokens": 0
}
}
}
| Kolom | Deskripsi |
|---|---|
input_tokens | Jumlah token input yang tidak dibaca dari cache dan tidak ditulis ke cache |
cache_read_input_tokens | Jumlah token yang dibaca dari cache |
cache_creation_input_tokens | Jumlah token yang ditulis ke cache |
cache_creation | Jumlah token yang ditulis ke cache menurut TTL |
prompt_tokens_details.cached_tokens | Jumlah token yang dibaca dari cache. Sama dengan cache_read_input_tokens. Jangan menjumlahkan keduanya. |
Jumlah total token input adalah jumlah dari input_tokens, cache_read_input_tokens, dan cache_creation_input_tokens, yaitu 8 + 0 + 2048 = 2056 pada contoh di atas.
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 |
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.
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.
T: Apakah permintaan 5m yang menghasilkan hit pada cache 1h memperpendek periode validitas cache?
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.