Alibaba Cloud Model Studio：Context cache

Ketersediaan model

Cara kerjanya

Saat mengirim permintaan ke model yang mendukung cache implisit, fitur ini bekerja secara otomatis:

1. Pencarian: Setelah sistem menerima permintaan, ia menggunakan pencocokan awalan untuk menentukan apakah awalan umum dari konten dalam array messages ada di dalam cache.

2. Keputusan:

   • Jika terjadi hit cache, sistem menggunakan hasil cache untuk pembangkitan.

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

Sistem secara berkala membersihkan data cache yang belum digunakan dalam waktu lama. Tingkat hit cache tidak dijamin 100%. Miss cache dapat terjadi bahkan untuk konteks permintaan yang identik. Sistem menentukan probabilitas hit aktual.

Meningkatkan tingkat hit

Hit cache implisit terjadi ketika sistem menentukan bahwa permintaan yang berbeda berbagi awalan yang umum. Untuk meningkatkan tingkat hit, tempatkan konten yang berulang di awal prompt dan konten variabel di akhir.

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

• Model pemahaman visual:

  • Untuk beberapa pertanyaan tentang gambar atau video yang sama: Tempatkan gambar atau video sebelum teks untuk meningkatkan probabilitas hit.

  • Untuk pertanyaan yang sama tentang gambar atau video yang berbeda: Tempatkan teks sebelum gambar atau video untuk meningkatkan probabilitas hit.

Penagihan

Tidak ada biaya tambahan untuk mengaktifkan mode cache implisit.

Saat permintaan mengenai cache, token input yang cocok dibebankan sebagai cached_tokens sebesar 20% dari harga standar input_token. Token input yang tidak cocok dibebankan pada harga standar input_token. Token output dibebankan pada harga standar.

Contoh: Sebuah permintaan berisi 10.000 token input, dan 5.000 di antaranya mengenai cache. Biayanya dihitung sebagai berikut:

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

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

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

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

OpenAI compatible batch tidak memenuhi syarat untuk diskon cache.

Skenario tipikal

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

1. Tanya jawab berdasarkan teks panjang

   Ini cocok untuk skenario yang memerlukan pengiriman beberapa permintaan untuk teks panjang tetap, seperti novel, buku teks, atau dokumen hukum.

   Array pesan untuk permintaan pertama

   messages = [{"role": "system","content": "Anda adalah guru bahasa yang dapat membantu siswa dengan pemahaman bacaan."},
             {"role": "user","content": "<Isi Artikel> Apa perasaan dan pikiran yang diekspresikan penulis dalam teks ini?"}]

   Array pesan yang digunakan dalam permintaan selanjutnya

   messages = [{"role": "system","content": "Anda adalah guru bahasa yang dapat membantu siswa dengan pemahaman bacaan."},
             {"role": "user","content": "<Isi Artikel> Silakan analisis paragraf ketiga dari teks ini."}]

   Meskipun pertanyaannya berbeda, semuanya didasarkan pada artikel yang sama. Prompt sistem yang identik dan isi artikel membentuk awalan besar yang berulang, yang menghasilkan probabilitas hit cache yang tinggi.

2. Auto-completion kode

   Dalam skenario pengisian otomatis kode, model melengkapi kode berdasarkan kode yang ada dalam konteks. Saat pengguna menulis lebih banyak kode, awalan kode tetap tidak berubah. Cache Konteks dapat menyimpan kode yang ada untuk meningkatkan kecepatan pengisian.

3. Percakapan multi-putaran

   Untuk menerapkan percakapan multi-putaran, Anda dapat menambahkan riwayat percakapan dari setiap putaran ke array pesan. Oleh karena itu, setiap permintaan baru berisi putaran sebelumnya sebagai awalan, menghasilkan probabilitas hit cache yang tinggi.

   Array pesan untuk putaran pertama

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

   Array pesan untuk putaran kedua

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

   Saat jumlah putaran percakapan bertambah, penyimpanan cache memberikan keuntungan yang lebih signifikan untuk kecepatan inferensi dan biaya.

4. Bermain peran atau pembelajaran few-shot

   Dalam skenario bermain peran atau pembelajaran few-shot, Anda biasanya perlu menyertakan sejumlah besar informasi dalam prompt untuk membimbing format output model. Ini menghasilkan sejumlah besar informasi awalan yang berulang antara permintaan yang berbeda.

   Sebagai contoh, untuk membuat model bertindak sebagai ahli pemasaran, prompt sistem berisi sejumlah besar teks. Berikut adalah contoh pesan untuk dua permintaan:

   system_prompt = """Anda adalah ahli pemasaran berpengalaman. Harap berikan saran pemasaran rinci untuk produk yang 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 dilaksanakan, dan sangat relevan dengan fitur produk."""
   
   # Pesan pengguna pertama bertanya tentang smartwatch
   messages_1=[
     {"role": "system", "content": system_prompt},
     {"role": "user", "content": "Harap berikan saran pemasaran untuk smartwatch baru yang diluncurkan."}
   ]
   
   # Pesan pengguna kedua bertanya tentang laptop. Karena system_prompt sama, ada kemungkinan tinggi untuk hit cache.
   messages_2=[
     {"role": "system", "content": system_prompt},
     {"role": "user", "content": "Harap berikan saran pemasaran untuk laptop baru yang diluncurkan."}
   ]

   Dengan cache konteks, meskipun pengguna sering mengubah jenis produk yang ditanyakan, seperti dari smartwatch ke laptop, sistem dapat merespons dengan cepat setelah cache dipicu.

5. Pemahaman video

   Dalam skenario pemahaman video, jika Anda mengajukan beberapa pertanyaan tentang video yang sama, menempatkan video sebelum teks meningkatkan tingkat hit. Jika Anda mengajukan pertanyaan yang sama tentang video yang berbeda, menempatkan teks sebelum video meningkatkan tingkat hit. Berikut adalah contoh pesan untuk dua permintaan tentang video yang sama:

   # Pesan pengguna untuk permintaan pertama bertanya tentang isi 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?"}
           ]
       }
   ]
   
   # Pesan pengguna untuk permintaan kedua bertanya tentang cap waktu video. Karena pertanyaan didasarkan pada video yang sama, menempatkan video sebelum teks memiliki kemungkinan tinggi 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": "Harap jelaskan serangkaian peristiwa dalam video. Keluarkan waktu mulai (start_time), waktu akhir (end_time), dan peristiwa (event) dalam format JSON. Jangan sertakan segmen kode ```json```."}
           ]
       }
   ]

Penggunaan

Tambahkan penanda "cache_control": {"type": "ephemeral"} ke pesan. Sistem kemudian mencoba hit cache dengan menelusuri hingga 20 blok content dari posisi setiap penanda cache_control.

Permintaan tunggal mendukung hingga 4 penanda cache.

• Cache miss

  Sistem membuat blok cache baru menggunakan konten dari awal array pesan hingga penanda cache_control. Periode validitasnya adalah 5 menit.

  Pembuatan cache terjadi setelah model merespons. Cobalah untuk mengenai cache setelah permintaan pembuatan selesai.

  Panjang konten minimum untuk blok cache adalah 1.024 token.

• Cache hit

  Pencocokan awalan terpanjang dipilih sebagai blok cache hit, dan periode validitas blok cache diatur ulang menjadi 5 menit.

Berikut adalah contohnya:

1. Mulai permintaan pertama: Kirim pesan sistem yang berisi teks A dengan 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. Mulai permintaan kedua: Kirim permintaan dengan struktur berikut:

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

   • Jika tidak ada lebih dari 20 "pesan lainnya", blok cache A terkena, dan periode validitasnya diatur ulang menjadi 5 menit. Pada saat yang sama, sistem membuat blok cache baru berdasarkan konten A, pesan lainnya, dan B.

   • Jika ada lebih dari 20 "pesan lainnya", blok cache A tidak terkena hit. Sistem tetap membuat blok cache baru berdasarkan konteks lengkap (A + pesan lainnya + B).

Ketersediaan model

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 fitur cache eksplisit di wilayah Tiongkok daratan dan internasional.

Snapshot dan model terbaru saat ini tidak didukung.

Memulai

Contoh berikut menunjukkan mekanisme pembuatan dan hit blok cache dalam API OpenAI compatible dan protokol DashScope.

from openai import OpenAI
import os

client = OpenAI(
    # Jika Anda belum mengekspor variabel lingkungan, ganti baris berikut dengan api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Jika menggunakan model dari wilayah Singapura, ganti base_url dengan https://dashscope-intl.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

# Konten repositori kode simulasi. Panjang prompt minimum untuk caching 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,
                    # Letakkan penanda cache_control di sini untuk membuat blok cache dari awal array messages hingga posisi konten saat ini.
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        # Konten pertanyaan berbeda setiap kali
        {
            "role": "user",
            "content": user_input,
        },
    ]
    completion = client.chat.completions.create(
        # Pilih model yang mendukung explicit cache
        model="qwen3-coder-plus",
        messages=messages,
    )
    return completion

# Permintaan pertama
first_completion = get_completion("What is the content of this code?")
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)
# Permintaan kedua, konten kode sama, hanya pertanyaannya yang berubah
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
# Jika menggunakan model dari wilayah Singapura, harap hapus komentar baris berikut.
# dashscope.base_http_api_url = "https://dashscope-intl.aliyuncs.com/api/v1"

# Konten repositori kode simulasi. Panjang prompt minimum untuk caching 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,
                    # Letakkan penanda cache_control di sini untuk membuat blok cache dari awal array messages hingga posisi konten saat ini.
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        # Konten pertanyaan berbeda setiap kali
        {
            "role": "user",
            "content": user_input,
        },
    ]
    response = Generation.call(
        # Jika variabel lingkungan tidak dikonfigurasi, ganti baris ini dengan Kunci API Model Studio Anda: api_key = "sk-xxx",
        api_key=os.getenv("DASHSCOPE_API_KEY"), 
        model="qwen3-coder-plus",
        messages=messages,
        result_format="message"
    )
    return response

# Permintaan pertama
first_completion = get_completion("What is the content of this code?")
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)
# Permintaan kedua, konten kode sama, hanya pertanyaannya yang berubah
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"]}")

// Versi minimum Java SDK adalah 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";
    // Simulasikan konten repositori kode (ulangi 400 kali untuk memastikan melebihi 1024 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 {
        // Jika menggunakan model di wilayah Singapura, ganti https://dashscope.aliyuncs.com/api/v1 dengan https://dashscope-intl.aliyuncs.com/api/v1
        Generation gen = new Generation();

        // 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 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 {
            // Permintaan pertama
            GenerationResult firstResult = getCompletion("What is the content of this code?");
            printCacheInfo(firstResult, "First request");
            System.out.println(new String(new char[20]).replace('\0', '='));            // Permintaan kedua
            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();
        }
    }
}

Repositori kode simulasi mengaktifkan cache eksplisit dengan menambahkan penanda cache_control. Untuk permintaan berikutnya yang menanyakan repositori kode ini, sistem dapat menggunakan kembali blok cache ini tanpa perhitungan ulang. Ini menghasilkan respons yang lebih cepat dan biaya yang lebih rendah.

Token cache dibuat pada permintaan pertama: 1605
Token cache terkena hit pada permintaan pertama: 0
====================
Token cache dibuat pada permintaan kedua: 0
Token cache terkena hit pada permintaan kedua: 1605

Gunakan beberapa penanda cache untuk kontrol yang lebih halus

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

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

• Persona sistem: Sangat stabil dan jarang berubah.

• Pengetahuan eksternal: Semi-stabil. Konten ini diambil dari basis pengetahuan atau kueri alat dan mungkin tetap tidak berubah selama percakapan berkelanjutan.

• Sejarah percakapan: Berkembang secara dinamis.

• Pertanyaan saat ini: Berbeda setiap kali.

Jika seluruh prompt disimpan sebagai satu unit, perubahan kecil, seperti pembaruan pada pengetahuan eksternal, dapat menyebabkan miss cache.

Sebaliknya, Anda dapat menyetel hingga empat penanda cache dalam permintaan untuk membuat blok cache terpisah untuk bagian-bagian prompt yang berbeda. Ini meningkatkan tingkat hit dan memungkinkan kontrol detail halus.

• Permintaan pertama: Buat beberapa blok cache

  Pengguna pertama kali bertanya tentang Produk A. Array messages adalah sebagai berikut:

  [
      {
          "role": "system",
          "content": [
              {
                  "type": "text",
                  // Informasi persona harus lebih besar dari 1.024 token
                  "text": "### Persona Sistem ###\nAnda adalah agen layanan pelanggan e-commerce profesional yang bertanggung jawab untuk menjawab pertanyaan pengguna tentang produk, pesanan, dan logistik. Jawaban Anda harus ringkas dan ramah...",
                  // Penanda 1: Buat blok cache yang dapat digunakan kembali untuk persona
                  "cache_control": {"type": "ephemeral"}
              }
          ]
      },
      {
          "role": "user",
          "content": [
              {
                  "type": "text",
                  "text": "### Basis Pengetahuan ###\nTentang Produk A:\n- Material: Katun murni\n- Pengiriman dari: Hangzhou\n- Waktu pengiriman perkiraan: Dalam 24 jam"
                  // Penanda 2: Buat blok cache yang dapat digunakan kembali untuk persona + basis pengetahuan
                  "cache_control": {"type": "ephemeral"}
              },
              {
                  "type": "text",
                  "text": "### Pertanyaan Pengguna ###\nApa material Produk A?"
              }
          ]
      }
  ]

  Sistem membuat dua blok cache:

  • Blok cache A: [Persona Sistem].

  • Blok cache B: [Persona Sistem] + [Potongan Basis Pengetahuan]

• Permintaan kedua

  Permintaan kedua mungkin tentang Produk A atau produk lainnya. Karena beberapa blok cache dibuat dalam permintaan pertama, sistem dapat mengenai cache yang sesuai dalam skenario yang berbeda.

  • Skenario 1: Pengguna mengajukan pertanyaan lanjutan tentang Produk A

    Pertanyaan baru: "Dari mana produk ini dikirim?" Dalam hal ini, baik persona sistem maupun basis pengetahuan tetap tidak berubah.

    [
        {
            "role": "system",
            "content": [
              {
                "type": "text",
                "text": "### Persona Sistem ###\nAnda adalah agen layanan pelanggan e-commerce profesional yang bertanggung jawab untuk menjawab pertanyaan pengguna tentang produk, pesanan, dan logistik. Jawaban Anda harus ringkas dan ramah...",
                "cache_control": { "type": "ephemeral" }
              }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "### Basis Pengetahuan ###\nTentang Produk A:\n- Material: Katun murni\n- Pengiriman dari: Hangzhou\n- Waktu pengiriman perkiraan: Dalam 24 jam"
                    // Penanda 2 masih ada
                    "cache_control": {"type": "ephemeral"}
                },
                {
                    "type": "text",
                    "text": "### Pertanyaan Pengguna ###\nDari mana produk ini dikirim?" // Bagian yang berubah
                }
            ]
        }
    ]

    Hasil hit: Sistem memprioritaskan pencocokan awalan terpanjang dan mengenai blok cache B ([Persona Sistem] + [Potongan Basis Pengetahuan]).

  • Skenario 2: Pengguna bertanya tentang "Produk X" sebagai gantinya

    Pertanyaan baru: "Kapan Produk X akan dikirim?" Dalam hal ini, persona sistem tetap tidak berubah, tetapi bagian basis pengetahuan diperbarui.

    [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": "### Persona SSistem ###\nAnda adalah agen layanan pelanggan e-commerce profesional yang bertanggung jawab untuk menjawab pertanyaan pengguna tentang produk, pesanan, dan logistik. Jawaban Anda harus ringkas dan ramah...",
                    // Penanda 1 masih ada
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "### Basis Pengetahuan ###\nTentang Produk X:\n- Material: Poliester\n- Pengiriman dari: Guangzhou\n- Waktu pengiriman perkiraan: Dalam 48 jam" // Konten basis pengetahuan telah berubah
                    // Penanda 2 masih ada
                    "cache_control": {"type": "ephemeral"}
                },
                {
                    "type": "text",
                    "text": "### Pertanyaan Pengguna ###\nKapan Produk X akan dikirim?"
                }
            ]
        }
    ]

    Hasil hit: Perubahan pada basis pengetahuan menyebabkan miss cache untuk blok B, tetapi sistem masih dapat mengenai blok cache A ([Persona Sistem]). Secara bersamaan, sistem membuat blok cache C berdasarkan konten baru: [Persona Sistem] + [Basis Pengetahuan Produk X] untuk digunakan di masa mendatang.

Dengan menambahkan beberapa penanda cache, sistem masih dapat mengenai cache meskipun beberapa bagian berubah.

Billing

Cache eksplisit hanya memengaruhi metode penagihan untuk token input. Aturannya adalah sebagai berikut:

• Pembuatan cache: Konten cache baru dikenakan biaya sebesar 125% dari harga input standar. Jika konten cache permintaan baru mencakup cache yang ada sebagai awalan, hanya bagian baru yang dikenakan biaya. Ini dihitung sebagai jumlah token cache baru dikurangi jumlah token cache yang ada.

  Sebagai contoh, jika ada cache A yang ada dengan 1.200 token, dan permintaan baru perlu menyimpan konten AB sebanyak 1.500 token, 1.200 token pertama dikenakan biaya sebagai hit cache (10% dari harga standar), dan 300 token baru dikenakan biaya untuk pembuatan cache (125% dari harga standar).

  Lihat jumlah token yang digunakan untuk pembuatan cache di parameter cache_creation_input_tokens.

• Hit cache: Ditagih dengan harga 10% dari harga input standar.

  Lihat jumlah token yang disimpan dalam cache di parameter cached_tokens.

• Token lainnya: Token yang tidak terkena dan untuk mana cache tidak dibuat dikenakan biaya pada harga standar.

Cacheable content

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

• Pesan sistem

• Pesan pengguna

• Pesan asisten

• Pesan alat (hasil setelah eksekusi alat)

Jika permintaan mencakup parameter tools, menambahkan penanda cache dalam messages juga menyimpan informasi deskripsi alat.

Mengambil pesan sistem sebagai contoh, Anda dapat mengubah bidang content menjadi format array dan menambahkan bidang cache_control:

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

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

Batasan

• Panjang prompt minimum adalah 1.024 token.

• Cache menggunakan strategi pencocokan awalan mundur. Sistem secara otomatis memeriksa 20 blok konten terakhir. Hit cache tidak terjadi jika konten yang akan dicocokkan dipisahkan dari pesan yang berisi penanda cache_control oleh lebih dari 20 blok konten.

• Hanya mendukung pengaturan type ke ephemeral. Ini memberikan periode validitas selama 5 menit.

• Anda dapat menambahkan hingga 4 penanda cache dalam satu permintaan.

  Jika jumlah penanda cache lebih dari 4, hanya 4 terakhir yang berlaku.

Contoh penggunaan

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Berikut adalah base_url untuk internasional (Singapura). Base_url untuk daratan Tiongkok (Beijing) adalah https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

# Simulasi konten repositori kode
long_text_content = "<Kode Anda Di Sini>" * 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 untuk membuat cache dari awal prompt hingga akhir konten ini (konten repositori kode simulasi).
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        {
            "role": "user",
            "content": user_input,
        },
    ]
    completion = client.chat.completions.create(
        # Pilih model yang mendukung cache eksplisit
        model="qwen3-coder-plus",
        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"Token cache dibuat pada permintaan pertama: {created_cache_tokens}")
hit_cached_tokens = first_completion.usage.prompt_tokens_details.cached_tokens
print(f"Token cache terkena hit pada permintaan pertama: {hit_cached_tokens}")
print(f"Token tidak terkena hit atau dibuat dalam cache pada permintaan pertama: {first_completion.usage.prompt_tokens-created_cache_tokens-hit_cached_tokens}")
print("=" * 20)
# Permintaan kedua, konten kode sama, hanya pertanyaan yang berubah
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"Token cache dibuat pada permintaan kedua: {created_cache_tokens}")
hit_cached_tokens = second_completion.usage.prompt_tokens_details.cached_tokens
print(f"Token cache terkena hit pada permintaan kedua: {hit_cached_tokens}")
print(f"Token tidak terkena hit atau dibuat dalam cache pada permintaan kedua: {second_completion.usage.prompt_tokens-created_cache_tokens-hit_cached_tokens}")

Token cache dibuat pada permintaan pertama: 1605
Token cache terkena hit pada permintaan pertama: 0
Token tidak terkena hit atau dibuat dalam cache pada permintaan pertama: 13
====================
Token cache dibuat pada permintaan kedua: 0
Token cache terkena hit pada permintaan kedua: 1605
Token tidak terkena hit atau dibuat dalam cache pada permintaan kedua: 15

from openai import OpenAI
import os
  
client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Berikut adalah base_url untuk internasional (Singapura). Base_url untuk daratan Tiongkok (Beijing) adalah https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.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-coder-plus",
        messages=messages,
    )
    return completion

while True:
    user_input = input("Silakan masukkan:")
    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"[Informasi Cache] Token cache dibuat: {created_cache_tokens}")
    print(f"[Informasi Cache] Token cache terkena hit: {hit_cached_tokens}")
    print(f"[Informasi Cache] Token tidak terkena hit atau dibuat dalam cache: {uncached_tokens}")

FAQ