Alibaba Cloud Model Studio：Context Cache

Model yang didukung

Cara kerja

Saat Anda mengirim permintaan ke model yang mendukung implicit cache, fitur ini diaktifkan secara otomatis. Sistem bekerja sebagai berikut:

1. Pencarian: Saat permintaan diterima, sistem memeriksa apakah ada awalan umum dari konten dalam array messages yang tersimpan di cache. Pemeriksaan ini berdasarkan prinsip pencocokan awalan.

2. Keputusan:

   • Jika terjadi cache hit, sistem menggunakan hasil cache untuk inferensi berikutnya.

   • Jika terjadi cache miss, sistem memproses permintaan secara normal dan menyimpan awalan prompt saat ini di cache untuk penggunaan di masa depan.

Sistem secara berkala melakukan purge terhadap data cache yang sudah lama tidak digunakan. Tingkat hit context cache tidak mencapai 100%. Cache miss dapat terjadi meskipun konteks permintaannya identik. Sistem menentukan tingkat hit yang tepat.

Meningkatkan probabilitas cache hit

Implicit cache menentukan hit dengan memeriksa apakah permintaan yang berbeda memiliki awalan yang sama. Untuk meningkatkan tingkat cache hit, letakkan konten yang berulang di awal prompt dan konten yang bervariasi di akhir.

• Model teks: Misalnya, jika sistem telah menyimpan cache "ABCD", permintaan "ABE" mungkin menghasilkan cache hit untuk bagian "AB", tetapi permintaan "BCD" tidak akan menghasilkan cache hit.

• Model pemahaman visual:

  • Untuk beberapa pertanyaan tentang gambar atau video yang sama, letakkan gambar atau video sebelum teks untuk meningkatkan tingkat cache hit.

  • Untuk pertanyaan yang sama tentang gambar atau video yang berbeda, letakkan teks sebelum gambar atau video untuk meningkatkan tingkat cache hit.

Penagihan

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

Saat permintaan menghasilkan cache hit, token input yang cocok ditagih sebagai cached_token sebesar 20% dari harga standar input_token. Token input yang tidak cocok ditagih sesuai harga standar input_token. Token output ditagih sesuai harga standar.

Misalnya, jika permintaan berisi 10.000 token input dan 5.000 di antaranya menghasilkan cache hit, penagihannya dihitung sebagai berikut:

• Token yang tidak cocok (5.000): Ditagih 100% dari harga standar

• Token yang cocok (5.000): Ditagih 20% dari harga standar

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

Anda dapat mengambil jumlah token yang di-cache dari atribut cached_tokens dalam respons.

OpenAI compatible batch tidak memenuhi syarat untuk diskon cache.

Skenario

Jika permintaan Anda memiliki awalan yang sama, context cache dapat secara signifikan meningkatkan kecepatan inferensi, mengurangi biaya inferensi, dan menurunkan latensi paket pertama. Berikut adalah skenario aplikasi khas:

1. Tanya jawab berdasarkan teks panjang

   Berlaku untuk skenario bisnis yang memerlukan beberapa permintaan untuk teks panjang tetap, seperti novel, buku pelajaran, atau dokumen hukum.

   Array pesan untuk permintaan pertama

   messages = [{"role": "system","content": "You are a Chinese language teacher who helps students with reading comprehension."},
             {"role": "user","content": "<Article Content> What feelings and thoughts does the author express in this text?"}]

   Array pesan untuk permintaan selanjutnya

   messages = [{"role": "system","content": "You are a Chinese language teacher who helps students with reading comprehension."},
             {"role": "user","content": "<Article Content> Please analyze the third paragraph of this text."}]

   Meskipun pertanyaannya berbeda, keduanya didasarkan pada artikel yang sama. Prompt sistem dan konten artikel yang identik membentuk awalan besar yang berulang, sehingga menghasilkan tingkat cache hit yang tinggi.

2. Penyelesaian kode otomatis

   Dalam skenario penyelesaian kode otomatis, LLM menyelesaikan kode berdasarkan konteks yang ada. Saat pengguna terus menulis kode, awalan kode tetap tidak berubah. Context cache dapat menyimpan kode sebelumnya untuk mempercepat kecepatan penyelesaian.

3. Percakapan multi-putaran

   Menerapkan percakapan multi-putaran memerlukan penambahan dialog setiap putaran ke array messages. Oleh karena itu, setiap permintaan baru memiliki awalan yang sama dengan putaran sebelumnya, sehingga menghasilkan tingkat cache hit yang tinggi.

   Array pesan untuk giliran pertama

   messages=[{"role": "system","content": "You are a helpful assistant."},
             {"role": "user","content": "Who are you?"}]

   Array pesan untuk giliran kedua

   messages=[{"role": "system","content": "You are a helpful assistant."},
             {"role": "user","content": "Who are you?"},
             {"role": "assistant","content": "I am Qwen, developed by Alibaba Cloud."},
             {"role": "user","content": "What can you do?"}]

   Saat jumlah putaran percakapan bertambah, keunggulan kecepatan dan biaya caching menjadi semakin signifikan.

4. Role-playing atau pembelajaran few-shot

   Dalam skenario role-playing atau pembelajaran few-shot, Anda biasanya menyertakan panduan ekstensif dalam prompt untuk menentukan format output model. Hal ini menciptakan awalan besar yang berulang di berbagai permintaan.

   Misalnya, agar model bertindak sebagai ahli pemasaran, prompt sistem berisi teks yang substansial. Berikut adalah contoh messages untuk dua permintaan:

   system_prompt = """You are an experienced marketing expert. Please provide detailed marketing suggestions for different products in the following format:
   
   1. Target audience: xxx
   
   2. Key selling points: xxx
   
   3. Marketing channels: xxx
   ...
   12. Long-term development strategy: xxx
   
   Ensure your suggestions are specific, actionable, and highly relevant to product features."""
   
   # First request asks about a smartwatch
   messages_1=[
     {"role": "system", "content": system_prompt},
     {"role": "user", "content": "Please provide marketing suggestions for a newly launched smartwatch."}
   ]
   
   # Second request asks about a laptop. Since system_prompt is identical, cache hit probability is high.
   messages_2=[
     {"role": "system", "content": system_prompt},
     {"role": "user", "content": "Please provide marketing suggestions for a newly launched laptop."}
   ]

   Dengan context cache, sistem dapat merespons dengan cepat setelah cache hit dipicu, bahkan jika pengguna sering berganti jenis produk, misalnya dari smartwatch ke laptop.

5. Pemahaman video

   Dalam skenario pemahaman video, untuk beberapa pertanyaan tentang video yang sama, meletakkan video sebelum teks meningkatkan tingkat cache hit. Untuk pertanyaan yang sama tentang video yang berbeda, meletakkan teks sebelum video meningkatkan tingkat hit. Berikut adalah contoh messages untuk dua permintaan tentang video yang sama:

   # First request asks about video content
   messages1 = [
       {"role":"system","content":[{"text": "You are a helpful assistant."}]},
       {"role": "user",
           "content": [
               {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250328/eepdcq/phase_change_480p.mov"},
               {"text": "What is the content of this video?"}
           ]
       }
   ]
   
   # Second request asks about video timestamps. Since it's the same video, placing video before text increases cache hit probability.
   messages2 = [
       {"role":"system","content":[{"text": "You are a helpful assistant."}]},
       {"role": "user",
           "content": [
               {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250328/eepdcq/phase_change_480p.mov"},
               {"text": "Describe the series of events in the video. Output start time (start_time), end time (end_time), and event (event) in JSON format. Do not include the ```json``` code block."}
           ]
       }
   ]

Penggunaan

Anda dapat menambahkan penanda "cache_control": {"type": "ephemeral"} ke messages. Sistem kemudian mencoba mendapatkan cache hit dengan menelusuri mundur hingga 20 blok content dari posisi setiap penanda cache_control.

Satu permintaan mendukung maksimal empat penanda cache.

• Cache miss

  Sistem membuat blok cache baru yang menggunakan konten dari awal array messages hingga penanda cache_control. Blok ini berlaku selama 5 menit.

  Cache dibuat setelah model merespons. Anda hanya dapat mencoba mendapatkan cache hit setelah permintaan pembuatan selesai.

  Konten blok cache harus berisi minimal 1.024 token.

• Cache hit

  Sistem memilih awalan yang paling panjang sebagai cache hit dan mengatur ulang periode validitas blok cache menjadi 5 menit.

Berikut adalah contohnya:

1. Kirim permintaan pertama: Kirim pesan sistem yang berisi lebih dari 1.024 token teks A dengan penanda cache:

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

   Sistem membuat blok cache pertama, yang diberi label sebagai blok cache A.

2. Kirim permintaan kedua: Kirim permintaan yang memiliki struktur berikut:

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

   • Jika "other messages" memiliki 20 entri atau kurang, terjadi cache hit untuk blok cache A dan periode validitasnya diatur ulang menjadi 5 menit. Pada saat yang sama, sistem membuat blok cache baru berdasarkan A, other messages, dan B.

   • Jika "other messages" memiliki lebih dari 20 entri, tidak terjadi cache hit untuk blok cache A. Sistem tetap membuat blok cache baru berdasarkan konteks lengkap (A + other messages + B).

Model yang didukung

Qwen Max: qwen3-max

Qwen Plus: qwen-plus

Qwen Flash: qwen-flash

Qwen-Coder: qwen3-coder-plus, qwen3-coder-flash

Model yang tercantum di atas mendukung explicit cache baik dalam mode penyebaran China Daratan maupun Internasional.

Model snapshot dan latest saat ini tidak didukung.

Qwen VL: qwen3-vl-plus

Model qwen3-vl-plus hanya mendukung explicit cache dalam mode penyebaran China Daratan.

DeepSeek-Alibaba Cloud Model Studio: deepseek-v3.2

Model deepseek-v3.2 hanya mendukung explicit cache dalam mode penyebaran China Daratan.

Memulai

Contoh berikut menunjukkan mekanisme pembuatan dan hit blok cache menggunakan antarmuka kompatibel OpenAI dan protokol DashScope.

from openai import OpenAI
import os

client = OpenAI(
    # If you haven't configured an environment variable, replace the next line with: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # For Beijing region models, use: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

# Simulated code repository content. Minimum cacheable prompt length is 1,024 tokens.
long_text_content = "<Your Code Here>" * 400

# Request function
def get_completion(user_input):
    messages = [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": long_text_content,
                    # Place cache_control marker here to create a cache block from the start of messages to this content position.
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        # Question content differs each time
        {
            "role": "user",
            "content": user_input,
        },
    ]
    completion = client.chat.completions.create(
        # Select a model that supports explicit cache
        model="qwen3-coder-plus",
        messages=messages,
    )
    return completion

# First request
first_completion = get_completion("What is this code about?")
print(f"First request created cache tokens: {first_completion.usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"First request hit cache tokens: {first_completion.usage.prompt_tokens_details.cached_tokens}")
print("=" * 20)
# Second request, same code content, different question
second_completion = get_completion("How can this code be optimized?")
print(f"Second request created cache tokens: {second_completion.usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"Second request hit cache tokens: {second_completion.usage.prompt_tokens_details.cached_tokens}")

import os
from dashscope import Generation
# For Beijing region models, set base_url to: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = "https://dashscope-intl.aliyuncs.com/api/v1"

# Simulated code repository content. Minimum cacheable prompt length is 1,024 tokens.
long_text_content = "<Your Code Here>" * 400

# Request function
def get_completion(user_input):
    messages = [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": long_text_content,
                    # Place cache_control marker here to create a cache block from the start of messages to this content position.
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        # Question content differs each time
        {
            "role": "user",
            "content": user_input,
        },
    ]
    response = Generation.call(
        # If environment variable isn't configured, replace with your Model Studio API key: api_key = "sk-xxx",
        api_key=os.getenv("DASHSCOPE_API_KEY"), 
        model="qwen3-coder-plus",
        messages=messages,
        result_format="message"
    )
    return response

# First request
first_completion = get_completion("What is this code about?")
print(f"First request created cache tokens: {first_completion.usage.prompt_tokens_details['cache_creation_input_tokens']}")
print(f"First request hit cache tokens: {first_completion.usage.prompt_tokens_details['cached_tokens']}")
print("=" * 20)
# Second request, same code content, different question
second_completion = get_completion("How can this code be optimized?")
print(f"Second request created cache tokens: {second_completion.usage.prompt_tokens_details['cache_creation_input_tokens']}")
print(f"Second request hit cache tokens: {second_completion.usage.prompt_tokens_details['cached_tokens']}")

// Minimum Java SDK version is 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";
    // Simulate code repository content (400 repetitions ensure over 1,024 tokens)
    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 {
        // For Beijing region models, set base_url to: https://dashscope.aliyuncs.com/api/v1
        Generation gen = new Generation("http", "https://dashscope-intl.aliyuncs.com/api/v1");

        // Build system message with cache control
        MessageContentText systemContent = MessageContentText.builder()
                .type("text")
                .text(LONG_TEXT_CONTENT)
                .cacheControl(MessageContentText.CacheControl.builder()
                        .type("ephemeral") // Set cache type
                        .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();

        // Build request parameters
        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 created cache tokens: %d%n", requestLabel, result.getUsage().getPromptTokensDetails().getCacheCreationInputTokens());
        System.out.printf("%s hit cache tokens: %d%n", requestLabel, result.getUsage().getPromptTokensDetails().getCachedTokens());
    }

    public static void main(String[] args) {
        try {
            // First request
            GenerationResult firstResult = getCompletion("What is this code about?");
            printCacheInfo(firstResult, "First request");
            System.out.println(new String(new char[20]).replace('\0', '='));            // Second request
            GenerationResult secondResult = getCompletion("How can this code be optimized?");
            printCacheInfo(secondResult, "Second request");
        } catch (NoApiKeyException | ApiException | InputRequiredException e) {
            System.err.println("API call failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Konten repositori kode simulasi mengaktifkan explicit cache dengan menambahkan penanda cache_control. Permintaan berikutnya tentang repositori ini menggunakan kembali blok cache tanpa perhitungan ulang. Hal ini memberikan respons lebih cepat dan biaya lebih rendah.

First request created cache tokens: 1605
First request hit cache tokens: 0
====================
Second request created cache tokens: 0
Second request hit cache tokens: 1605

Gunakan beberapa penanda cache untuk kontrol detail halus

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

Misalnya, prompt layanan pelanggan cerdas biasanya mencakup bagian-bagian berikut:

• Persona sistem: Bagian ini sangat stabil dan jarang berubah.

• Pengetahuan eksternal: Bagian ini semi-stabil dan diambil dari basis pengetahuan atau menggunakan kueri tool. Bagian ini mungkin tetap tidak berubah selama percakapan berkelanjutan.

• Riwayat percakapan: Bagian ini tumbuh secara dinamis.

• Pertanyaan saat ini: Bagian ini berbeda setiap kali.

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

Anda dapat mengatur maksimal empat penanda cache per permintaan untuk membuat blok cache terpisah bagi bagian-bagian berbeda dari prompt. Hal ini meningkatkan tingkat hit dan memungkinkan kontrol detail halus.

Penagihan

Explicit cache hanya memengaruhi penagihan token input. Aturan penagihannya adalah sebagai berikut:

• Pembuatan cache: Konten cache baru ditagih sebesar 125% dari harga input standar. Jika konten cache permintaan baru mencakup cache yang sudah ada sebagai awalan, hanya bagian barunya yang ditagih. Jumlah yang ditagih dihitung berdasarkan jumlah token cache baru dikurangi jumlah token cache yang sudah ada.

  Misalnya, jika cache A yang sudah ada memiliki 1.200 token dan permintaan baru perlu menyimpan cache 1.500 token 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.

  Anda dapat melihat jumlah token yang digunakan untuk pembuatan cache menggunakan parameter cache_creation_input_tokens.

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

  Anda dapat melihat jumlah token yang di-cache menggunakan parameter cached_tokens.

• Token lainnya: Token yang tidak cocok dan token yang tidak digunakan untuk membuat cache ditagih sesuai harga standar.

Konten yang dapat di-cache

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

• Pesan sistem

• Pesan pengguna

  Saat Anda membuat cache dengan model qwen3-vl-plus, penanda cache_control dapat mengikuti konten multimodal atau teks tanpa memengaruhi cache seluruh pesan pengguna.

• Pesan asisten

• Pesan tool (hasil eksekusi tool)

  Jika permintaan mencakup parameter tools, menambahkan penanda cache di messages juga menyimpan cache informasi deskripsi tool.

Untuk pesan sistem, Anda dapat mengubah bidang content menjadi array dan menambahkan bidang cache_control:

{
  "role": "system",
  "content": [
    {
      "type": "text",
      "text": "<Specified Prompt>",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

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

Batas cache

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

• Cache menggunakan pencocokan awalan mundur. Sistem memeriksa 20 blok konten terakhir. Jika konten yang akan dicocokkan dipisahkan dari penanda cache_control oleh lebih dari 20 blok konten, cache hit tidak terjadi.

• Hanya nilai ephemeral yang didukung untuk parameter type. Nilai ini menentukan periode validitas 5 menit.

• Satu permintaan mendukung maksimal empat penanda cache.

  Jika lebih dari empat penanda ditambahkan, hanya empat penanda terakhir yang berlaku.

Contoh penggunaan

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # For Beijing region models, set base_url to: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

# Simulated code repository content
long_text_content = "<Your Code Here>" * 400

# Request function
def get_completion(user_input):
    messages = [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": long_text_content,
                    # Place cache_control marker here to create a cache from prompt start to this content end (simulated code repository).
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        {
            "role": "user",
            "content": user_input,
        },
    ]
    completion = client.chat.completions.create(
        # Select a model that supports explicit cache
        model="qwen3-coder-plus",
        messages=messages,
    )
    return completion

# First request
first_completion = get_completion("What is this code about?")
created_cache_tokens = first_completion.usage.prompt_tokens_details.cache_creation_input_tokens
print(f"First request created cache tokens: {created_cache_tokens}")
hit_cached_tokens = first_completion.usage.prompt_tokens_details.cached_tokens
print(f"First request hit cache tokens: {hit_cached_tokens}")
print(f"First request tokens not hit or created in cache: {first_completion.usage.prompt_tokens-created_cache_tokens-hit_cached_tokens}")
print("=" * 20)
# Second request, same code content, different question
second_completion = get_completion("What optimizations are possible for this code?")
created_cache_tokens = second_completion.usage.prompt_tokens_details.cache_creation_input_tokens
print(f"Second request created cache tokens: {created_cache_tokens}")
hit_cached_tokens = second_completion.usage.prompt_tokens_details.cached_tokens
print(f"Second request hit cache tokens: {hit_cached_tokens}")
print(f"Second request tokens not hit or created in cache: {second_completion.usage.prompt_tokens-created_cache_tokens-hit_cached_tokens}")

First request created cache tokens: 1605
First request hit cache tokens: 0
First request tokens not hit or created in cache: 13
====================
Second request created cache tokens: 0
Second request hit cache tokens: 1605
Second request tokens not hit or created in cache: 15

from openai import OpenAI
import os
  
client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # For Beijing region models, set base_url to: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

system_prompt = "You are a witty person." * 400
messages = [{"role": "system", "content": system_prompt}]

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

while True:
    user_input = input("Enter:")
    messages.append({"role": "user", "content": [{"type": "text", "text": user_input, "cache_control": {"type": "ephemeral"}}]})
    completion = get_completion(messages)
    print(f"[AI Response] {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"[Cache Info] Created cache tokens: {created_cache_tokens}")
    print(f"[Cache Info] Hit cache tokens: {hit_cached_tokens}")
    print(f"[Cache Info] Tokens not hit or created in cache: {uncached_tokens}")

FAQ