Topik ini menjelaskan cara menggunakan explicit cache beserta praktik terbaiknya. Dengan menambahkan penanda cache ke permintaan Anda, explicit cache menjamin hit cache yang deterministik untuk konten input yang identik, sehingga secara signifikan mengurangi biaya dan latensi.
Kapan menggunakan explicit cache
- Anda memerlukan hit cache yang dijamin: Explicit cache memberikan hit cache 100% deterministik terlepas dari penjadwalan sumber daya backend. Jika aplikasi Anda memerlukan penggunaan ulang konten yang stabil, explicit cache adalah pilihan tepat.
- Anda sering menggunakan kembali prompt yang sama: Saat prompt yang identik atau sangat konsisten dikirim berulang kali, explicit cache secara signifikan mengurangi biaya. Pembuatan cache hanya dikenai biaya tambahan 25% dibanding harga input standar, sedangkan setiap hit berikutnya menghemat 90%. Satu kali hit saja sudah cukup untuk mencapai titik impas.
- Anda mengelola konteks panjang dalam Agent produksi: Dalam aplikasi Agent, mekanisme umum seperti kompresi, ringkasan, dan pengingat sistem menyebabkan konteks terus berubah. Explicit cache memungkinkan Anda menyematkan dan menggunakan kembali segmen konteks kunci sehingga tetap di-cache meskipun konteks di sekitarnya berkembang.
Agent dan alat coding
Alat Agent dan coding berikut terhubung ke Model Studio melalui protokol Anthropic dan mendukung explicit cache secara native. Konfigurasikan sesuai dokumentasi masing-masing, dan alat tersebut akan secara otomatis memanfaatkan explicit cache untuk mengoptimalkan manajemen konteks.
Contoh di bawah menggunakan titik akhir Singapura. Untuk wilayah lain, ganti URL dasar dengan titik akhir regional yang sesuai.
Claude Code
Claude Code v2.x dan versi lebih baru secara otomatis menyertakan penanda cache_control dalam permintaan (system, env, dan pesan pengguna terbaru). Tidak diperlukan konfigurasi tambahan setelah terhubung ke titik akhir Model Studio yang kompatibel dengan Anthropic.
Buat atau edit ~/.claude/settings.json (Windows: C:\Users\<username>\.claude\settings.json) dengan pengaturan paket yang sesuai. Atau, hubungkan melalui variabel lingkungan:
export ANTHROPIC_BASE_URL="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic"
export ANTHROPIC_AUTH_TOKEN="${DASHSCOPE_API_KEY}"
export ANTHROPIC_MODEL="qwen3.7-max"
claude
Tetapkan titik akhir protokol Anthropic:
-
Token Plan (Team):
https://token-plan.ap-southeast-1.maas.aliyuncs.com/apps/anthropic -
Coding Plan:
https://coding-intl.dashscope.aliyuncs.com/apps/anthropic -
Pay-as-you-go:
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropicGanti
WorkspaceIddengan Workspace ID Anda yang sebenarnya.
Untuk detail selengkapnya, lihat Claude Code.
Opsi: Tingkatkan tingkat hit lintas sesiSecara default, Claude Code menyertakan informasi dinamis dalam prompt system (direktori saat ini, tanggal, status git), yang dapat mengurangi tingkat hit cache lintas sesi. Tambahkan flag berikut saat startup untuk memindahkan bagian dinamis ke pesan pengguna:
claude --exclude-dynamic-system-prompt-sections
Open Code
Saat OpenCode terhubung ke titik akhir Model Studio yang kompatibel dengan Anthropic melalui @ai-sdk/anthropic, alat ini secara otomatis menyisipkan cache_control pada pesan system dan pesan non-system terbaru.
npm install -g opencode-ai
KonfigurasiBuat file konfigurasi ~/.config/opencode/opencode.json (Windows: C:\Users\<username>\.config\opencode\opencode.json):
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"bailian": {
"npm": "@ai-sdk/anthropic",
"name": "Alibaba Cloud Model Studio",
"options": {
"baseURL": "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic/v1",
"apiKey": "{env:DASHSCOPE_API_KEY}"
},
"models": {
"qwen3.7-max": { "name": "qwen3.7-max" }
}
}
}
}
CatatanbaseURL harus diakhiri dengan /v1.
export DASHSCOPE_API_KEY=sk-xxxxx
opencode run -m "bailian/qwen3.7-max" "..."
URL dasar paket lainnya:
- Token Plan (Team):
https://token-plan.ap-southeast-1.maas.aliyuncs.com/apps/anthropic/v1 - Coding Plan:
https://coding-intl.dashscope.aliyuncs.com/apps/anthropic/v1
Untuk detail selengkapnya, lihat OpenCode.
OpenClaw
Saat menggunakan titik akhir yang kompatibel dengan Anthropic, OpenClaw secara otomatis menyisipkan penanda cache_control pada prompt system dan pesan pengguna terbaru. Tidak diperlukan konfigurasi tambahan — selama Base URL penyedia mengarah ke /apps/anthropic, explicit cache akan diaktifkan secara otomatis.
npm install -g openclaw
# or
curl -fsSL https://openclaw.ai/install.sh | bash
KonfigurasiEdit file konfigurasi ~/.openclaw/openclaw.json. Tetapkan "api" ke "anthropic-messages" dan atur URL dasar:
- Token Plan (Team):
https://token-plan.ap-southeast-1.maas.aliyuncs.com/apps/anthropic/v1 - Coding Plan:
https://coding-intl.dashscope.aliyuncs.com/apps/anthropic/v1 - Pay-as-you-go:
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic/v1
Untuk detail selengkapnya, lihat OpenClaw.
Opsi: Batas cache kustomJika prompt system Anda berisi konten templat yang stabil dan konten dinamis (timestamp, CWD, dll.), sisipkan <!-- OPENCLAW_CACHE_BOUNDARY --> di antara keduanya. OpenClaw akan menerapkan cache_control hanya pada awalan stabil sebelum batas tersebut, sehingga meningkatkan tingkat hit lintas sesi:
You are a Python engineer following these conventions:
- type hints required
- docstrings in Google format
<!-- OPENCLAW_CACHE_BOUNDARY -->
Current time: 2026-05-25 18:42
Working directory: /Users/<username>/project
Tanpa batas ini, OpenClaw menerapkan cache_control ke seluruh prompt system menggunakan strategi bawaannya, tetap memperoleh manfaat dari explicit cache.
Hermes
Konfigurasikan menggunakan perintah hermes config set. Tetapkan URL dasar:
- Token Plan (Team):
https://token-plan.ap-southeast-1.maas.aliyuncs.com/apps/anthropic/v1 - Coding Plan:
https://coding-intl.dashscope.aliyuncs.com/apps/anthropic/v1 - Pay-as-you-go:
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic/v1
Untuk detail selengkapnya, lihat Hermes Agent.
Integrasi API
Poin-poin penting
- Tambahkan
"cache_control": {"type": "ephemeral"}ke konten pesan yang ingin Anda cache. Seluruh konten dari awal array messages hingga penanda tersebut akan di-cache sebagai satu blok. - Konten yang di-cache harus memiliki minimal 1.024 token.
- Satu permintaan mendukung hingga 4 penanda cache.
- TTL cache adalah 5 menit, diperpanjang secara otomatis setiap kali ada hit.
- Definisi tool merupakan bagian dari prompt system untuk tujuan caching. Jika definisi tool berubah, cache tidak akan terhitung.
Mulai cepat
Contoh berikut menunjukkan alur kerja dasar: permintaan pertama membuat cache, dan permintaan kedua mengenai cache tersebut.
from openai import OpenAI
import os
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
# Ganti WorkspaceId dengan Workspace ID Anda yang sebenarnya.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
# Teks panjang untuk di-cache (harus melebihi 1024 token)
long_text_content = "<Your Long Text Here>" * 400
def get_completion(user_input):
messages = [
{
"role": "system",
"content": [
{
"type": "text",
"text": long_text_content,
# Penanda cache: konten dari awal messages hingga titik ini akan di-cache
"cache_control": {"type": "ephemeral"},
}
],
},
{"role": "user", "content": user_input},
]
completion = client.chat.completions.create(
model="qwen3.7-max",
messages=messages,
extra_body={"enable_thinking": False},
)
return completion
# Permintaan pertama: membuat cache
first = get_completion("Summarize the key points of this document")
print(f"Cache created: {first.usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"Cache hit: {first.usage.prompt_tokens_details.cached_tokens}")
# Permintaan kedua: konten system sama, pertanyaan berbeda — mengenai cache
second = get_completion("What precautions are mentioned in the document?")
print(f"Cache created: {second.usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"Cache hit: {second.usage.prompt_tokens_details.cached_tokens}")
import anthropic
import os
client = anthropic.Anthropic(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic",
)
# Teks panjang untuk di-cache (harus melebihi 1024 token)
long_text_content = "<Your Long Text Here>" * 400
def get_completion(user_input):
response = client.messages.create(
model="qwen3.7-max",
max_tokens=1024,
system=[
{
"type": "text",
"text": long_text_content,
# Penanda cache
"cache_control": {"type": "ephemeral"},
}
],
messages=[
{"role": "user", "content": user_input},
],
)
return response
# Permintaan pertama: membuat cache
first = get_completion("Summarize the key points of this document")
print(f"Cache created: {first.usage.cache_creation_input_tokens}")
print(f"Cache hit: {first.usage.cache_read_input_tokens}")
# Permintaan kedua: mengenai cache
second = get_completion("What precautions are mentioned in the document?")
print(f"Cache created: {second.usage.cache_creation_input_tokens}")
print(f"Cache hit: {second.usage.cache_read_input_tokens}")
Output yang diharapkan:
Cache created: 2005
Cache hit: 0
Cache created: 0
Cache hit: 2005
Permintaan pertama membuat blok cache. Permintaan kedua mengenai cache karena konten prompt system identik. Token yang di-cache hanya dikenai biaya 10% dari harga input standar.
Verifikasi status cache
Periksa bidang usage dalam respons untuk mengonfirmasi perilaku cache:
cache_creation_input_tokens: Jumlah token yang dibuat cache baru. Nilai lebih dari 0 berarti blok cache baru telah dibuat.cached_tokens(kompatibel OpenAI) ataucache_read_input_tokens(kompatibel Anthropic): Jumlah token yang mengenai cache. Nilai lebih dari 0 berarti cache berhasil dihitung.
Praktik terbaik berdasarkan skenario
Percakapan multi-putaran
Karakteristik:- Pengguna berinteraksi dengan model dalam beberapa putaran, setiap permintaan membawa riwayat percakapan lengkap
- Kasus penggunaan khas: layanan pelanggan, tanya jawab berbasis pengetahuan, asisten coding
Praktik terbaik: Tambahkan penanda cache_control ke pesan terakhir dalam setiap permintaan. Setiap putaran mengenai cache yang dibuat oleh putaran sebelumnya (riwayat percakapan), sekaligus membuat cache baru yang mencakup putaran saat ini untuk putaran berikutnya.
from openai import OpenAI
import os
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
# Ganti WorkspaceId dengan Workspace ID Anda yang sebenarnya.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
# Prompt system: manual produk (harus melebihi 1024 token)
product_manual = """You are the support assistant for "BaiLian SmartHome" smart home controller. Here is the complete product manual:
## Product Overview
BaiLian SmartHome is a whole-home smart controller supporting voice control, scene automation, and energy management...
## Installation Guide
1. Install at a central location with good WiFi coverage...
2. Connect the power adapter (5V/2A)...
## FAQ
Q: Cannot connect to WiFi? A: Make sure your router supports 2.4GHz...
""" * 80 # Ulangi hingga melebihi 1024 token
messages = [{"role": "system", "content": product_manual}]
def chat(user_input):
# Kunci: tambahkan cache_control ke pesan pengguna terakhir
messages.append({
"role": "user",
"content": [
{
"type": "text",
"text": user_input,
"cache_control": {"type": "ephemeral"},
}
],
})
completion = client.chat.completions.create(
model="qwen3.7-max",
messages=messages,
extra_body={"enable_thinking": False},
)
assistant_msg = completion.choices[0].message.content
messages.append({"role": "assistant", "content": assistant_msg})
usage = completion.usage
created = usage.prompt_tokens_details.cache_creation_input_tokens
cached = usage.prompt_tokens_details.cached_tokens
print(f" [Cache] Created: {created} tokens, Hit: {cached} tokens")
return assistant_msg
# Simulasikan percakapan multi-putaran
print("User: What voice assistants does BaiLian SmartHome support?")
print(f"Agent: {chat('What voice assistants does BaiLian SmartHome support?')[:80]}...\n")
print("User: What if I cannot connect to WiFi?")
print(f"Agent: {chat('What if I cannot connect to WiFi?')[:80]}...\n")
print("User: How many devices can it control simultaneously?")
print(f"Agent: {chat('How many devices can it control simultaneously?')[:80]}...")
Output yang diharapkan:
User: What voice assistants does BaiLian SmartHome support?
[Cache] Created: 8739 tokens, Hit: 0 tokens
Agent: BaiLian SmartHome supports Tmall Genie, XiaoAi, Siri, and other voice assistants...
User: What if I cannot connect to WiFi?
[Cache] Created: 151 tokens, Hit: 8739 tokens
Agent: For WiFi connectivity issues, try the following: 1. Confirm your router supports 2.4GHz...
User: How many devices can it control simultaneously?
[Cache] Created: 101 tokens, Hit: 8890 tokens
Agent: BaiLian SmartHome can control up to 256 smart devices simultaneously...
Mulai dari putaran kedua, setiap permintaan mengenai cache dari putaran sebelumnya (riwayat percakapan), sekaligus membuat cache baru yang mencakup putaran saat ini. Semakin banyak putaran dalam percakapan, semakin besar penghematannya.
Production Agent (beberapa penanda cache)
Karakteristik:- Percakapan multi-putaran panjang yang terdiri dari: prompt system + definisi keterampilan/tool + konteks proyek + pesan pengguna / pemanggilan tool
- Bagian-bagian berbeda berubah dengan frekuensi berbeda
- Kasus penggunaan khas: asisten coding AI (Claude Code, OpenClaw), sistem tanya jawab berbasis RAG
Praktik terbaik: Gunakan beberapa penanda cache (hingga 4) untuk menyematkan konten pada tingkat stabilitas berbeda. Setiap penanda harus berada pada pesan terpisah (peran berbeda) agar berfungsi sebagai breakpoint independen:
- Prompt system — satu penanda (jarang berubah)
- Definisi keterampilan/tool — satu penanda (mungkin berubah dalam kombinasi)
- Konteks proyek — satu penanda (mungkin berganti atau dikompresi)
- Pesan pengguna / pemanggilan tool — satu penanda (bertambah setiap putaran)
Contoh: Contoh ini mensimulasikan arsitektur Agent khas dengan 3 penanda cache yang menyematkan persona system dan tool (penanda 1), basis pengetahuan (penanda 2), dan riwayat percakapan (penanda 3). Perhatikan bahwa basis pengetahuan ditempatkan dalam pesan pengguna untuk memastikan memiliki breakpoint cache independen sendiri — beberapa pesan system digabung secara internal dan tidak dapat berfungsi sebagai breakpoint terpisah:
from openai import OpenAI
import os
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
# Ganti WorkspaceId dengan Workspace ID Anda yang sebenarnya.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
# Lapisan 1: Persona system (jarang berubah)
system_persona = """You are the senior AI support agent for "Model Studio Electronics". Your guidelines:
1. Answer questions based on the knowledge base
2. For information not in the knowledge base, say "Let me transfer you to a human agent"
3. Maintain a professional and friendly tone
4. If the user is unhappy, apologize first then resolve the issue
Below is your complete service specification and script guide:
""" + "Detailed service specification..." * 200 # Pastikan > 1024 token
# Lapisan 2: Definisi tool/keterampilan (kadang berubah, misal saat fitur baru diluncurkan)
tools_description = """### Available Tools
- search_product(query): Search product information
- check_inventory(sku, color): Check stock status
- create_ticket(type, description): Create a support ticket
- transfer_to_human(reason): Transfer to a human agent
### Tool Usage Rules
1. When user asks about product details, use search_product first
2. When user asks about stock/shipping, use check_inventory
3. When user requests return/exchange, use create_ticket
4. When a tool returns an error, apologize and transfer_to_human
""" + "Detailed tool usage examples..." * 150 # Pastikan > 1024 token
# Lapisan 3: Basis pengetahuan proyek (semi-stabil, berubah saat pengguna berganti produk)
knowledge_base_product_a = """### Current product: Model Studio Pro Max Wireless Earbuds
- SKU: BL-PM-2024
- Price: CNY 599
- Colors: Night Black / Nebula White / Ice Blue
- Battery: 8 hours (ANC on), 12 hours (ANC off)
- Water resistance: IPX5
- Warranty: 1 year, 7-day no-questions-asked return
- Stock: Night Black (in stock) / Nebula White (low) / Ice Blue (out of stock)
""" * 50 # Pastikan > 1024 token
def ask_agent(user_question, history=None):
if history is None:
history = []
messages = [
{
"role": "system",
"content": [
{
"type": "text",
"text": system_persona + "\n\n" + tools_description,
"cache_control": {"type": "ephemeral"}, # Penanda 1: persona system + tool
}
],
},
{
"role": "user",
"content": [
{
"type": "text",
"text": f"Here is the knowledge base for the current product:\n{knowledge_base_product_a}",
"cache_control": {"type": "ephemeral"}, # Penanda 2: basis pengetahuan
}
],
},
{"role": "assistant", "content": "Got it. I have the product details ready. How can I help you?"},
]
messages.extend(history)
# Tambahkan pertanyaan saat ini dengan penanda 3
messages.append({
"role": "user",
"content": [
{
"type": "text",
"text": user_question,
"cache_control": {"type": "ephemeral"}, # Penanda 3: riwayat percakapan
}
],
})
completion = client.chat.completions.create(
model="qwen3.7-max",
messages=messages,
extra_body={"enable_thinking": False},
)
usage = completion.usage
print(f" Created: {usage.prompt_tokens_details.cache_creation_input_tokens}, "
f"Hit: {usage.prompt_tokens_details.cached_tokens}")
return completion.choices[0].message.content
# Permintaan pertama
print("Q1: Is the Ice Blue color available?")
a1 = ask_agent("Is the Ice Blue color available?")
print(f"A1: {a1}\n")
# Permintaan kedua: produk sama (persona + tool + basis pengetahuan semua hit)
history = [
{"role": "user", "content": "Is the Ice Blue color available?"},
{"role": "assistant", "content": a1},
]
print("Q2: When will it be back in stock?")
a2 = ask_agent("When will it be back in stock?", history)
print(f"A2: {a2}")
Output yang diharapkan:
Q1: Is the Ice Blue color available?
Created: 7659, Hit: 0
A1: I'm sorry, but the Ice Blue color... is currently out of stock...
Q2: When will it be back in stock?
Created: 73, Hit: 7659
A2: I don't have access to specific restock dates... Let me transfer you to a human agent...
Pada Q2, awalan hingga penanda 2 (persona + tool + basis pengetahuan = 7.659 token) tidak berubah, sehingga menghasilkan hit cache penuh. Hanya konten baru setelah penanda 2 (riwayat percakapan + pertanyaan baru) yang memerlukan pemrosesan.
Cara kerja caching multi-penanda:- Pengguna terus bertanya tentang produk yang sama: Persona, tool, dan basis pengetahuan semuanya tidak berubah, mengenai cache pada penanda 2 (pencocokan awalan terpanjang) untuk penghematan maksimal.
- Lebih banyak putaran percakapan: Konten sebelumnya (persona + tool + basis pengetahuan + riwayat) mengenai cache putaran sebelumnya; hanya konten baru yang memerlukan cache baru.
CatatanAtur konten dari yang paling stabil ke yang paling tidak stabil: tempatkan konten yang paling jarang berubah di awal (misalnya, persona system) dan konten yang paling sering berubah di akhir (misalnya, percakapan saat ini) untuk memaksimalkan tingkat hit cache.
Pemrosesan batch (penyelesaian tugas)
Karakteristik:- Permintaan satu putaran, tidak memerlukan memori konteks
- Prompt system panjang tetap (instruksi tugas) + input pengguna variabel (data untuk diproses)
- Kasus penggunaan khas: klasifikasi teks, pengenalan maksud, ekstraksi data, moderasi konten
Praktik terbaik: Tambahkan penanda cache_control hanya pada prompt system. Semua permintaan berikutnya akan mengenai cache selama prompt system tetap tidak berubah.
from openai import OpenAI
import os
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
# Ganti WorkspaceId dengan Workspace ID Anda yang sebenarnya.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
# Prompt system panjang: aturan klasifikasi detail (harus melebihi 1024 token)
classification_prompt = """You are a product review classifier. Classify each review into one of these categories:
- Positive
- Negative
- Neutral
- Question
- Complaint
Output only the category name, nothing else.
Detailed classification rules and examples:
""" + """Rules:
1. Positive: Contains positive sentiment words (e.g., "great", "excellent", "recommend"), or expresses satisfaction.
2. Negative: Contains negative sentiment words (e.g., "terrible", "disappointed", "return"), or expresses dissatisfaction.
3. Neutral: No clear sentiment, merely states facts.
4. Question: Phrased as a question asking for product information.
5. Complaint: Expresses suggestions for improvement or lodges a complaint.
""" * 100
# Ulasan untuk diklasifikasikan (mensimulasikan pemrosesan batch)
reviews = [
"This product is amazing, great quality, highly recommended!",
"Shipping took a week and the packaging was damaged",
"Does this come in red? Does it run large or small?",
"You should add more size options, medium is too big for me",
"It's okay I guess, nothing special, does what it says",
]
print("=== Batch Classification (Explicit Cache) ===")
for i, review in enumerate(reviews):
completion = client.chat.completions.create(
model="qwen3.7-max",
messages=[
{
"role": "system",
"content": [
{
"type": "text",
"text": classification_prompt,
"cache_control": {"type": "ephemeral"}, # Cache aturan klasifikasi
}
],
},
{"role": "user", "content": review},
],
)
result = completion.choices[0].message.content
cached = completion.usage.prompt_tokens_details.cached_tokens
created = completion.usage.prompt_tokens_details.cache_creation_input_tokens
print(f"Review {i+1}: \"{review[:40]}...\" -> {result}")
print(f" Created: {created}, Hit: {cached}")
Output yang diharapkan:
Review 1: "This product is amazing, great quality, ..." -> Positive
Created: 10353, Hit: 0
Review 2: "Shipping took a week and the packaging w..." -> Negative
Created: 0, Hit: 10353
Review 3: "Does this come in red? Does it run large..." -> Question
Created: 0, Hit: 10353
Review 4: "You should add more size options, medium..." -> Complaint
Created: 0, Hit: 10353
Review 5: "It's okay I guess, nothing special, does..." -> Neutral
Created: 0, Hit: 10353
Setelah permintaan pertama membuat cache, semua permintaan berikutnya mengenai cache tersebut. Saat memproses 1.000 item, 999 permintaan mengalami pengurangan biaya token input sebesar 90%.
Pemanggilan Fungsi dengan definisi tool yang di-cache
Karakteristik:- Menggunakan Pemanggilan Fungsi dengan daftar panjang definisi tool
- Definisi tool tetap tidak berubah di berbagai permintaan
Praktik terbaik: Konten parameter tools merupakan bagian dari prompt system untuk caching. Pastikan definisi tool benar-benar identik di berbagai permintaan (urutan sama, urutan field sama, struktur sama), dan tambahkan penanda cache_control ke konten pesan.
from openai import OpenAI
import os
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
# Ganti WorkspaceId dengan Workspace ID Anda yang sebenarnya.
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
# Teks panjang untuk memenuhi minimum 1024 token
long_text_content = "<Your Code Here>" * 400
# Definisi tool: harus benar-benar identik di berbagai permintaan
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a given city",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
},
"required": ["city"]
}
}
},
{
"type": "function",
"function": {
"name": "search_flights",
"description": "Search flights between two cities",
"parameters": {
"type": "object",
"properties": {
"origin": {"type": "string", "description": "Departure city"},
"destination": {"type": "string", "description": "Destination city"},
"date": {"type": "string", "description": "Departure date in YYYY-MM-DD format"}
},
"required": ["origin", "destination", "date"]
}
}
}
]
def ask(user_input):
messages = [
{
"role": "system",
"content": [
{
"type": "text",
"text": long_text_content,
# cache_control hanya dapat ditambahkan ke konten pesan, bukan ke tool
"cache_control": {"type": "ephemeral"},
}
],
},
{"role": "user", "content": user_input},
]
completion = client.chat.completions.create(
model="qwen3.7-max",
messages=messages,
tools=tools,
extra_body={"enable_thinking": False},
)
usage = completion.usage
print(f" Created: {usage.prompt_tokens_details.cache_creation_input_tokens}, "
f"Hit: {usage.prompt_tokens_details.cached_tokens}")
tool_calls = completion.choices[0].message.tool_calls
if tool_calls:
print(f" Tools called: {[t.function.name for t in tool_calls]}")
return completion
# Permintaan pertama: membuat cache (termasuk definisi tool)
print("Q1: What's the weather in Beijing today?")
ask("What's the weather in Beijing today?")
# Permintaan kedua: mengenai cache
print("\nQ2: Find flights from Shanghai to Beijing tomorrow")
ask("Find flights from Shanghai to Beijing tomorrow")
Output yang diharapkan:
Q1: What's the weather in Beijing today?
Created: 1995, Hit: 0
Tools called: ['get_weather']
Q2: Find flights from Shanghai to Beijing tomorrow
Created: 0, Hit: 1995
Tools called: ['search_flights']
PentingKunci untuk memaksimalkan hit cache Pemanggilan Fungsi:
- Urutan tool konsisten: Pertahankan urutan tool yang sama dalam array tools.
- Urutan field konsisten: Pertahankan urutan field JSON yang sama dalam setiap definisi tool.
- Struktur konsisten: Jangan menambah, menghapus, atau mengubah urutan field antar permintaan, bahkan jika field tersebut opsional atau kosong.
Catatan penting
- Persyaratan format konten: Saat menambahkan
cache_control, bidang konten harus dalam bentuk array. Konten berbentuk string tidak mendukung penanda cache. - Granularitas penanda cache: Model Qwen3.5 dan versi lebih baru hanya mendukung breakpoint cache tingkat pesan. Menempatkan beberapa penanda
cache_controldalam array konten satu pesan tidak membuat breakpoint terpisah — sistem hanya menyimpan cache pada posisi penanda terakhir dalam pesan tersebut dan tidak dapat melakukan pencocokan potongan pada blok konten antara. Selain itu, beberapa pesan system digabung secara internal menjadi satu segmen dan tidak dapat berfungsi sebagai breakpoint terpisah. Untuk membuat beberapa breakpoint independen, sebarkan penandacache_controldi pesan dengan peran berbeda (misalnya, satu di system, satu di user). Model sebelum Qwen3.5 mendukung breakpoint tingkat konten (dalam pesan). - Saling eksklusif dengan cache implisit: Satu permintaan hanya dapat menggunakan satu mode caching. Jika permintaan berisi penanda
cache_control, explicit cache digunakan; jika tidak, sistem secara otomatis menggunakan cache implisit.
Model yang didukung
Untuk daftar model yang mendukung explicit cache, lihat Context cache.