Alibaba Cloud Model Studio:Context Cache

Cara kerja

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

Satu permintaan mendukung hingga empat penanda cache.

• Cache miss

  Jika terjadi cache miss, sistem membuat blok cache baru dari konten antara awal array messages hingga 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.

  Satu blok cache berisi minimal 1.024 token.

• Cache hit

  Jika terjadi cache hit, sistem memilih awalan yang paling panjang dan mereset 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, mereset 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 dengan cepat

Contoh berikut menunjukkan mekanisme pembuatan blok cache dan hit cache untuk protokol kompatibel OpenAI, DashScope, dan kompatibel 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 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.7-max",
        messages=messages,
    )
    return completion

# Permintaan pertama
first_completion = get_completion("What is the content of this code?")
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("How can this code be optimized?")
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 Generation
# 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 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,
        },
    ]
    response = Generation.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.7-max",
        messages=messages,
        result_format="message"
    )
    return response

# Permintaan pertama
first_completion = get_completion("What is the content of this code?")
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("How can this code be optimized?")
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 Java SDK: 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("What is the content of this code?");
            printCacheInfo(firstResult, "Permintaan pertama");
            System.out.println(new String(new char[20]).replace('\0', '='));            // Permintaan kedua
            GenerationResult secondResult = getCompletion("How can this code be optimized?");
            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 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.7-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("What is the content of this code?")
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("How can this code be optimized?")
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 pembuatan 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.

Misalnya, 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 cache 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 untuk bagian-bagian berbeda dari prompt. Hal ini meningkatkan rasio hit cache dan memungkinkan kontrol detail halus.

Penagihan

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).

  Misalnya, jika Anda memiliki cache 1.200 token yang sudah ada (Cache A) dan Anda menggunakan permintaan baru untuk menyimpan cache 1.500 token konten (Konten AB), 1.200 token pertama ditagih sebagai hit cache 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: Dikenakan biaya sebesar 10% dari harga token input standar.

  Parameter cached_tokens menentukan jumlah token yang di-cache.

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

Konten yang dapat di-cache

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

• Pesan sistem

  Catatan

  Untuk 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)

Misalnya, 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.

Optimalisasi cache untuk Pemanggilan Fungsi

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.

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.7-max",
        messages=messages,
    )
    return completion

# Permintaan pertama
first_completion = get_completion("What is the content of this code?")
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("What are some possible optimizations for this code?")
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 tertentu.",
            "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 tertentu.",
            "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 di 'content' pesan, bukan di '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("What's the weather like in Beijing now?")
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 (Hit cache) ===")
messages = [
    {
        "role": "system",
        "content": [
            {
                "type": "text",
                "text": long_text_content,
                "cache_control": {"type": "ephemeral"},
            }
        ],
    }
]
second_completion = get_completion("What's the weather like in Shanghai now?", 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 (Hit cache) ===
 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 = "You are a witty person." * 400
messages = [{"role": "system", "content": system_prompt}]

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

while True:
    user_input = input("User: ")
    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] Token pembuatan cache: {created_cache_tokens}")
    print(f"[Cache Info] Token hit cache: {hit_cached_tokens}")
    print(f"[Cache Info] Token tidak di-cache: {uncached_tokens}")

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 apakah terdapat awalan umum dari konten dalam array messages permintaan.

2. Keputusan:

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

   • Jika terjadi cache miss, sistem memproses permintaan secara normal dan menyimpan awalan prompt dalam cache untuk permintaan berikutnya.

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 hit cache

Hit implicit cache 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: Misalnya, asumsikan sistem telah menyimpan cache "ABCD". Permintaan untuk "ABE" mungkin mengenai bagian "AB", tetapi permintaan untuk "BCD" tidak akan mengenai cache.

• 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.

Penagihan

Tidak ada biaya tambahan untuk mengaktifkan mode cache implisit.

Saat permintaan mengenai cache, token input dari hit cache 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: 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 harga spesifik, lihat konsol Model Studio.

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

• Token tanpa hit cache (5.000): Ditagih 100% dari harga satuan.

• Token hit 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 hit cache dari atribut cached_tokens dalam respons.

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

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": "

   Array pesan permintaan berikutnya

   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 dari teks ini."}]

   Meskipun pertanyaannya berbeda, semuanya didasarkan pada artikel yang sama. Prompt sistem dan konten artikel yang sama membentuk banyak informasi awalan berulang, yang memiliki probabilitas tinggi untuk hit cache.

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 hit cache.

   Pesan putaran pertama

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

   Pesan putaran kedua

   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 berlangsung, manfaat caching untuk kecepatan inferensi dan biaya menjadi semakin 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.

   Misalnya, saat menginstruksikan model untuk bertindak sebagai ahli pemasaran, prompt sistem berisi teks panjang. Berikut 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 jam tangan pintar.
   messages_1=[
     {"role": "system", "content": system_prompt},
     {"role": "user", "content": "Berikan saran pemasaran untuk jam tangan pintar yang baru diluncurkan."}
   ]
   
   # Pesan pengguna untuk permintaan kedua menanyakan tentang laptop. Karena system_prompt sama, kemungkinan besar terjadi hit cache.
   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 (misalnya, dari jam tangan pintar ke laptop).

5. Pemahaman video

   Dalam skenario pemahaman video, jika Anda mengajukan beberapa pertanyaan tentang video yang sama, menempatkan video sebelum teks meningkatkan probabilitas hit cache. Jika Anda mengajukan pertanyaan yang sama tentang video berbeda, menempatkan teks sebelum video meningkatkan probabilitas hit cache. 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 hit cache.
   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 akhir (end_time), dan event (event) dalam format JSON. Jangan sertakan blok kode ```json```."}
           ]
       }
   ]

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 hit cache meresetnya menjadi 5 menit lagi. Jika blok cache tidak terkena 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 cache implisit?

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

T: Mengapa terjadi cache miss pada cache eksplisit saya?

J: Cache miss dapat terjadi karena alasan berikut:

• Sistem membersihkan blok cache jika tidak terkena dalam periode validitas 5 menitnya.

• Jika interval antara content terakhir dan blok cache yang sudah ada lebih dari 20 blok content, hit cache tidak akan terjadi. Kami menyarankan Anda membuat blok cache baru.

T: Apakah hit cache mereset validitasnya?

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

T: Apakah cache eksplisit dibagikan antar akun?

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

T: Apakah explicit cache dibagikan antar model?

J: Tidak. Data cache diisolasi antar model.

T: Mengapa input_tokens dalam usage tidak sama dengan jumlah cache_creation_input_tokens dan cached_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.