Skip to main content

顯式緩衝(Qwen4)

僅適用於 Qwen4 系列模型的顯式緩衝。透過自動緩衝或緩衝斷點指定需要重複使用的輸入首碼,並按 5 分鐘或 1 小時設定緩衝有效期間,減少重複計算,降低延遲和輸入成本。

在多輪對話、長文件問答、Agent 等情境中,連續請求往往包含大量相同的開頭內容,例如系統提示詞、工具說明或參考文件。使用顯式緩衝(Qwen4)後,有效期間內的後續請求可以直接讀取這部分內容的緩衝,無需重複計算,從而降低回應延遲和輸入成本。 顯式緩衝透過緩衝斷點指定需要重複使用的內容首碼,命中是確定的:只要首碼完全相同且在有效期間內,後續請求就能讀取緩衝。系統自動識別公用首碼的隱式緩衝不保證命中。 Qwen4 在基礎用法之上提供自動緩衝和緩衝有效期間(TTL)兩項進階用法,詳見進階用法。
本文介紹原有顯式緩衝在 Qwen4 上的版本:內容塊斷點的用法保持不變,並新增自動緩衝與緩衝有效期間(TTL)。與上下文緩衝中兩種緩衝方式的關係:
  • 顯式緩衝:透過緩衝斷點指定輸入首碼,命中確定,即本文介紹的內容。
  • 隱式緩衝:不設定任何緩衝參數時自動識別公用首碼,不保證命中,詳見隱式緩衝。
  • OpenAI 相容介面原有的 cache_control 內容塊標記繼續相容,用法與 prompt_cache_breakpoint 相同,詳見基礎用法。

工作原理

緩衝以斷點為單位建立和讀取。自動緩衝的斷點由系統設定在輸入末尾,緩衝斷點由您在內容塊上標記。每個斷點對應的緩衝首碼是從請求開頭到斷點所在內容塊末尾的全部輸入。 收到請求後,系統以每個斷點為終點,向前尋找最多 20 個內容塊,選取已緩衝的最長相同首碼:
  • 命中緩衝:讀取已緩衝的首碼,並按本次請求的 TTL 續期。
  • 未命中緩衝:從請求開頭到斷點處的內容建立為新的緩衝。若首碼中有部分內容已命中緩衝,僅對新增部分建立緩衝。
緩衝首碼需完全相同才能命中,且僅在同一使用者的請求之間重複使用。將固定不變的內容放在前面、每次變化的內容放在斷點之後,可以提高命中率。 未設定任何緩衝參數時,系統使用隱式緩衝自動識別請求的公用首碼,但不保證命中。需要穩定重複使用指定內容時,請開啟自動緩衝或設定緩衝斷點。

基礎用法

在請求中需要重複使用的內容塊上設定緩衝斷點。系統以該內容塊的末尾作為斷點,把從請求開頭到該處的全部輸入作為緩衝首碼:第一次請求建立緩衝,有效期間內首碼相同的後續請求讀取緩衝。緩衝首碼至少為 1,024 Token。
  • OpenAI 兼容 Chat Completions
  • OpenAI 兼容 Responses
  • Anthropic 相容
在 messages 中需要緩衝的內容塊上新增 prompt_cache_breakpoint,值為 {"mode": "explicit"}。新增斷點的訊息,其 content 需使用陣列形式:
messages=[
  {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": long_text,
        "prompt_cache_breakpoint": {"mode": "explicit"},  # <-- 緩衝斷點
      },
      {"type": "text", "text": "請概括這份文件。"},  # 斷點之後的內容不參與該緩衝
    ],
  }
],
原有的 "cache_control": {"type": "ephemeral"} 內容塊標記繼續相容,用法與 prompt_cache_breakpoint 相同。同一使用者的相同首碼可以在兩種標記之間重複使用緩衝。新接入建議使用 prompt_cache_breakpoint。
同一請求中請只使用 prompt_cache_breakpoint 和 cache_control 中的一種。
以下範例連續傳送兩次請求:第一次請求建立緩衝,第二次請求保持首碼不變、只修改問題,從而讀取緩衝。
Python
import os
from openai import OpenAI

client = OpenAI(
  # 若沒有設定環境變數,請將下行替換為:api_key="sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  # 以下為新加坡地域的 URL,呼叫時請將 WorkspaceId 替換為真實的業務空間 ID,各地域的 URL 不同。
  base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# 需要重複使用的長文件,緩衝首碼最少為 1024 Token
long_text = "<固定的長文件>" * 400

def ask(question):
  completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[
      {
        "role": "user",
        "content": [
          {"type": "text", "text": long_text, "prompt_cache_breakpoint": {"mode": "explicit"}},  # <-- 緩衝斷點
          {"type": "text", "text": question},  # 斷點之後的內容每次可以不同
        ],
      }
    ],
    extra_body={
      "enable_thinking": False,
    },
  )
  return completion.usage.prompt_tokens_details

ask("請概括這份文件。")  # 第一次請求:建立緩衝
details = ask("請列出文件的三個要點。")  # 第二次請求:讀取緩衝
print(f"讀取緩衝 {details.cached_tokens} Token,建立緩衝 {details.cache_write_tokens} Token")
第二次請求的 cached_tokens 為讀取的緩衝量,cache_write_tokens 為本次建立的緩衝量。首碼不變時,cache_write_tokens 為 0。數字為示意,實際取決於文件長度。

使用多個斷點

當提示詞由變化頻率不同的幾部分組成時,可以為每一部分分別設定斷點。例如智慧客服的提示詞通常包括系統人設(幾乎不變)、知識庫檢索結果(隨諮詢主題變化)和對話歷史(持續增長)。在每部分末尾設定斷點後,即使知識庫內容發生變化,系統人設部分仍可命中緩衝。 每個請求最多保留最後 4 個有效斷點,超出的斷點不生效。開啟自動緩衝時,自動斷點佔用其中 1 個。

斷點位置變化時的續期

系統只建立或續期本次請求中的斷點。斷點位置改變後,即使讀取了舊斷點的緩衝,舊斷點的有效期間也不會延長。 例如,在 TTL 不變的情況下,上次請求的斷點位於第 2,048 Token 處,本次請求將斷點移到第 3,072 Token 處且未保留舊斷點。若舊斷點在尋找範圍內且未過期,本次請求讀取前 2,048 Token 的緩衝,並為後續 1,024 Token 建立緩衝;系統只建立或續期第 3,072 Token 處的斷點,第 2,048 Token 處的緩衝不續期。

進階用法

Qwen4 在基礎用法之上提供以下兩項能力,可以組合使用:
  • 自動緩衝:由系統自動在輸入末尾設定斷點,適合多輪對話。
  • 緩衝有效期間(TTL):可選 5 分鐘或 1 小時。

自動緩衝

開啟自動緩衝後,系統自動在每次請求的輸入末尾設定斷點,無需隨對話增長逐輪移動斷點。自動斷點不包含用於開始產生回覆的範本後綴。自動緩衝可以與基礎用法中的緩衝斷點同時使用;若輸入末尾已有手動斷點,不會重複設定。
  • OpenAI 兼容 Chat Completions
  • OpenAI 兼容 Responses
  • Anthropic 相容
在請求頂層設定 prompt_cache_options,並將 mode 設定為 implicit。使用 OpenAI Python SDK 時透過 extra_body 傳入:
completion = client.chat.completions.create(
  model="qwen4-max",
  messages=[{"role": "user", "content": "請概括這份文件:" + long_text}],
  extra_body={
    "enable_thinking": False,
    "prompt_cache_options": {"mode": "implicit"},  # <-- 開啟自動緩衝
  },
)
prompt_cache_options.mode 的取值與對應行為如下:
設定自動斷點緩衝行為
mode 為 implicit設定輸入末尾的自動斷點和手動斷點同時生效
mode 為 explicit,有手動斷點不設定按手動斷點建立或讀取緩衝
mode 為 explicit,無手動斷點不設定使用隱式緩衝
不傳 prompt_cache_options、傳 null 或 {},或只設定 ttl不設定有手動斷點時按手動斷點緩衝,否則使用隱式緩衝
mode 為 implicit 時使用的是自動斷點緩衝,按本文的 TTL 與計費規則處理,與不傳緩衝參數時的隱式緩衝不同。mode 為 explicit 只表示不自動設定斷點,不會關閉隱式緩衝。mode 僅對當前請求生效。
以下完整範例開啟自動緩衝,並連續傳送兩次相同的長文件請求:第一次請求建立緩衝,第二次請求讀取緩衝。
  • OpenAI 兼容 Chat Completions
  • OpenAI 兼容 Responses
  • Anthropic 相容
import os
from openai import OpenAI

client = OpenAI(
  # 若沒有設定環境變數,請將下行替換為:api_key="sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  # 以下為新加坡地域的 URL,呼叫時請將 WorkspaceId 替換為真實的業務空間 ID,各地域的 URL 不同。
  base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# 需要重複使用的長文件,緩衝首碼最少為 1024 Token
long_text = "<固定的長文件>" * 400

def ask():
  completion = client.chat.completions.create(
    model="qwen4-max",
    messages=[{"role": "user", "content": "請概括這份文件:" + long_text}],
    extra_body={
      "enable_thinking": False,
      "prompt_cache_options": {"mode": "implicit"},  # <-- 開啟自動緩衝
    },
  )
  return completion.usage.prompt_tokens_details

for i in range(1, 3):
  details = ask()
  print(f"第 {i} 次請求:讀取緩衝 {details.cached_tokens} Token,建立緩衝 {details.cache_write_tokens} Token")
預期輸出類似如下,具體 Token 數取決於文件長度:
第 1 次請求:讀取緩衝 0 Token,建立緩衝 2048 Token
第 2 次請求:讀取緩衝 2048 Token,建立緩衝 0 Token
第二次請求的輸入與第一次相同,因此讀取了第一次建立的緩衝。

設定緩衝有效期間

緩衝有效期間(TTL)可選 5m(5 分鐘)或 1h(1 小時),預設為 5m。緩衝在有效期間內被命中時會自動續期,續期方式見續期規則。
  • OpenAI 兼容 Chat Completions
  • OpenAI 兼容 Responses
  • Anthropic 相容
在請求頂層的 prompt_cache_options.ttl 中設定,對本次請求的全部斷點生效:
extra_body={
  "prompt_cache_options": {
    "mode": "implicit",
    "ttl": "1h",  # <-- 緩衝有效期間為 1 小時
  },
},
未設定 prompt_cache_options.ttl 時,使用請求中最後一個 cache_control 標記的 ttl;該標記未設定 ttl,或請求中沒有 cache_control 標記時,TTL 為 5m。TTL 只對顯式緩衝生效,設定 ttl 時需同時設定緩衝斷點或開啟自動緩衝。

續期規則

首次請求或緩衝已過期時,按本次請求的 TTL 建立緩衝。命中有效緩衝時,按以下規則續期和計費:
  • 到期時間取較晚值,並保留較高的檔位。 新的到期時間約為「原到期時間」與「本次緩衝處理開始時間 + 本次 TTL」中較晚的一個。例如,12:03 命中 12:05 到期的 5m 緩衝,新的到期時間約為 12:08。又如,5m 請求命中有效的 1h 緩衝時,按 5m 計算續期,但緩衝仍保留 1h 檔位,後續 1h 請求在有效期間內仍按讀取緩衝計費。
  • 從 5m 升級為 1h 時,升級部分按 1h 建立緩衝計費。 1h 請求命中有效的 5m 緩衝時,命中部分按 1h 重新建立,不再計為讀取。若部分首碼已有有效的 1h 緩衝,這部分仍按讀取計費,僅剩餘部分和新增首碼按建立計費。其他情況(5m 請求命中 5m 緩衝、5m 請求命中 1h 緩衝、1h 請求命中 1h 緩衝)的命中部分均按讀取計費。
有效期間從本次緩衝處理開始時計算,不在原到期時間上累加,也不從回覆結束時重新計時。產生回覆的耗時計入有效期間,實際到期時間會預留少量處理時間。 以下範例為對同一份緩衝的連續請求,該緩衝於 12:00 按 1h 建立,原到期時間為 13:00:
請求本次 TTL請求前的到期時間請求後的到期時間(約)計費與檔位
12:20 發起5m13:0013:00讀取緩衝。12:25 早於原到期時間,到期時間不變,既不縮短,也不續到 13:20
12:58 發起5m13:0013:03讀取緩衝。到期時間延長至本次開始後 5 分鐘,仍保留 1h 檔位
13:01 發起1h13:0314:01讀取緩衝。緩衝已是 1h 檔位,不產生升級建立
以上範例基於相同首碼的串行請求。多個請求並發寫入同一緩衝時可能相互覆蓋,不保證保留最晚的到期時間。

查看緩衝用量

回應的 usage 中傳回讀取緩衝和建立緩衝的 Token 數。串流輸出時,OpenAI 相容介面需設定 stream_options 為 {"include_usage": true},從最後一個包含 usage 的資料塊中讀取。
  • OpenAI 兼容 Chat Completions
  • OpenAI 兼容 Responses
  • Anthropic 相容
以下為首次建立緩衝時的 usage(純文字輸入、非思考模式):
{
  "usage": {
    "prompt_tokens": 2304,
    "completion_tokens": 128,
    "total_tokens": 2432,
    "prompt_tokens_details": {
      "text_tokens": 2304,
      "cached_tokens": 0,
      "cache_write_tokens": 2048,
      "cache_creation_input_tokens": 2048,
      "cache_type": "ephemeral",
      "cache_creation": {
        "ephemeral_5m_input_tokens": 2048,
        "ephemeral_1h_input_tokens": 0
      }
    },
    "completion_tokens_details": {}
  }
}
欄位說明
prompt_tokens全部輸入 Token 數,包含讀取緩衝、建立緩衝和未使用緩衝的部分,命中緩衝後不扣減
total_tokensprompt_tokens 與 completion_tokens 之和
prompt_tokens_details.cached_tokens讀取緩衝的 Token 數
prompt_tokens_details.cache_write_tokens建立緩衝的 Token 數
prompt_tokens_details.cache_creation_input_tokens建立緩衝的 Token 數,與 cache_write_tokens 相等,統計時不要重複相加
prompt_tokens_details.cache_type顯式緩衝的類型,固定為 ephemeral
prompt_tokens_details.cache_creation按 TTL 統計的建立緩衝 Token 數,ephemeral_5m_input_tokens 與 ephemeral_1h_input_tokens 之和等於建立緩衝的 Token 數
上例中未使用緩衝的輸入為 2304 − 0 − 2048 = 256 Token。各緩衝欄位均為原始 Token 數,不含計費倍率。有效期間內以相同首碼再次請求時,cached_tokens 為 2048,cache_write_tokens、cache_creation_input_tokens 及 cache_creation 中的兩項均為 0,prompt_tokens 仍為 2304。圖像、音訊、視訊等輸入明細按實際輸入傳回,思考等輸出明細按模型與設定傳回;不適用的欄位不會傳回,而不是傳回 0。

最佳實務

  • 多輪對話優先使用自動緩衝。 自動斷點隨對話增長後移,無需逐輪調整斷點位置。
  • 將固定內容放在前面。 系統提示詞、工具定義、參考文件等不變的內容放在輸入開頭,時間戳、使用者問題等每次變化的內容放在最後。
  • 將斷點設定在每次請求都相同的最後一個內容塊上。 不要將斷點設定在每次都會變化的內容塊上,否則每次請求都會建立新緩衝,無法讀取。
  • 追加歷史訊息,不改寫已有內容。 修改、刪減或重新排序前面的訊息或工具定義,會使之後的緩衝無法命中。
  • 按變化頻率使用多個斷點。 例如工具定義很少變化、參考文件每天更新時,分別在兩者末尾設定斷點。
  • 單輪新增內容塊較多時補充斷點。 每個斷點最多向前尋找 20 個內容塊,單輪新增內容超過該範圍時,在中間位置增加斷點。
  • 按重複使用間隔選擇 TTL。 重複使用間隔在 5 分鐘以內時使用 5m,命中即可續期;重複使用間隔在 5 分鐘到 1 小時之間時使用 1h。
  • 透過用量欄位觀察命中情況。 緩衝命中率可按讀取緩衝的 Token 數除以全部輸入 Token 數計算,命中率偏低時,檢查首碼和斷點位置是否穩定。

計費說明

緩衝斷點僅影響輸入 Token 的計費,輸出 Token 按原價計費。
輸入 Token 類型計費方式
建立緩衝,TTL 為 5m輸入 Token 單價的約 125%
建立緩衝,TTL 為 1h輸入 Token 單價的約 200%
讀取緩衝Qwen4-Max
未讀取也未建立緩衝輸入 Token 單價
若本次緩衝首碼包含已有的有效緩衝,已有部分按讀取緩衝計費,僅新增部分按建立緩衝計費。TTL 從 5m 升級為 1h 時的計費見續期規則。

使用限制

  • 僅 Qwen4 系列模型支援。
  • 緩存前綴最少爲 1,024 Token。不足 1,024 Token 時不創建緩存,請求正常返回,按 TTL 統計的創建明細不返回。
  • 每個請求最多保留最後 4 個有效斷點,開啟自動緩衝時自動斷點佔用其中 1 個。
  • 系統以每個斷點為終點,最多向前尋找 20 個內容塊。待命中的緩衝與斷點之間間隔超過 20 個內容塊時,無法命中。
  • TTL 僅可設定為 5m 或 1h。

常見問題

Q:不設定任何緩衝參數,還能命中緩衝嗎?

可以。未設定緩衝參數時使用隱式緩衝,系統自動識別請求的公用首碼,但不保證命中。需要穩定命中時,請設定緩衝斷點或開啟自動緩衝。

Q:只設定了 TTL,為什麼緩衝有效期間沒有變化?

TTL 只對顯式緩衝生效。在 OpenAI 相容介面中只設定 prompt_cache_options.ttl 時,請求使用隱式緩衝。請同時新增手動斷點,或將 prompt_cache_options.mode 設定為 implicit。

Q:使用 5m 請求命中 1h 緩衝,會縮短緩衝有效期間嗎?

不會。新的到期時間取原到期時間與本次續期時間中較晚的一個,且緩衝保留 1h 檔位。詳見續期規則。