Alibaba Cloud Model Studio：上下文緩衝（Context Cache）

支援的模型

工作方式

向支援隱式緩衝的模型發送請求時，該功能會自動開啟。系統的工作方式如下：

1. 尋找：收到請求後，系統基於首碼匹配原則，檢查緩衝中是否存在請求中 messages 數組內容的公用首碼。

2. 判斷：

   • 若命中緩衝，系統直接使用緩衝結果進行後續部分的推理。

   • 若未命中，系統按常規處理請求，並將本次提示詞的首碼存入緩衝，以備後續請求使用。

系統會定期清理長期未使用的快取資料。上下文快取命中機率並非100%，即使請求上下文完全一致，仍可能未命中，具體命中機率由系統判定。

提升命中緩衝的機率

隱式緩衝的命中邏輯是判斷不同請求的首碼是否存在重複內容。為提高命中機率，請將重複內容置於提示詞開頭，差異內容置於末尾。

• 文本模型：假設系統已緩衝"ABCD"，則請求"ABE"可能命中"AB"部分，而請求"BCD"則無法命中。

• 視覺理解模型：

  • 對同一映像或視頻進行多次提問：將映像或視頻放在文本資訊前會提高命中機率。

  • 對不同映像或視頻提問同一問題：將文本資訊放在映像或視頻前面會提高命中機率。

如何計費

開啟隱式緩衝模式無需額外付費。

當請求命中緩衝時，命中的輸入 Token 按 cached_token 計費（單價為input_token單價的20%）；未被命中的輸入 Token 按標準 input_token計費。輸出 Token 仍按原價計費。

樣本：某請求包含 10,000 個輸入 Token，其中 5,000 個命中緩衝。費用計算如下：

• 未命中 Token (5,000)：按 100% 單價計費

• 命中 Token (5,000)：按 20% 單價計費

總輸入費用相當於無緩衝模式的 60%：(50% × 100%) + (50% × 20%) = 60%。

可從返回結果的cached_tokens屬性擷取命中緩衝的 Token 數。

OpenAI相容-Batch方式調用無法享受緩衝折扣。

典型情境

如果您的不同請求有著相同的首碼資訊，上下文緩衝可以有效提升這些請求的推理速度，降低推理成本與首包延遲。以下是幾個典型的應用情境：

1. 基於長文本的問答

   適用於需要針對固定的長文本（如小說、教材、法律檔案等）發送多次請求的業務情境。

   第一次請求的訊息數組

   messages = [{"role": "system","content": "你是一個語文老師，你可以協助學生進行閱讀理解。"},
             {"role": "user","content": "<文章內容> 這篇課文表達了作者怎樣的思想感情？"}]

   之後請求的訊息數組

   messages = [{"role": "system","content": "你是一個語文老師，你可以協助學生進行閱讀理解。"},
             {"role": "user","content": "<文章內容> 請賞析這篇課文的第三自然段。"}]

   雖然提問的問題不同，但都基於同一篇文章。相同的系統提示和文章內容構成了大量重複的首碼資訊，有較大機率命中緩衝。

2. 代碼自動補全

   在代碼自動補全情境，大模型會結合上下文中存在的代碼進行代碼自動補全。隨著使用者的持續編碼，代碼的首碼部分會保持不變。上下文緩衝可以緩衝之前的代碼，提升補全速度。

3. 多輪對話

   實現多輪對話需要將每一輪的對話資訊添加到 messages 數組中，因此每輪對話的請求都會存在與前輪對話首碼相同的情況，有較高機率命中緩衝。

   第一輪對話的訊息數組

   messages=[{"role": "system","content": "You are a helpful assistant."},
             {"role": "user","content": "你是誰？"}]

   第二輪對話的訊息數組

   messages=[{"role": "system","content": "You are a helpful assistant."},
             {"role": "user","content": "你是誰？"},
             {"role": "assistant","content": "我是由阿里雲開發的通義千問。"},
             {"role": "user","content": "你能幹什嗎？"}]

   隨著對話輪數的增加，緩衝帶來的推理速度優勢與成本優勢會更明顯。

4. 角色扮演或 Few Shot

   在角色扮演或 Few-shot 學習的情境中，您通常需要在提示詞中加入大量資訊來指引大模型的輸出格式，這樣不同的請求之間會有大量重複的首碼資訊。

   以讓大模型扮演營銷專家為例，System prompt包含有大量文本資訊，以下是兩次請求的訊息樣本：

   system_prompt = """你是一位經驗豐富的營銷專家。請針對不同產品提供詳細的營銷建議，格式如下：
   
   1. 目標受眾：xxx
   
   2. 主要賣點：xxx
   
   3. 營銷渠道：xxx
   ...
   12. 長期發展策略：xxx
   
   請確保你的建議具體、可操作，並與產品特性高度相關。"""
   
   # 第一次請求的user message 提問關於智能手錶
   messages_1=[
     {"role": "system", "content": system_prompt},
     {"role": "user", "content": "請為一款新上市的智能手錶提供營銷建議。"}
   ]
   
   # 第二次請求的user message 提問關於膝上型電腦，由於system_prompt相同，有較大機率命中 Cache
   messages_2=[
     {"role": "system", "content": system_prompt},
     {"role": "user", "content": "請為一款新上市的膝上型電腦提供營銷建議。"}
   ]

   使用上下文緩衝後，即使使用者頻繁更換詢問的產品類型（如從智能手錶到膝上型電腦），系統也可以在觸發緩衝後快速響應。

5. 視頻理解

   在視頻理解情境中，如果對同一個視頻提問多次，將video放在text前會提高命中緩衝的機率；如果對不同的視頻提問相同的問題，則將text放在video前面，會提高命中緩衝的機率。以下是對同一個視頻請求兩次的訊息樣本：

   # 第一次請求的user message 提問這段視頻的內容
   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": "這段視頻的內容是什麼?"}
           ]
       }
   ]
   
   # 第二次請求的user message 提問關於視頻時間戳記相關的問題，由於基於同一個視頻進行提問，將video放在text前面，有較大機率命中 Cache
   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": "請你描述下視頻中的一系列活動事件，以JSON格式輸出開始時間（start_time）、結束時間（end_time）、事件（event），不要輸出```json```程式碼片段"}
           ]
       }
   ]

使用方式

在 messages 中加入"cache_control": {"type": "ephemeral"}標記，系統將以每個cache_control標記位置為終點，向前回溯最多 20 個 content 塊，嘗試命中緩衝。

單次請求最多支援加入4 個快取標籤。

• 未命中緩衝

  系統將從messages數組開頭到 cache_control標記之間的內容建立為新的緩衝塊，有效期間為 5 分鐘。

  緩衝建立發生在模型響應之後，建議在建立請求完成後再嘗試命中該緩衝。

  緩衝塊的內容最少為 1024 Token。

• 命中緩衝

  選取最長的匹配首碼作為命中的緩衝塊，並將該緩衝塊的有效期間重設為5分鐘。

以下樣本說明其使用方式：

1. 發起第一個請求：發送包含超 1024 Token 文本 A 的系統訊息，並加入快取標籤：

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

   系統將建立首個緩衝塊，記為 A 緩衝塊。

2. 發起第二個請求：發送以下結構的請求：

   [
       {"role": "system", "content": A},
       <其他 message>
       {"role": "user","content": [{"type": "text", "text": B, "cache_control": {"type": "ephemeral"}}]}
   ]

   • 若“其他message”不超過 20 條，則命中 A 緩衝塊，並將其有效期間重設為 5 分鐘；同時，系統會基於 A、其他message和 B 建立一個新的緩衝塊。

   • 若“其他message”超過 20 條，則無法命中 A 緩衝塊，系統仍會基於完整上下文（A + 其他message + B）建立新緩衝塊。

支援的模型

通義千問Max：qwen3-max

通義千問Plus：qwen-plus

通義千問Flash：qwen-flash

通義千問Coder：qwen3-coder-plus、qwen3-coder-flash

以上所列模型在中國內地版和國際版均支援顯式緩衝功能

暫不支援快照與 latest 模型。

通義千問VL：qwen3-vl-plus

qwen3-vl-plus 模型僅在中國內地版支援顯式緩衝功能。

DeepSeek-阿里雲百鍊：deepseek-v3.2

deepseek-v3.2 模型僅在中國內地版支援顯式緩衝功能。

快速開始

以下樣本展示了在 OpenAI 相容介面和 DashScope 協議中，緩衝塊的建立與命中機制。

from openai import OpenAI
import os

client = OpenAI(
    # 若沒有配置環境變數，請將下行替換為：api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 如果使用北京地區的模型，需要將base_url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

# 類比的代碼倉庫內容，最小可緩衝提示詞長度為 1024 Token
long_text_content = "<Your Code Here>" * 400

# 發起請求的函數
def get_completion(user_input):
    messages = [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": long_text_content,
                    # 在此處放置 cache_control 標記，將建立從 messages 數組的開頭到當前 content 所在位置的所有內容作為緩衝塊。
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        # 每次的提問內容不同
        {
            "role": "user",
            "content": user_input,
        },
    ]
    completion = client.chat.completions.create(
        # 選擇支援顯式緩衝的模型
        model="qwen3-coder-plus",
        messages=messages,
    )
    return completion

# 第一次請求
first_completion = get_completion("這段代碼的內容是什麼")
print(f"第一次請求建立緩衝 Token：{first_completion.usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"第一次請求命中緩衝 Token：{first_completion.usage.prompt_tokens_details.cached_tokens}")
print("=" * 20)
# 第二次請求，代碼內容一致，只修改了提問問題
second_completion = get_completion("這段代碼可以怎麼最佳化")
print(f"第二次請求建立緩衝 Token：{second_completion.usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"第二次請求命中緩衝 Token：{second_completion.usage.prompt_tokens_details.cached_tokens}")

import os
from dashscope import Generation
# 若使用北京地區的模型，需將base_url替換為：https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = "https://dashscope-intl.aliyuncs.com/api/v1"

# 類比的代碼倉庫內容，最小可緩衝提示詞長度為 1024 Token
long_text_content = "<Your Code Here>" * 400

# 發起請求的函數
def get_completion(user_input):
    messages = [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": long_text_content,
                    # 在此處放置 cache_control 標記，將建立從 messages 數組的開頭到當前 content 所在位置的所有內容作為緩衝塊。
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        # 每次的提問內容不同
        {
            "role": "user",
            "content": user_input,
        },
    ]
    response = Generation.call(
        # 若沒有配置環境變數，請用阿里雲百鍊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_completion = get_completion("這段代碼的內容是什麼")
print(f"第一次請求建立緩衝 Token：{first_completion.usage.prompt_tokens_details['cache_creation_input_tokens']}")
print(f"第一次請求命中緩衝 Token：{first_completion.usage.prompt_tokens_details['cached_tokens']}")
print("=" * 20)
# 第二次請求，代碼內容一致，只修改了提問問題
second_completion = get_completion("這段代碼可以怎麼最佳化")
print(f"第二次請求建立緩衝 Token：{second_completion.usage.prompt_tokens_details['cache_creation_input_tokens']}")
print(f"第二次請求命中緩衝 Token：{second_completion.usage.prompt_tokens_details['cached_tokens']}")

// 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";
    // 類比代碼倉庫內容（400次重複確保超過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 {
        // 若使用北京地區的模型，需將base_url替換為：https://dashscope.aliyuncs.com/api/v1
        Generation gen = new Generation("http", "https://dashscope-intl.aliyuncs.com/api/v1");

        // 構建帶緩衝控制的系統訊息
        MessageContentText systemContent = MessageContentText.builder()
                .type("text")
                .text(LONG_TEXT_CONTENT)
                .cacheControl(MessageContentText.CacheControl.builder()
                        .type("ephemeral") // 設定緩衝類型
                        .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();

        // 構建請求參數
        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: %d%n", requestLabel, result.getUsage().getPromptTokensDetails().getCacheCreationInputTokens());
        System.out.printf("%s命中緩衝 Token: %d%n", requestLabel, result.getUsage().getPromptTokensDetails().getCachedTokens());
    }

    public static void main(String[] args) {
        try {
            // 第一次請求
            GenerationResult firstResult = getCompletion("這段代碼的內容是什麼");
            printCacheInfo(firstResult, "第一次請求");
            System.out.println(new String(new char[20]).replace('\0', '='));            // 第二次請求
            GenerationResult secondResult = getCompletion("這段代碼可以怎麼最佳化");
            printCacheInfo(secondResult, "第二次請求");
        } catch (NoApiKeyException | ApiException | InputRequiredException e) {
            System.err.println("API調用失敗: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

類比的代碼倉庫內容通過添加 cache_control標記啟用顯式緩衝。後續針對該代碼倉庫的提問請求，系統可複用該緩衝塊，無需重新計算，可獲得比建立緩衝前更快的響應與更低的成本。

第一次請求建立緩衝 Token：1605
第一次請求命中緩衝 Token：0
====================
第二次請求建立緩衝 Token：0
第二次請求命中緩衝 Token：1605

使用多個快取標籤實現精細控制

在複雜情境中，提示詞通常由多個重用頻率不同的部分組成。使用多個快取標籤可實現精細控制。

例如，智能客服的提示詞通常包括：

• 系統人設：高度穩定，幾乎不變。

• 外部知識：半穩定，通過知識庫檢索或工具查詢獲得，可能在連續對話中保持不變。

• 對話歷史：動態增長。

• 當前問題：每次不同。

如果將整個提示詞作為一個整體緩衝，任何微小變化（如外部知識改變）都可能導致無法命中緩衝。

在請求中最多可設定四個快取標籤，為提示詞的不同部分分別建立緩衝塊，從而提升命中率並實現精細控制。

如何計費

顯式緩衝僅影響輸入 Token 的計費方式。規則如下：

• 建立緩衝：新建立的緩衝內容按標準輸入單價的 125% 計費。若新請求的緩衝內容包含已有緩衝作為首碼，則僅對新增部分計費（即新緩衝 Token 數減去已有緩衝 Token 數）。

  例如：若已有 1200 Token 的緩衝 A，新請求需緩衝 1500 Token 的內容 AB，則前 1200 Token 按快取命中計費（標準單價的 10%），新增的 300 Token 按建立緩衝計費（標準單價的 125%）。

  建立緩衝所用的 Token數通過cache_creation_input_tokens 參數查看。

• 命中緩衝：按標準輸入單價的 10% 計費。

  命中緩衝的 Token數通過 cached_tokens 參數查看。

• 其他 Token：未命中且未建立緩衝的 Token 按原價計費。

可緩衝內容

僅 messages 數組中的以下訊息類型支援添加快取標籤：

• 系統訊息（System Message）

• 使用者訊息（User Message）

  使用qwen3-vl-plus模型建立緩衝時，cache_control標記可放置在多模態內容或文本之後，其位置不影響緩衝整個使用者訊息的效果。

• 助手訊息（Assistant Message）

• 工具訊息（Tool Message，即工具執行後的結果）

  若請求包含 tools 參數，在messages中添加快取標籤還會緩衝其中的工具描述資訊。

以系統訊息為例，需將 content 欄位改為數組形式，並添加 cache_control 欄位：

{
  "role": "system",
  "content": [
    {
      "type": "text",
      "text": "<指定的提示詞>",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

此結構同樣適用於 messages 數組中的其他訊息類型。

緩衝限制

• 最小可緩衝提示詞長度為 1024 Token。

• 緩衝採用從後向前的首碼匹配策略，系統會自動檢查最近的 20 個 content 塊。若待匹配內容與帶有 cache_control 標記的訊息之間間隔超過 20 個 content 塊，則無法命中緩衝。

• 僅支援將 type 設定為 ephemeral，有效期間為 5 分鐘。

• 單次請求最多可添加 4 個快取標籤。

  若快取標籤個數大於4，則最後四個快取標籤生效。

使用樣本

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 若使用北京地區的模型，需將base_url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

# 類比的代碼倉庫內容
long_text_content = "<Your Code Here>" * 400

# 發起請求的函數
def get_completion(user_input):
    messages = [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": long_text_content,
                    # 在此處放置 cache_control 標記，將建立從提示詞開始到本content結束位置（即類比的代碼倉庫內容）的緩衝。
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        {
            "role": "user",
            "content": user_input,
        },
    ]
    completion = client.chat.completions.create(
        # 選擇支援顯式緩衝的模型
        model="qwen3-coder-plus",
        messages=messages,
    )
    return completion

# 第一次請求
first_completion = get_completion("這段代碼的內容是什麼")
created_cache_tokens = first_completion.usage.prompt_tokens_details.cache_creation_input_tokens
print(f"第一次請求建立緩衝 Token：{created_cache_tokens}")
hit_cached_tokens = first_completion.usage.prompt_tokens_details.cached_tokens
print(f"第一次請求命中緩衝 Token：{hit_cached_tokens}")
print(f"第一次請求未命中也未建立緩衝的 Token：{first_completion.usage.prompt_tokens-created_cache_tokens-hit_cached_tokens}")
print("=" * 20)
# 第二次請求，代碼內容一致，只修改了提問問題
second_completion = get_completion("這段代碼有哪些可以最佳化的地方")
created_cache_tokens = second_completion.usage.prompt_tokens_details.cache_creation_input_tokens
print(f"第二次請求建立緩衝 Token：{created_cache_tokens}")
hit_cached_tokens = second_completion.usage.prompt_tokens_details.cached_tokens
print(f"第二次請求命中緩衝 Token：{hit_cached_tokens}")
print(f"第二次請求未命中也未建立緩衝的 Token：{second_completion.usage.prompt_tokens-created_cache_tokens-hit_cached_tokens}")

第一次請求建立緩衝 Token：1605
第一次請求命中緩衝 Token：0
第一次請求未命中也未建立緩衝的 Token：13
====================
第二次請求建立緩衝 Token：0
第二次請求命中緩衝 Token：1605
第二次請求未命中也未建立緩衝的 Token：15

from openai import OpenAI
import os
  
client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 若使用北京地區的模型，需將base_url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

system_prompt = "你是說話風趣的人。" * 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("請輸入：")
    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：{created_cache_tokens}")
    print(f"[Cache Info] 命中緩衝 Token：{hit_cached_tokens}")
    print(f"[Cache Info] 未命中也未建立緩衝的 Token：{uncached_tokens}")

常見問題