Alibaba Cloud Model Studio:Context Cache

Permintaan inferensi untuk model besar sering kali berisi input yang tumpang tindih, seperti dalam percakapan multi-putaran atau rangkaian pertanyaan tentang buku yang sama. Context Cache mengurangi komputasi berulang dengan menyimpan awalan umum dari permintaan tersebut di cache, sehingga meningkatkan kecepatan respons dan menurunkan biaya penggunaan tanpa memengaruhi kualitas respons.

Untuk mendukung berbagai skenario, Context Cache menyediakan dua mode. Pilih mode berdasarkan kebutuhan Anda terkait kenyamanan, determinisme, dan biaya:

• Explicit cache: Mode yang diaktifkan secara manual. Anda membuat cache untuk konten tertentu guna memastikan hit yang deterministik selama periode validitas 5 menit. Token yang digunakan untuk membuat cache biasanya dikenai biaya sebesar 125% dari harga standar token input, sedangkan hit cache berikutnya biasanya hanya dikenai biaya sebesar 10% dari harga tersebut. Untuk informasi harga spesifik, lihat Billing.
• Implicit cache: Mode otomatis ini tidak memerlukan konfigurasi tambahan dan tidak dapat dinonaktifkan, ideal untuk skenario yang mengutamakan kenyamanan. Sistem secara otomatis mengidentifikasi dan menyimpan awalan umum dari permintaan di cache, tetapi probabilitas hit tidak dijamin. Bagian input yang dilayani dari cache biasanya dikenai biaya sebesar 20% dari harga standar token input. Untuk informasi harga spesifik, lihat Billing.

Explicit cache

Berbeda dengan implicit cache, explicit cache memerlukan pembuatan eksplisit dan menimbulkan overhead, tetapi memberikan rasio hit cache yang lebih tinggi serta latensi akses yang lebih rendah.

Cara kerja

Tambahkan penanda "cache_control": {"type": "ephemeral"} ke array messages. Sistem kemudian mencari mundur dari setiap penanda cache_control dan memeriksa hingga 20 blok content sebelumnya untuk menemukan cache hit.

Satu permintaan mendukung hingga empat penanda cache.

• Cache miss

  Jika terjadi cache miss, sistem membuat blok cache baru dari konten antara awal array messages dan penanda cache_control. Blok cache baru memiliki periode validitas 5 menit.

  Sistem membuat cache setelah model menghasilkan respons. Tunggu hingga permintaan pembuatan selesai sebelum mencoba mengakses cache tersebut.

  Blok cache berisi minimal 1.024 token.

• Cache hit

  Jika terjadi cache hit, sistem memilih awalan yang paling panjang sesuai dan mengatur ulang periode validitas blok cache yang sesuai menjadi 5 menit.

Contoh berikut menunjukkan cara kerjanya:

1. Kirim permintaan pertama: Kirim pesan sistem berisi teks A (lebih dari 1.024 token), dan tambahkan penanda cache:

[{"role": "system", "content": [{"type": "text", "text": A, "cache_control": {"type": "ephemeral"}}]}]

Sistem membuat blok cache pertama, yang disebut blok cache A. 2. Kirim permintaan kedua: Kirim permintaan dengan struktur berikut:

[
    {"role": "system", "content": A},
    <Other messages>
    {"role": "user","content": [{"type": "text", "text": B, "cache_control": {"type": "ephemeral"}}]}
]

• Jika terdapat 20 atau kurang "Other messages," permintaan akan mengenai blok cache A dan mengatur ulang periode validitasnya menjadi 5 menit. Sistem juga membuat blok cache baru berdasarkan A, pesan lainnya, dan B.
• Jika terdapat lebih dari 20 "Other messages," permintaan tidak mengenai blok cache A. Sistem tetap membuat blok cache baru berdasarkan konteks lengkap (A, pesan lainnya, dan B).

Model yang didukung

Memulai cepat

Contoh berikut menunjukkan mekanisme pembuatan blok cache dan cache hit untuk protokol yang kompatibel dengan OpenAI, DashScope, dan Anthropic.

from openai import OpenAI
import os

client = OpenAI(
    # Jika variabel lingkungan tidak diatur, ganti baris berikut dengan: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Jika Anda menggunakan model di China (Beijing), ganti base_url dengan: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# Konten repositori kode tiruan. Panjang prompt yang dapat di-cache minimal adalah 1.024 token.
long_text_content = "<Your Code Here>" * 400

# Fungsi untuk membuat permintaan
def get_completion(user_input):
    messages = [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": long_text_content,
                    # Tempatkan penanda cache_control di sini. Ini membuat blok cache yang berisi semua konten dari awal array messages hingga titik ini.
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        # Pertanyaan pengguna berbeda untuk setiap permintaan.
        {
            "role": "user",
            "content": user_input,
        },
    ]
    completion = client.chat.completions.create(
        # Pilih model yang mendukung explicit cache.
        model="qwen3.8-max",
        messages=messages,
    )
    return completion

# Permintaan pertama
first_completion = get_completion("Apa isi kode ini?")
print(f"Token pembuatan cache permintaan pertama: {first_completion.usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"Token yang di-cache permintaan pertama: {first_completion.usage.prompt_tokens_details.cached_tokens}")
print("=" * 20)
# Permintaan kedua. Konten kode sama, tetapi pertanyaannya berbeda.
second_completion = get_completion("Bagaimana kode ini dapat dioptimalkan?")
print(f"Token pembuatan cache permintaan kedua: {second_completion.usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"Token yang di-cache permintaan kedua: {second_completion.usage.prompt_tokens_details.cached_tokens}")

import os
from dashscope import MultiModalConversation
# URL berikut untuk Singapura. Ganti {WorkspaceId} dengan ID ruang kerja Anda. URL bervariasi berdasarkan wilayah.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

# Konten repositori kode tiruan. Panjang prompt yang dapat di-cache minimal adalah 1.024 token.
long_text_content = "<Your Code Here>" * 400

# Fungsi untuk membuat permintaan
def get_completion(user_input):
    messages = [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": long_text_content,
                    # Tempatkan penanda cache_control di sini. Ini membuat blok cache yang berisi semua konten dari awal array messages hingga titik ini.
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        # Pertanyaan pengguna berbeda untuk setiap permintaan.
        {
            "role": "user",
            "content": [{"text": user_input}],
        },
    ]
    response = MultiModalConversation.call(
        # Jika variabel lingkungan tidak diatur, gunakan langsung Kunci API Model Studio Anda: api_key = "sk-xxx",
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        model="qwen3.8-max",
        messages=messages,
    )
    return response

# Permintaan pertama
first_completion = get_completion("Apa isi kode ini?")
print(f"Token pembuatan cache permintaan pertama: {first_completion.usage.prompt_tokens_details['cache_creation_input_tokens']}")
print(f"Token yang di-cache permintaan pertama: {first_completion.usage.prompt_tokens_details['cached_tokens']}")
print("=" * 20)
# Permintaan kedua. Konten kode sama, tetapi pertanyaannya berbeda.
second_completion = get_completion("Bagaimana kode ini dapat dioptimalkan?")
print(f"Token pembuatan cache permintaan kedua: {second_completion.usage.prompt_tokens_details['cache_creation_input_tokens']}")
print(f"Token yang di-cache permintaan kedua: {second_completion.usage.prompt_tokens_details['cached_tokens']}")

// Versi minimum SDK Java: 2.21.6
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.MessageContentText;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;

import java.util.Arrays;
import java.util.Collections;

public class Main {
    private static final String MODEL = "qwen3-coder-plus";
    // Konten repositori kode tiruan (diulang 400 kali untuk memastikan melebihi 1.024 token).
    private static final String LONG_TEXT_CONTENT = generateLongText(400);
    private static String generateLongText(int repeatCount) {
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < repeatCount; i++) {
            sb.append("<Your Code Here>");
        }
        return sb.toString();
    }
    private static GenerationResult getCompletion(String userQuestion)
            throws NoApiKeyException, ApiException, InputRequiredException {
        // URL berikut untuk Singapura. Ganti {WorkspaceId} dengan ID ruang kerja Anda. URL bervariasi berdasarkan wilayah.
        Generation gen = new Generation("http", "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1");

        // Bangun pesan sistem dengan kontrol cache.
        MessageContentText systemContent = MessageContentText.builder()
                .type("text")
                .text(LONG_TEXT_CONTENT)
                .cacheControl(MessageContentText.CacheControl.builder()
                        .type("ephemeral") // Atur jenis cache.
                        .build())
                .build();

        Message systemMsg = Message.builder()
                .role(Role.SYSTEM.getValue())
                .contents(Collections.singletonList(systemContent))
                .build();
        Message userMsg = Message.builder()
                .role(Role.USER.getValue())
                .content(userQuestion)
                .build();

        // Bangun parameter permintaan.
        GenerationParam param = GenerationParam.builder()
                .model(MODEL)
                .messages(Arrays.asList(systemMsg, userMsg))
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                .build();
        return gen.call(param);
    }

    private static void printCacheInfo(GenerationResult result, String requestLabel) {
        System.out.printf("%s token pembuatan cache: %d%n", requestLabel, result.getUsage().getPromptTokensDetails().getCacheCreationInputTokens());
        System.out.printf("%s token yang di-cache: %d%n", requestLabel, result.getUsage().getPromptTokensDetails().getCachedTokens());
    }

    public static void main(String[] args) {
        try {
            // Permintaan pertama
            GenerationResult firstResult = getCompletion("Apa isi kode ini?");
            printCacheInfo(firstResult, "Permintaan pertama");
            System.out.println(new String(new char[20]).replace('\0', '='));            // Permintaan kedua
            GenerationResult secondResult = getCompletion("Bagaimana kode ini dapat dioptimalkan?");
            printCacheInfo(secondResult, "Permintaan kedua");
        } catch (NoApiKeyException | ApiException | InputRequiredException e) {
            System.err.println("Panggilan API gagal: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

import anthropic
import os

api_key = os.getenv("DASHSCOPE_API_KEY")
client = anthropic.Anthropic(
    # Jika variabel lingkungan tidak diatur, ganti baris berikut dengan: api_key="sk-xxx"
    api_key=api_key,
    # Jika Anda menggunakan model di China (Beijing), ganti base_url dengan: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/apps/anthropic
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic",
    default_headers={"Authorization": f"Bearer {api_key}"},
)

# Konten repositori kode tiruan. Panjang prompt yang dapat di-cache minimal adalah 1.024 token.
long_text_content = "<Your Code Here>" * 400

# Fungsi untuk membuat permintaan
def get_completion(user_input):
    response = client.messages.create(
        # Pilih model yang mendukung explicit cache.
        model="qwen3.8-max",
        max_tokens=1024,
        system=[
            {
                "type": "text",
                "text": long_text_content,
                # Tempatkan penanda cache_control di sini untuk membuat blok cache dari konten teks sistem. Penanda ini juga dapat ditempatkan di `messages`.
                "cache_control": {"type": "ephemeral"},
            }
        ],
        messages=[
            # Pertanyaan pengguna berbeda untuk setiap permintaan.
            {"role": "user", "content": user_input},
        ],
    )
    return response

# Permintaan pertama
first_completion = get_completion("Apa isi kode ini?")
print(f"Token pembuatan cache permintaan pertama: {first_completion.usage.cache_creation_input_tokens}")
print(f"Token yang di-cache permintaan pertama: {first_completion.usage.cache_read_input_tokens}")
print("=" * 20)
# Permintaan kedua. Konten kode sama, tetapi pertanyaannya berbeda.
second_completion = get_completion("Bagaimana kode ini dapat dioptimalkan?")
print(f"Token pembuatan cache permintaan kedua: {second_completion.usage.cache_creation_input_tokens}")
print(f"Token yang di-cache permintaan kedua: {second_completion.usage.cache_read_input_tokens}")

Menambahkan penanda cache_control mengaktifkan explicit cache untuk konten repositori kode tiruan. Untuk permintaan berikutnya yang menanyakan konten ini, sistem menggunakan kembali blok cache, sehingga menghilangkan komputasi ulang. Hal ini membuat permintaan yang mengenai cache lebih cepat dan lebih murah dibandingkan permintaan awal yang membuat cache.

Token pembuatan cache permintaan pertama: 1605
Token yang di-cache permintaan pertama: 0
====================
Token pembuatan cache permintaan kedua: 0
Token yang di-cache permintaan kedua: 1605

Kontrol detail halus dengan beberapa penanda cache

Dalam skenario kompleks, prompt sering terdiri dari beberapa bagian dengan frekuensi penggunaan ulang yang berbeda. Anda dapat menggunakan beberapa penanda cache untuk mencapai kontrol detail halus.

Sebagai contoh, prompt untuk agen layanan pelanggan cerdas biasanya mencakup:

• Persona sistem: Sangat stabil dan jarang berubah.
• Pengetahuan eksternal: Diperoleh dari basis pengetahuan atau melalui kueri tool dan mungkin tidak berubah selama satu percakapan.
• Riwayat percakapan: Berkembang secara dinamis.
• Pertanyaan saat ini: Berbeda untuk setiap permintaan.

Jika Anda menyimpan seluruh prompt sebagai satu unit, perubahan kecil apa pun, seperti pembaruan pada pengetahuan eksternal, dapat menyebabkan cache miss.

Anda dapat menambahkan hingga empat penanda cache dalam satu permintaan untuk membuat blok cache terpisah bagi bagian-bagian berbeda dari prompt. Hal ini meningkatkan rasio hit cache dan memungkinkan kontrol detail halus.

Billing

Explicit cache hanya memengaruhi cara token input ditagih. Aturannya adalah sebagai berikut:

• Pembuatan cache: Konten yang digunakan untuk membuat cache baru ditagih sebesar 125% dari harga standar token input. Jika konten untuk cache baru mencakup cache yang sudah ada sebagai awalan, hanya bagian tambahannya yang ditagih untuk pembuatan cache (yaitu, jumlah token cache baru dikurangi jumlah token cache yang sudah ada).

  Sebagai contoh, jika Anda memiliki cache yang sudah ada sebesar 1.200 token (Cache A) dan Anda menggunakan permintaan baru untuk menyimpan cache 1.500 token konten (Konten AB), 1.200 token pertama ditagih sebagai cache hit sebesar 10% dari harga standar. 300 token baru ditagih untuk pembuatan cache sebesar 125% dari harga standar.

  Parameter cache_creation_input_tokens menentukan jumlah token yang digunakan untuk pembuatan cache.

• Cache hit: Ditagih sebesar 10% dari harga standar token input.

  Parameter cached_tokens menentukan jumlah token yang di-cache.

• Token lainnya: Token yang bukan merupakan cache hit maupun digunakan untuk pembuatan cache ditagih dengan harga standar token input.

• Pengecualian: Harga cache hit eksplisit untuk qwen3.8-max, qwen3.8-flash, dan qwen3.8-2.4t-a95b bukan 10% dari harga standar token input. Untuk informasi harga spesifik, lihat konsol Model Studio. (Harga pembuatan cache tetap 125% dari harga standar.)

Konten yang dapat di-cache

Hanya jenis pesan berikut dalam array messages yang mendukung penambahan penanda cache:

• Pesan sistem

  CatatanUntuk pemanggilan fungsi, jika permintaan mencakup parameter tools, definisi tool dimasukkan dalam pesan sistem untuk perhitungan cache. Definisi tool tidak dapat di-cache secara independen. Penanda cache yang ditambahkan ke definisi tool diabaikan, karena hanya dapat ditambahkan ke konten pesan.

• Pesan pengguna

  Saat membuat cache dengan model qwen3-vl-plus, Anda dapat menempatkan penanda cache_control setelah konten multimodal atau teks. Posisinya tidak memengaruhi cara seluruh pesan pengguna di-cache.

• Pesan asisten

• Pesan tool (hasil eksekusi tool)

Sebagai contoh, untuk pesan sistem, Anda harus mengubah bidang content menjadi array dan menambahkan bidang cache_control:

{
  "role": "system",
  "content": [
    {
      "type": "text",
      "text": "<your specified prompt>",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

Struktur ini juga berlaku untuk jenis pesan lain dalam array messages.

Batasan cache

• Panjang prompt minimum yang dapat di-cache adalah 1.024 token.

• Cache menggunakan strategi pencocokan awalan mundur. Cache miss terjadi jika konten yang cocok dan pesan dengan penanda cache_control dipisahkan oleh lebih dari 20 blok konten.

• type hanya dapat diatur ke ephemeral, yang membuat cache dengan periode validitas 5 menit.

• Satu permintaan mendukung hingga empat penanda cache.

  Jika lebih dari empat penanda cache disediakan, hanya empat penanda terakhir yang berlaku.

Optimasi cache untuk Function Calling

Definisi tool diserialisasi menjadi string JSON untuk caching. Untuk mencegah invalidasi cache, definisi ini harus identik di semua permintaan. Perhatikan hal berikut:

• Urutan tool konsisten: Urutan tool dalam array tools harus konsisten di semua permintaan.
• Urutan bidang konsisten: Urutan bidang JSON dalam tool yang sama harus konsisten di semua permintaan.
• Struktur bidang konsisten: Jangan menghilangkan atau menambahkan bidang, meskipun kosong atau opsional.

Mengoptimalkan struktur pesan untuk pemanggilan tool paralel

Saat Anda menggunakan pemanggilan tool paralel, model mengembalikan beberapa tool_calls dalam satu respons. Jika Anda mengirim setiap hasil tool sebagai pesan tool terpisah, jumlah blok konten dalam array messages meningkat pesat. Ketika lebih dari 20 blok konten memisahkan penanda cache_control dari konten sebelumnya, jendela pencarian mundur tidak dapat mencapai blok-blok tersebut, menyebabkan cache miss.

Untuk mengatasi hal ini, gabungkan pesan tool berurutan dengan peran yang sama menjadi satu pesan tool dengan beberapa blok konten sebelum mengirim permintaan berikutnya. Hal ini mengurangi jumlah total blok konten dan menjaga konten yang ingin Anda cache tetap berada dalam jendela pencarian mundur 20 blok.

Sebelum optimasi (pesan tool terpisah — tingkat hit cache lebih rendah):

# Setelah model mengembalikan tool_calls paralel, kirim setiap hasil sebagai pesan terpisah
messages.append(assistant_message)  # pesan asisten yang berisi tool_calls paralel
# Setiap hasil tool adalah pesannya sendiri — meningkatkan jumlah blok konten sebanyak N
messages.append({"role": "tool", "tool_call_id": "call_1", "content": "result_1"})
messages.append({"role": "tool", "tool_call_id": "call_2", "content": "result_2"})

Setelah optimasi (pesan tool digabung — tingkat hit cache lebih tinggi):

# Setelah model mengembalikan tool_calls paralel, gabungkan semua hasil menjadi satu pesan
messages.append(assistant_message)  # pesan asisten yang berisi tool_calls paralel
# Gabungkan semua hasil tool menjadi satu pesan dengan beberapa blok konten
messages.append({
    "role": "tool",
    "tool_call_id": "call_1",
    "content": [
        {"type": "text", "text": "result_1"},
        {"type": "text", "text": "result_2", "tool_call_id": "call_2"},
    ],
})

Untuk meningkatkan lebih lanjut tingkat hit cache, tempatkan penanda cache_control pada posisi stabil dalam array messages (misalnya, pada pesan sistem atau konten lain yang jarang berubah). Satu permintaan mendukung hingga empat penanda cache.

Contoh penggunaan

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Ini adalah base_url untuk wilayah Singapura. Saat melakukan panggilan, ganti {WorkspaceId} dengan WorkspaceId aktual Anda. URL bervariasi berdasarkan wilayah.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# Konten repositori kode tiruan
long_text_content = "<Your Code Here>" * 400

# Fungsi untuk mengirim permintaan
def get_completion(user_input):
    messages = [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": long_text_content,
                    # Tempatkan penanda cache_control di sini untuk membuat cache dari awal prompt hingga akhir objek konten ini (konten repositori kode tiruan).
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        {
            "role": "user",
            "content": user_input,
        },
    ]
    completion = client.chat.completions.create(
        # Pilih model yang mendukung explicit cache
        model="qwen3.8-max",
        messages=messages,
    )
    return completion

# Permintaan pertama
first_completion = get_completion("Apa isi kode ini?")
created_cache_tokens = first_completion.usage.prompt_tokens_details.cache_creation_input_tokens
print(f"Permintaan pertama - Token pembuatan cache: {created_cache_tokens}")
hit_cached_tokens = first_completion.usage.prompt_tokens_details.cached_tokens
print(f"Permintaan pertama - Token hit cache: {hit_cached_tokens}")
print(f"Permintaan pertama - Token tidak di-cache: {first_completion.usage.prompt_tokens-created_cache_tokens-hit_cached_tokens}")
print("=" * 20)
# Permintaan kedua dengan konten kode yang sama tetapi pertanyaan berbeda
second_completion = get_completion("Apa saja kemungkinan optimasi untuk kode ini?")
created_cache_tokens = second_completion.usage.prompt_tokens_details.cache_creation_input_tokens
print(f"Permintaan kedua - Token pembuatan cache: {created_cache_tokens}")
hit_cached_tokens = second_completion.usage.prompt_tokens_details.cached_tokens
print(f"Permintaan kedua - Token hit cache: {hit_cached_tokens}")
print(f"Permintaan kedua - Token tidak di-cache: {second_completion.usage.prompt_tokens-created_cache_tokens-hit_cached_tokens}")

Permintaan pertama - Token pembuatan cache: 1605
Permintaan pertama - Token hit cache: 0
Permintaan pertama - Token tidak di-cache: 13
====================
Permintaan kedua - Token pembuatan cache: 0
Permintaan kedua - Token hit cache: 1605
Permintaan kedua - Token tidak di-cache: 15

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# Konten repositori kode tiruan, memastikan melebihi ambang batas minimum 1.024 token untuk explicit cache.
long_text_content = "<Your Code Here>" * 400

# Definisi tool: Pastikan identik untuk setiap permintaan (urutan tool, urutan bidang, dan struktur bidang).
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Dapatkan informasi cuaca saat ini untuk kota yang ditentukan.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "Nama kota, misalnya Beijing, Shanghai, atau New York."
                    },
                    "unit": {
                        "type": "string",
                        "description": "Satuan suhu, 'celsius' atau 'fahrenheit'. Default 'celsius'.",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["city"],
                "additionalProperties": False
            },
            "strict": True
        }
    },
    {
        "type": "function",
        "function": {
            "name": "get_current_time",
            "description": "Dapatkan tanggal dan waktu saat ini untuk zona waktu yang ditentukan.",
            "parameters": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "Nama zona waktu IANA, misalnya 'Asia/Shanghai' atau 'America/New_York'. Default 'Asia/Shanghai'."
                    }
                },
                "required": [],
                "additionalProperties": False
            },
            "strict": True
        }
    },
    {
        "type": "function",
        "function": {
            "name": "convert_currency",
            "description": "Konversi jumlah mata uang berdasarkan nilai tukar real-time.",
            "parameters": {
                "type": "object",
                "properties": {
                    "from_currency": {
                        "type": "string",
                        "description": "Kode ISO 4217 mata uang sumber, misalnya CNY, USD, atau EUR."
                    },
                    "to_currency": {
                        "type": "string",
                        "description": "Kode ISO 4217 mata uang tujuan."
                    },
                    "amount": {
                        "type": "number",
                        "description": "Jumlah yang akan dikonversi."
                    }
                },
                "required": ["from_currency", "to_currency", "amount"],
                "additionalProperties": False
            },
            "strict": True
        }
    }
]

def get_completion(user_input, messages=None):
    if messages is None:
        messages = [
            {
                "role": "system",
                "content": [
                    {
                        "type": "text",
                        "text": long_text_content,
                        # Tempatkan penanda cache_control di sini. Ini membuat blok cache dengan semua konten dari awal array messages hingga objek konten saat ini.
                        # Penanda cache_control harus berada pada 'content' pesan, bukan pada 'tools'.
                        "cache_control": {"type": "ephemeral"},
                    }
                ],
            }
        ]

    messages.append({"role": "user", "content": user_input})

    completion = client.chat.completions.create(
        # Pilih model yang mendukung explicit cache
        model="qwen3.7-plus",
        messages=messages,
        tools=tools,
        # Nonaktifkan mode berpikir
        extra_body={"enable_thinking": False},
    )
    return completion

# Permintaan pertama: Buat cache
print("=== Permintaan pertama (Buat cache) ===")
first_completion = get_completion("Bagaimana cuaca di Beijing sekarang?")
usage = first_completion.usage
print(f"Token Prompt: {usage.prompt_tokens}")
print(f"Token pembuatan cache: {usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"Token hit cache: {usage.prompt_tokens_details.cached_tokens}")
print(f"Tool yang dipilih model: {[t.function.name for t in first_completion.choices[0].message.tool_calls or []]}")
print()

# Permintaan kedua: Mengenai cache dengan pesan sistem yang sama tetapi pertanyaan berbeda
print("=== Permintaan kedua (Cache hit) ===")
messages = [
    {
        "role": "system",
        "content": [
            {
                "type": "text",
                "text": long_text_content,
                "cache_control": {"type": "ephemeral"},
            }
        ],
    }
]
second_completion = get_completion("Bagaimana cuaca di Shanghai sekarang?", messages=messages)
usage = second_completion.usage
print(f"Token Prompt: {usage.prompt_tokens}")
print(f"Token pembuatan cache: {usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"Token hit cache: {usage.prompt_tokens_details.cached_tokens}")
print(f"Tool yang dipilih model: {[t.function.name for t in second_completion.choices[0].message.tool_calls or []]}")

=== Permintaan pertama (Buat cache) ===
 Token Prompt: 2174
 Token pembuatan cache: 2156
 Token hit cache: 0
 Tool yang dipilih model: ['get_weather']

 === Permintaan kedua (Cache hit) ===
 Token Prompt: 2174
 Token pembuatan cache: 0
 Token hit cache: 2156
 Tool yang dipilih model: ['get_weather']

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Ini adalah base_url untuk wilayah Singapura. Saat melakukan panggilan, ganti {WorkspaceId} dengan WorkspaceId aktual Anda. URL bervariasi berdasarkan wilayah.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

system_prompt = "Anda adalah orang yang cerdas." * 400
messages = [{"role": "system", "content": system_prompt}]

def get_completion(messages):
    completion = client.chat.completions.create(
        model="qwen3.8-max",
        messages=messages,
    )
    return completion

while True:
    user_input = input("Pengguna: ")
    messages.append({"role": "user", "content": [{"type": "text", "text": user_input, "cache_control": {"type": "ephemeral"}}]})
    completion = get_completion(messages)
    print(f"[Respons AI] {completion.choices[0].message.content}")
    messages.append(completion.choices[0].message)
    created_cache_tokens = completion.usage.prompt_tokens_details.cache_creation_input_tokens
    hit_cached_tokens = completion.usage.prompt_tokens_details.cached_tokens
    uncached_tokens = completion.usage.prompt_tokens - created_cache_tokens - hit_cached_tokens
    print(f"[Info Cache] Token pembuatan cache: {created_cache_tokens}")
    print(f"[Info Cache] Token hit cache: {hit_cached_tokens}")
    print(f"[Info Cache] Token tidak di-cache: {uncached_tokens}")

Implicit cache

Model yang didukung

Cara kerja

Fitur implicit cache diaktifkan secara otomatis saat permintaan dikirim ke model yang didukung. Sistem bekerja sebagai berikut:

1. Pencarian: Setelah menerima permintaan, sistem menggunakan pencocokan awalan untuk memeriksa cache guna mencari awalan umum dari konten dalam array messages permintaan.

2. Keputusan:

   • Jika terjadi cache hit, sistem menggunakan hasil yang di-cache untuk sisa inferensi.
   • Jika terjadi cache miss, sistem memproses permintaan secara normal dan menyimpan awalan prompt di cache untuk permintaan mendatang.

Sistem secara berkala membersihkan data cache yang telah lama tidak digunakan. Probabilitas hit Context Cache tidak 100%. Cache miss dapat terjadi meskipun konteks permintaan identik. Sistem menentukan probabilitas hit spesifik.

Meningkatkan probabilitas cache hit

Cache hit implicit terjadi ketika awalan dari permintaan berbeda memiliki konten duplikat. Untuk meningkatkan probabilitas hit, tempatkan konten duplikat di awal prompt dan konten unik di akhir.

• Model teks: Sebagai contoh, asumsikan sistem telah menyimpan cache "ABCD". Permintaan untuk "ABE" mungkin mengenai bagian "AB", tetapi permintaan untuk "BCD" tidak akan mengenai.

• Model pemahaman visual:
  • Untuk mengajukan beberapa pertanyaan tentang gambar atau video yang sama, tempatkan gambar atau video sebelum teks.
  • Untuk mengajukan pertanyaan yang sama tentang gambar atau video berbeda, tempatkan teks sebelum gambar atau video.

Billing

Tidak ada biaya tambahan yang dikenakan untuk mengaktifkan mode implicit cache.

Saat permintaan mengenai cache, token input dari cache hit ditagih sebagai cached_token. Tingkat diskon untuk token ini bervariasi berdasarkan model. Token input yang tidak mengenai cache ditagih sebagai input_token standar. Token output ditagih dengan harga aslinya.

• Untuk model selain deepseek-v4-pro, qwen3.8-max, qwen3.8-flash, dan qwen3.8-2.4t-a95b: Harga satuan cached_token adalah 20% dari harga satuan input_token.

• deepseek-v4-pro: Harga satuan cached_token bukan 20% dari harga satuan input_token. Untuk informasi harga spesifik, lihat konsol Model Studio.

• qwen3.8-max, qwen3.8-flash, dan qwen3.8-2.4t-a95b: Harga satuan cached_token bukan 20% dari harga satuan input_token. Untuk informasi harga spesifik, lihat konsol Model Studio.

• GLM (diterapkan di Alibaba Cloud Model Studio): 25% untuk glm-5.2 dan glm-5.2-fast-preview, dan 20% untuk semua model seri GLM lainnya.

Contoh: Permintaan berisi 10.000 token input, dan 5.000 di antaranya menghasilkan cache hit. Biaya dihitung sebagai berikut:

• Token yang tidak mengenai cache (5.000): Ditagih 100% dari harga satuan.
• Token yang mengenai cache (5.000): Ditagih 20% dari harga satuan.

Total biaya input adalah 60% dari biaya dalam mode tanpa cache: (50% × 100%) + (50% × 20%) = 60%.

Anda dapat memperoleh jumlah token yang mengenai cache dari atribut cached_tokens dalam respons.

Panggilan yang dilakukan menggunakan metode OpenAI-compatible - Batch (input file) tidak memenuhi syarat untuk diskon cache.

Contoh cache hit

{
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "Saya adalah model bahasa skala besar yang dikembangkan oleh Alibaba Cloud. Nama saya Qwen."
            },
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null
        }
    ],
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 3019,
        "completion_tokens": 104,
        "total_tokens": 3123,
        "prompt_tokens_details": {
            "cached_tokens": 2048
        }
    },
    "created": 1735120033,
    "system_fingerprint": null,
    "model": "qwen-plus",
    "id": "chatcmpl-6ada9ed2-7f33-9de2-8bb0-78bd4035025a"
}

{
    "status_code": 200,
    "request_id": "f3acaa33-e248-97bb-96d5-cbeed34699e1",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": "Saya adalah model bahasa besar dari Alibaba Cloud. Nama saya Qwen. Saya dapat menghasilkan berbagai jenis teks, seperti artikel, cerita, dan puisi, serta dapat menyesuaikannya berdasarkan skenario dan kebutuhan yang berbeda. Selain itu, saya dapat menjawab berbagai pertanyaan dan memberikan bantuan serta solusi. Jika Anda memiliki pertanyaan atau membutuhkan bantuan, jangan ragu untuk bertanya, dan saya akan berusaha sebaik mungkin memberikan dukungan. Harap dicatat bahwa mengulang konten yang sama mungkin tidak menghasilkan respons yang lebih detail. Kami menyarankan untuk memberikan informasi yang lebih spesifik atau mengubah pertanyaan Anda agar saya dapat lebih memahami kebutuhan Anda."
                }
            }
        ]
    },
    "usage": {
        "input_tokens": 3019,
        "output_tokens": 101,
        "prompt_tokens_details": {
            "cached_tokens": 2048
        },
        "total_tokens": 3120
    }
}

{
    "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
    "type": "message",
    "role": "assistant",
    "content": [
        {
            "type": "text",
            "text": "Konten ini adalah teks placeholder yang diulang."
        }
    ],
    "model": "qwen3.7-max",
    "stop_reason": "end_turn",
    "usage": {
        "input_tokens": 82,
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 1536,
        "output_tokens": 14
    }
}

{
  "id": "chatcmpl-3f3bf7d0-b168-9637-a245-dd0f946c700f",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "Gambar ini menunjukkan adegan hangat antara seorang wanita dan seekor anjing yang berinteraksi di pantai. Wanita tersebut, mengenakan kemeja kotak-kotak, duduk di pasir dan tersenyum saat berinteraksi dengan anjing tersebut. Anjing tersebut adalah jenis besar berwarna terang yang mengenakan kalung warna-warni, dengan kaki depannya terangkat seolah-olah hendak bersalaman atau memberi high-five kepada wanita tersebut. Latar belakangnya adalah lautan dan langit yang luas, dengan sinar matahari yang bersinar dari sisi kanan bingkai, menambah suasana hangat dan tenang pada seluruh adegan.",
        "refusal": null,
        "role": "assistant",
        "audio": null,
        "function_call": null,
        "tool_calls": null
      }
    }
  ],
  "created": 1744956927,
  "model": "qwen-vl-max",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "completion_tokens": 93,
    "prompt_tokens": 1316,
    "total_tokens": 1409,
    "completion_tokens_details": null,
    "prompt_tokens_details": {
      "audio_tokens": null,
      "cached_tokens": 1152
    }
  }
}

{
  "status_code": 200,
  "request_id": "06a8f3bb-d871-9db4-857d-2c6eeac819bc",
  "code": "",
  "message": "",
  "output": {
    "text": null,
    "finish_reason": null,
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": [
            {
              "text": "Gambar ini menunjukkan adegan hangat antara seorang wanita dan seekor anjing yang berinteraksi di pantai. Wanita tersebut, mengenakan kemeja kotak-kotak, duduk di pasir dan tersenyum saat berinteraksi dengan anjing tersebut. Anjing tersebut adalah jenis besar yang mengenakan kalung warna-warni, dengan kaki depannya terangkat seolah-olah hendak bersalaman atau memberi high-five kepada wanita tersebut. Latar belakangnya adalah lautan dan langit yang luas, dengan sinar matahari yang bersinar dari sisi kanan bingkai, menambah suasana hangat dan tenang pada seluruh adegan."
            }
          ]
        }
      }
    ]
  },
  "usage": {
    "input_tokens": 1292,
    "output_tokens": 87,
    "input_tokens_details": {
      "text_tokens": 43,
      "image_tokens": 1249
    },
    "total_tokens": 1379,
    "output_tokens_details": {
      "text_tokens": 87
    },
    "image_tokens": 1249,
    "cached_tokens": 1152
  }
}

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Gambar ini menunjukkan adegan hangat antara seorang wanita dan seekor anjing yang berinteraksi di pantai."
    }
  ],
  "model": "qwen-vl-max",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 369,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 896,
    "output_tokens": 28
  }
}

Kasus penggunaan

Jika permintaan Anda memiliki awalan umum, context cache dapat secara signifikan meningkatkan kecepatan inferensi, menurunkan biaya inferensi, dan mengurangi latensi paket pertama. Fitur ini sangat berguna dalam kasus penggunaan berikut:

1. Menjawab pertanyaan teks panjang

   Gunakan pola ini saat Anda mengirim beberapa permintaan tentang teks panjang yang sama, seperti novel, buku teks, atau dokumen hukum.

   Pesan permintaan pertama

messages = [{"role": "system","content": "Anda adalah guru bahasa yang dapat membantu siswa dengan pemahaman membaca."},
          {"role": "user","content": "

messages = [{"role": "system","content": "Anda adalah guru seni bahasa. Anda dapat membantu siswa dengan pemahaman membaca."},
          {"role": "user","content": "<Konten artikel> Tolong analisis paragraf ketiga teks ini."}]

Meskipun pertanyaannya berbeda, semuanya didasarkan pada artikel yang sama. Prompt sistem dan konten artikel yang sama membentuk sejumlah besar informasi awalan berulang, yang memiliki probabilitas tinggi untuk cache hit. 2. Penyelesaian kode otomatis

Dalam skenario penyelesaian kode otomatis, model menggunakan kode di sekitarnya sebagai konteks untuk menghasilkan kode berikutnya. Saat Anda menulis, bagian awal file kode tetap sama. Context cache dapat menyimpan awalan ini untuk mempercepat penyelesaian kode. 3. Percakapan multi-putaran

Untuk percakapan multi-putaran, Anda menambahkan setiap putaran ke array messages. Hal ini memastikan bahwa setiap permintaan baru memiliki awalan umum dengan putaran sebelumnya, meningkatkan kemungkinan cache hit.

messages=[{"role": "system","content": "Anda adalah asisten yang membantu."},
          {"role": "user","content": "Siapa kamu?"}]

messages=[{"role": "system","content": "Anda adalah asisten yang membantu."},
          {"role": "user","content": "Siapa kamu?"},
          {"role": "assistant","content": "Saya Qwen, dikembangkan oleh Alibaba Cloud."},
          {"role": "user","content": "Apa yang bisa kamu lakukan?"}]

Saat percakapan berkembang, manfaat caching untuk kecepatan dan biaya inferensi menjadi lebih signifikan. 4. Bermain peran atau pembelajaran few-shot

Dalam skenario peran bermain atau pembelajaran few-shot, Anda sering menyertakan instruksi panjang dalam prompt untuk memandu format output model. Hal ini menciptakan awalan besar yang dibagikan di beberapa permintaan.

Sebagai contoh, saat menginstruksikan model untuk bertindak sebagai ahli pemasaran, prompt sistem berisi teks panjang. Berikut adalah dua contoh permintaan:

system_prompt = """Anda adalah ahli pemasaran berpengalaman. Berikan saran pemasaran terperinci untuk produk berbeda dalam format berikut:

1. Target audiens: xxx

2. Poin penjualan utama: xxx

3. Saluran pemasaran: xxx
...
12. Strategi pengembangan jangka panjang: xxx

Pastikan saran Anda spesifik, dapat ditindaklanjuti, dan sangat relevan dengan fitur produk."""

# Pesan pengguna untuk permintaan pertama menanyakan tentang smartwatch.
messages_1=[
  {"role": "system", "content": system_prompt},
  {"role": "user", "content": "Berikan saran pemasaran untuk smartwatch yang baru diluncurkan."}
]

# Pesan pengguna untuk permintaan kedua menanyakan tentang laptop. Karena system_prompt sama, kemungkinan besar terjadi cache hit.
messages_2=[
  {"role": "system", "content": system_prompt},
  {"role": "user", "content": "Berikan saran pemasaran untuk laptop yang baru diluncurkan."}
]

Dengan context cache, sistem dapat merespons lebih cepat karena prompt sistem yang panjang di-cache, bahkan saat Anda sering mengubah produk dalam permintaan Anda (misalnya, dari smartwatch ke laptop). 5. Pemahaman video

Dalam skenario pemahaman video, jika Anda mengajukan beberapa pertanyaan tentang video yang sama, menempatkan video sebelum teks meningkatkan probabilitas cache hit. Jika Anda mengajukan pertanyaan yang sama tentang video berbeda, menempatkan teks sebelum video meningkatkan probabilitas cache hit. Contoh berikut menunjukkan dua permintaan untuk video yang sama:

# Pesan pengguna untuk permintaan pertama menanyakan tentang konten video ini.
messages1 = [
    {"role":"system","content":[{"text": "Anda adalah asisten yang membantu."}]},
    {"role": "user",
        "content": [
            {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250328/eepdcq/phase_change_480p.mov"},
            {"text": "Apa isi video ini?"}
        ]
    }
]

# Untuk permintaan kedua tentang video yang sama, menempatkan video sebelum teks meningkatkan kemungkinan cache hit.
messages2 = [
    {"role":"system","content":[{"text": "Anda adalah asisten yang membantu."}]},
    {"role": "user",
        "content": [
            {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250328/eepdcq/phase_change_480p.mov"},
            {"text": "Jelaskan rangkaian peristiwa dalam video. Keluarkan waktu mulai (start_time), waktu selesai (end_time), dan event (event) dalam format JSON. Jangan sertakan blok kode ```json```."}
        ]
    }
]

FAQ

T: Berapa lama context cache disimpan (periode validitas)?

J: Periode validitas context cache tergantung pada jenis cache:

• Explicit cache: Periode validitas adalah 5 menit, dan setiap cache hit mengatur ulangnya menjadi 5 menit lagi. Jika blok cache tidak mengenai dalam 5 menit, sistem secara otomatis membersihkannya.
• Implicit cache: Dikelola secara otomatis oleh sistem tanpa periode validitas tetap. Sistem secara berkala membersihkan data cache yang telah lama tidak digunakan.

T: Bagaimana cara menonaktifkan implicit cache?

J: Anda tidak dapat menonaktifkannya. Implicit cache diaktifkan untuk semua permintaan model yang berlaku karena tidak memengaruhi kualitas respons. Saat terjadi cache hit, biaya berkurang dan kecepatan respons meningkat.

T: Mengapa cache miss eksplisit terjadi?

J: Cache miss dapat terjadi karena alasan berikut:

• Sistem membersihkan blok cache jika tidak mengenai dalam periode validitas 5 menit.
• Jika interval antara content terakhir dan blok cache yang sudah ada lebih dari 20 blok content, cache hit tidak akan terjadi. Kami menyarankan Anda membuat blok cache baru.

T: Apakah cache hit mengatur ulang validitasnya?

J: Ya. Setiap hit mengatur ulang periode validitas blok cache menjadi 5 menit.

T: Apakah explicit cache dibagikan antar akun?

J: Tidak. Data implicit cache dan explicit cache diisolasi pada tingkat akun.

T:Apakah explicit cache dibagikan lintas model?

J: Tidak. Data cache diisolasi antar model.

T: Mengapainput_tokensdalamusagetidak sama dengan jumlahcache_creation_input_tokensdancached_tokens?

J: Untuk memastikan kualitas output model, layanan backend menambahkan sejumlah kecil token (biasanya 10 atau kurang) ke prompt Anda. Token ini ditempatkan setelah penanda cache_control, sehingga tidak dihitung untuk pembuatan atau pembacaan cache, tetapi termasuk dalam total input_tokens.