Skip to main content
文本產生

上下文緩衝（Context Cache）

調用大模型時，不同推理請求可能出現輸入內容的重疊（例如多輪對話或對同一本書的多次提問）。上下文緩衝（Context Cache）技術可以緩衝這些請求的公用首碼，減少推理時的重複計算。這能提升響應速度，並在不影響回複效果的前提下降低您的使用成本。

為滿足不同情境的需求，上下文緩衝提供兩種工作模式，可以根據對便捷性、確定性及成本的需求進行選擇：
  • 顯式緩衝：需要主動開啟的緩衝模式。需要主動為指定內容建立緩衝，以在有效期間（5分鐘）內實現確定性命中。除了輸入 Token 計費，用於建立緩衝的 Token 通常按輸入 Token 標準單價的 125% 計費，後續命中通常僅需支付 10% 的費用，具體價格見如何計費。
  • 隱式緩衝：此為自動模式，無需額外配置，且無法關閉，適合追求便捷的通用情境。系統會自動識別請求內容的公用首碼並進行緩衝，但緩衝命中率不確定。對命中緩衝的部分，通常按輸入 Token 標準單價的 20% 計費，具體價格見如何計費。

專案

顯式緩衝

隱式緩衝

是否影響回複效果

不影響

不影響

用於建立緩衝Token計費

通常為輸入 Token 單價的125%

輸入 Token 單價的100%

命中緩衝的輸入 Token 計費

通常為輸入 Token 單價的10%（詳見計費說明）

通常為輸入 Token 單價的20%（詳見計費說明）

緩衝最少 Token 數

1024

256

緩衝有效期間

5分鐘（命中後重設）

不確定，系統會定期清理長期未使用的快取資料

顯式緩衝、隱式緩衝兩者互斥，單個請求只能應用其中一種模式。
預置吞吐（PTU）部署同樣支援上下文緩衝。命中緩衝時，PTU 額度消耗按緩衝折扣係數折算。詳見預置吞吐長輸入與緩衝。
本文內容適用 OpenAI Chat Completions 、 DashScope 與 Anthropic 相容介面。使用 Responses API 可通過 Session 緩衝降低推理延遲與成本，詳情參考Session 緩衝。

顯式緩衝

與隱式緩衝相比，顯式緩衝需要顯式建立並承擔相應開銷，但能實現更高的快取命中率和更低的訪問延遲。

使用方式

在 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）建立新緩衝塊。

支援的模型

  • 新加坡
  • 美國（維吉尼亞）
  • 華北2（北京）
  • 德國（法蘭克福）
  • 中國香港
  • 日本（東京）
以下模型均為國際部署範圍。
千問 Max：qwen3.8-max、qwen3.7-max、qwen3.7-max-2026-05-20、qwen3.7-max-2026-06-08、qwen3.6-max-preview、qwen3-max千問開源：qwen3.8-2.4t-a95b、qwen3.8-27b千問 Plus：qwen3.7-plus、qwen3.7-plus-2026-05-26、qwen3.6-plus、qwen3.5-plus、qwen3.5-plus-2026-04-20、qwen-plus千問 Flash：qwen3.8-flash、qwen3.7-flash、qwen3.7-flash-2026-07-15、qwen3.6-flash、qwen3.5-flash、qwen-flash千問 Coder：qwen3-coder-plus、qwen3-coder-flash千問 VL：qwen3-vl-plus、qwen3-vl-flashDeepSeek：deepseek-v3.2Kimi：kimi-k2.7-code

快速開始

以下樣本展示了在 OpenAI 相容、DashScope 和 Anthropic 相容協議中，緩衝塊的建立與命中機制。
  • OpenAI 相容
  • DashScope
  • Anthropic 相容
from openai import OpenAI
import os

client = OpenAI(
    # 若沒有配置環境變數，請將下行替換為：api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 如果使用北京地區的模型，需要將base_url替換為：https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.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.8-max",
        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}")
類比的代碼倉庫內容通過添加 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 按原價計費。
  • 例外：qwen3.8-max、qwen3.8-flash、qwen3.8-2.4t-a95b 的顯式快取命中價格不是標準輸入單價的 10%，具體價格請參見百鍊控制台（緩衝建立價格仍為標準單價的 125%）。

可緩衝內容

僅 messages 數組中的以下訊息類型支援添加快取標籤：
  • 系統訊息（System Message）
    若請求包含 tools 參數（Function Calling 情境），工具定義會作為系統訊息的一部分參與緩衝計算。工具定義不支援獨立緩衝，在工具定義中添加快取標籤會被忽略，快取標籤只能添加在 messages 的 content 中。
  • 使用者訊息（User Message）
    使用qwen3-vl-plus模型建立緩衝時，cache_control標記可放置在多模態內容或文本之後，其位置不影響緩衝整個使用者訊息的效果。
  • 助手訊息（Assistant Message）
  • 工具訊息（Tool Message，即工具執行後的結果）
以系統訊息為例，需將 content 欄位改為數組形式，並添加 cache_control 欄位： 
{
  "role": "system",
  "content": [
    {
      "type": "text",
      "text": "<指定的提示詞>",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}
此結構同樣適用於 messages 數組中的其他訊息類型。

緩衝限制

  • 最小可緩衝提示詞長度為 1024Token。
  • 緩衝採用從後向前的首碼匹配策略，系統會自動檢查最近的 20 個 content 塊。若待匹配內容與帶有 cache_control 標記的訊息之間間隔超過 20 個 content 塊，則無法命中緩衝。
  • 僅支援將 type 設定為 ephemeral，有效期間為 5 分鐘。
  • 單次請求最多可添加 4 個快取標籤。
    若快取標籤個數大於4，則最後四個快取標籤生效。

提高 Function Calling 快取命中率

由於工具定義會被序列化為 JSON 字串參與緩衝計算，請確保每次請求的工具定義完全一致，以避免緩衝失效。具體需注意：
  • 工具列表順序一致：tools 數組中各工具的排列順序需保持一致；
  • 欄位順序一致：同一個 tool 的 JSON 欄位順序需保持一致；
  • 欄位結構一致：不要遺漏或新增欄位，即使該欄位為空白或可選。

並行工具調用情境下的訊息結構最佳化

在並行工具調用情境下，模型會一次返回多個 tool_calls，需逐一執行這些工具並將結果回傳。如果將每個工具結果作為獨立的 tool 訊息傳入，多條連續同角色訊息會在訊息數組中各自佔據一個 content 塊位置。當待匹配內容（如系統訊息上的快取標籤）與最後一條 tool 訊息之間的 content 塊數量超過 20，緩衝將無法命中。 最佳化方案：在發送請求前，將連續同角色的 tool 訊息預先合并為一條訊息 + 多個 content 塊，減少訊息數組中的塊層級，降低超出 20 塊回溯視窗的風險。 合并前（分開傳，不推薦） 每個工具結果單獨一條 tool 訊息，多條訊息分別佔據獨立的 content 塊位置： 

# 並行工具調用後，逐條回傳結果（不推薦）
# 若工具數量較多，連續tool訊息可能使快取標籤超出20塊回溯範圍
messages.extend([
    {
        "role": "tool",
        "tool_call_id": "call_abc123",
        "content": "北京當前氣溫：25°C，晴"
    },
    {
        "role": "tool",
        "tool_call_id": "call_def456",
        "content": "目前時間：2024-01-15 14:30:00"
    },
    {
        "role": "tool",
        "tool_call_id": "call_ghi789",
        "content": "1 USD = 7.24 CNY"
    }
])
合并後（合并傳，推薦） 將所有工具結果合并為一條訊息 + 多個 content 塊，並在最後一個 content 塊添加 cache_control 標記： 

# 並行工具調用後，合并回傳結果（推薦）
# 將所有tool結果收集為單條訊息的content塊，減少訊息總量
tool_results = []
for tool_call in response.choices[0].message.tool_calls:
    # 執行各工具，擷取返回結果
    result = execute_tool(tool_call.function.name, tool_call.function.arguments)
    tool_results.append({
        "type": "text",
        "text": result,
        "tool_call_id": tool_call.id
    })

# 在最後一個content塊添加cache_control標記（穩定位置）
if tool_results:
    tool_results[-1]["cache_control"] = {"type": "ephemeral"}

# 合并為單條訊息追加到訊息數組
messages.append({
    "role": "tool",
    "content": tool_results
})
在訊息數組的其他穩定位置（如系統訊息末尾）可設定額外的 cache_control 標記，單次請求最多支援 4 個標記，合理分布可進一步提升快取命中率。

使用樣本 

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為新加坡地區URL，調用時請將WorkspaceId替換為真實的業務空間ID，各地區的URL不同。
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.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.8-max",
        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
系統為保證模型效果，會追加少量內部Token，這部分Token按標準輸入價格計費，請參見常見問題。
在使用 Function Calling 情境下緩衝系統訊息時，tools 參數會作為系統訊息的一部分參與緩衝。需確保每次請求的工具定義完全一致（包括工具順序、欄位順序、欄位結構），並在 messages 的最後一個 content 上添加 cache_control 標記。以下為完整流程：第一次請求建立緩衝，第二次請求命中緩衝。
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",
)

# 類比的代碼倉庫內容，確保超過顯式緩衝最小 1024 Token 閾值
long_text_content = "<Your Code Here>" * 400

# 工具定義：確保每次請求完全一致（工具順序、欄位順序、欄位結構）
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "查詢指定城市的當前天氣資訊",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "城市名稱，如北京、上海、紐約等"
                    },
                    "unit": {
                        "type": "string",
                        "description": "溫度單位，celsius（攝氏度）或 fahrenheit（華氏度），預設為 celsius",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["city"],
                "additionalProperties": False
            },
            "strict": True
        }
    },
    {
        "type": "function",
        "function": {
            "name": "get_current_time",
            "description": "查詢指定時區的當前日期和時間",
            "parameters": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "IANA 時區名稱，如 Asia/Shanghai、America/New_York 等，預設為 Asia/Shanghai"
                    }
                },
                "required": [],
                "additionalProperties": False
            },
            "strict": True
        }
    },
    {
        "type": "function",
        "function": {
            "name": "convert_currency",
            "description": "按照即時匯率進行貨幣金額的單位轉換",
            "parameters": {
                "type": "object",
                "properties": {
                    "from_currency": {
                        "type": "string",
                        "description": "源貨幣的 ISO 4217 代碼，如 CNY、USD、EUR 等"
                    },
                    "to_currency": {
                        "type": "string",
                        "description": "目標貨幣的 ISO 4217 代碼"
                    },
                    "amount": {
                        "type": "number",
                        "description": "需要轉換的金額"
                    }
                },
                "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,
                        # 在此處放置 cache_control 標記，將建立從 messages 數組的開頭到當前 content 所在位置的所有內容作為緩衝塊。
                        # cache_control 只能加在 messages 的 content 上，不能加在 tools 上
                        "cache_control": {"type": "ephemeral"},
                    }
                ],
            }
        ]

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

    completion = client.chat.completions.create(
        # 選擇支援顯式緩衝的模型
        model="qwen3.7-plus",
        messages=messages,
        tools=tools,
        # 關閉深度思考模式
        extra_body={"enable_thinking": False},
    )
    return completion

# 第一次請求：建立緩衝
print("=== 第一次請求（建立緩衝）===")
first_completion = get_completion("北京現在天氣怎麼樣？")
usage = first_completion.usage
print(f"Prompt Tokens: {usage.prompt_tokens}")
print(f"建立緩衝 Token: {usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"命中緩衝 Token: {usage.prompt_tokens_details.cached_tokens}")
print(f"模型選擇了工具: {[t.function.name for t in first_completion.choices[0].message.tool_calls or []]}")
print()

# 第二次請求：相同 system message，只修改提問內容，命中緩衝
print("=== 第二次請求（命中緩衝）===")
messages = [
    {
        "role": "system",
        "content": [
            {
                "type": "text",
                "text": long_text_content,
                "cache_control": {"type": "ephemeral"},
            }
        ],
    }
]
second_completion = get_completion("上海現在天氣怎麼樣？", messages=messages)
usage = second_completion.usage
print(f"Prompt Tokens: {usage.prompt_tokens}")
print(f"建立緩衝 Token: {usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"命中緩衝 Token: {usage.prompt_tokens_details.cached_tokens}")
print(f"模型選擇了工具: {[t.function.name for t in second_completion.choices[0].message.tool_calls or []]}")
運行代碼得到類似如下輸出：
=== 第一次請求（建立緩衝）===
 Prompt Tokens: 2174
 建立緩衝 Token: 2156
 命中緩衝 Token: 0
 模型選擇了工具: ['get_weather']

 === 第二次請求（命中緩衝）===
 Prompt Tokens: 2174
 建立緩衝 Token: 0
 命中緩衝 Token: 2156
 模型選擇了工具: ['get_weather']
在日常聊天的多輪對話情境，可將每一次請求的 messages 數組中最後一個 content 添加快取標籤。從第二輪對話開始，每次請求都將命中並重新整理前一輪對話建立的緩衝塊，且建立新的緩衝塊。
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為新加坡地區URL，調用時請將WorkspaceId替換為真實的業務空間ID，各地區的URL不同。
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.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.8-max",
        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}")
運行以上代碼，輸入問題與大模型溝通，每次提問都會命中前一輪建立的緩衝塊。

隱式緩衝

支援的模型

  • 新加坡
  • 華北2（北京）
  • 美國（維吉尼亞）
  • 德國（法蘭克福）
  • 中國香港
  • 日本（東京）
以下模型均為國際部署範圍。
  • 文本產生模型
    • 千問 Max：qwen3.8-max、qwen3.7-max、qwen3.7-max-2026-05-20、qwen3.7-max-2026-06-08、qwen3-max、qwen3-max-preview、qwen-max
    • 千問 Plus：qwen3.7-plus、qwen3.7-plus-2026-05-26、qwen-plus
    • 千問 Flash：qwen3.8-flash、qwen3.7-flash、qwen3.7-flash-2026-07-15、qwen-flash
    • 千問 Turbo：qwen-turbo
    • 千問 Coder：qwen3-coder-plus、qwen3-coder-flash
    • 千問開源：qwen3.8-2.4t-a95b、qwen3.8-27b
    • DeepSeek：deepseek-v4-pro、deepseek-v4-flash、deepseek-v3.2
    • GLM（阿里雲百鍊部署）：glm-5.1
    • Kimi（阿里雲百鍊部署）：kimi-k3、kimi-k2.7-code
    • GLM（智譜部署）：ZHIPU/GLM-5.3、ZHIPU/GLM-5.2
  • 視覺理解模型
    • 千問 VL：qwen3-vl-plus、qwen3-vl-flash、qwen-vl-max、qwen-vl-plus

工作方式

向支援隱式緩衝的模型發送請求時，該功能會自動開啟。系統的工作方式如下：
  1. 尋找：收到請求後，系統基於首碼匹配原則，檢查緩衝中是否存在請求中 messages 數組內容的公用首碼。
  2. 判斷：
    • 若命中緩衝，系統直接使用緩衝結果進行後續部分的推理。
    • 若未命中，系統按常規處理請求，並將本次提示詞的首碼存入緩衝，以備後續請求使用。
系統會定期清理長期未使用的快取資料。上下文快取命中機率並非100%，即使請求上下文完全一致，仍可能未命中，具體命中機率由系統判定。
Qwen3.7系列模型觸發隱式緩衝的最少 Token 數約為2000，其他模型為256。

提升命中緩衝的機率

隱式緩衝的命中邏輯是判斷不同請求的首碼是否存在重複內容。為提高命中機率，請將重複內容置於提示詞開頭，差異內容置於末尾。
  • 文本模型：假設系統已緩衝"ABCD"，則請求"ABE"可能命中"AB"部分，而請求"BCD"則無法命中。
  • 視覺理解模型：
    • 對同一映像或視頻進行多次提問：將映像或視頻放在文本資訊前會提高命中機率。
    • 對不同映像或視頻提問同一問題：將文本資訊放在映像或視頻前面會提高命中機率。

如何計費

開啟隱式緩衝模式無需額外付費。 當請求命中緩衝時，命中的輸入 Token 按 cached_token 計費，折扣比例因模型而有差異；未被命中的輸入 Token 按標準 input_token 計費。輸出 Token 仍按原價計費。
  • 除 deepseek-v4-pro、qwen3.8-max、qwen3.8-2.4t-a95b 外的模型：cached_token 單價為 input_token 單價的 20%
  • deepseek-v4-pro：cached_token 單價不是 input_token 單價的 20%，具體價格請參見百鍊控制台
  • qwen3.8-max、qwen3.8-flash、qwen3.8-2.4t-a95b：cached_token 單價不是 input_token 單價的 20%，具體價格請參見百鍊控制台
  • GLM（阿里雲百鍊部署）：glm-5.2、glm-5.2-fast-preview 為 25%，其餘glm系列模型均為 20%
樣本：某請求包含 10,000 個輸入 Token，其中 5,000 個命中緩衝。費用計算如下：
  • 未命中 Token (5,000)：按 100% 單價計費
  • 命中 Token (5,000)：按 20% 單價計費
總輸入費用相當於無緩衝模式的 60%：(50% × 100%) + (50% × 20%) = 60%。
image.png
可從返回結果的cached_tokens屬性擷取命中緩衝的 Token 數。
OpenAI相容-Batch（檔案輸入）方式調用無法享受緩衝折扣。

命中緩衝的案例

  • 文本產生模型
  • 視覺理解模型
  • OpenAI相容
  • DashScope
  • Anthropic 相容
當您使用 OpenAI 相容的方式調用模型並觸發了隱式緩衝後，可以得到如下的返回結果，在usage.prompt_tokens_details.cached_tokens可以查看命中緩衝的 Token 數（該數值為usage.prompt_tokens的一部分）。
{
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "我是阿里雲開發的一款超大規模語言模型，我叫千問。"
            },
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null
        }
    ],
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 3019,
        "completion_tokens": 104,
        "total_tokens": 3123,
        "prompt_tokens_details": {
            "cached_tokens": 2048
        }
    },
    "created": 1735120033,
    "system_fingerprint": null,
    "model": "qwen-plus",
    "id": "chatcmpl-6ada9ed2-7f33-9de2-8bb0-78bd4035025a"
}

典型情境

如果您的不同請求有著相同的首碼資訊，上下文緩衝可以有效提升這些請求的推理速度，降低推理成本與首包延遲。以下是幾個典型的應用情境：
  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```程式碼片段"}
        ]
    }
]

常見問題

Q：上下文緩衝的有效期間是多久（可以保留多長時間）？

A：上下文緩衝的有效期間取決於緩衝類型：
  • 顯式緩衝：有效期間為 5 分鐘，且每次命中後會重新計時 5 分鐘；若超過 5 分鐘未被命中，系統將自動清理該緩衝塊。
  • 隱式緩衝：由系統自動管理，無固定有效期間，系統會定期清理長期未使用的快取資料。
此處的有效期間指通過 API 呼叫時上下文緩衝的生命週期，與控制台「模型體驗 / 模型調試」頁面中展示的歷史對話記錄不是同一功能。

Q：如何關閉隱式緩衝？

A：無法關閉。隱式緩衝對所有適用模型請求開啟的前提是對回複效果沒有影響，且在命中緩衝時降低使用成本，提升響應速度。

Q：為什麼建立顯式緩衝後沒有命中？

A：有以下可能原因：
  • 建立後 5 分鐘內未被命中，超過有效期間系統將清理該緩衝塊；
  • 最後一個content與已存在的緩衝塊的間隔大於20個content塊時，不會命中緩衝，建議建立新的緩衝塊。

Q：顯式快取命中後，是否會重設有效期間？

A：是的，每次命中都會將該緩衝塊的有效期間重設為5分鐘。

Q：不同帳號之間的顯式緩衝是否會共用？

A：不會。無論是隱式緩衝還是顯式緩衝，資料都在帳號層級隔離，不會共用。

Q：相同帳號使用不同模型顯式緩衝是否會共用？

A：不會。快取資料存在模型間隔離，不會共用。

Q：為什麼usage的input_tokens不等於cache_creation_input_tokens和cached_tokens的總和？

A：為了確保模型輸出效果，後端服務會在使用者提供的提示詞之後追加少量 Token（通常在10以內），這些 Token 在 cache_control 標記之後，因此不會被計入緩衝的建立或讀取，但會計入總的 input_tokens。

Q：如何查看一段時間內（按天/按周）的快取命中 Token 數量？

A：可通過以下方式擷取指定時間段內的快取命中資料：
  • 模型監控：在百鍊控制台「模型監控」頁面，選擇目標模型和時間範圍，查看 cache_tokens 指標（支援按分鐘/按小時精度統計）。
  • 賬單明細：在百鍊控制台「賬單詳情」頁面匯出賬單明細，按計費類型篩選"快取命中"（cache）相關記錄，按日期分組匯總，可擷取每日的快取命中 Token 計量資料。詳細操作請參見賬單查詢與成本管理。
開始使用
Token Plan
模型體驗
接入用戶端/開發工具
模型推理
模型調優
模型部署
模型評測
用量統計與效能監控
資產中心
安全合規
實踐教程
服務支援
產品動態