僅適用於 Qwen4 系列模型的顯式緩衝。透過自動緩衝或緩衝斷點指定需要重複使用的輸入首碼,並按 5 分鐘或 1 小時設定緩衝有效期間,減少重複計算,降低延遲和輸入成本。
在多輪對話、長文件問答、Agent 等情境中,連續請求往往包含大量相同的開頭內容,例如系統提示詞、工具說明或參考文件。使用顯式緩衝(Qwen4)後,有效期間內的後續請求可以直接讀取這部分內容的緩衝,無需重複計算,從而降低回應延遲和輸入成本。
顯式緩衝透過緩衝斷點指定需要重複使用的內容首碼,命中是確定的:只要首碼完全相同且在有效期間內,後續請求就能讀取緩衝。系統自動識別公用首碼的隱式緩衝不保證命中。
Qwen4 在基礎用法之上提供自動緩衝和緩衝有效期間(TTL)兩項進階用法,詳見進階用法。
工作原理
緩衝以斷點為單位建立和讀取。自動緩衝的斷點由系統設定在輸入末尾,緩衝斷點由您在內容塊上標記。每個斷點對應的緩衝首碼是從請求開頭到斷點所在內容塊末尾的全部輸入。
收到請求後,系統以每個斷點為終點,向前尋找最多 20 個內容塊,選取已緩衝的最長相同首碼:
- 命中緩衝:讀取已緩衝的首碼,並按本次請求的 TTL 續期。
- 未命中緩衝:從請求開頭到斷點處的內容建立為新的緩衝。若首碼中有部分內容已命中緩衝,僅對新增部分建立緩衝。
緩衝首碼需完全相同才能命中,且僅在同一使用者的請求之間重複使用。將固定不變的內容放在前面、每次變化的內容放在斷點之後,可以提高命中率。
未設定任何緩衝參數時,系統使用隱式緩衝自動識別請求的公用首碼,但不保證命中。需要穩定重複使用指定內容時,請開啟自動緩衝或設定緩衝斷點。
基礎用法
在請求中需要重複使用的內容塊上設定緩衝斷點。系統以該內容塊的末尾作為斷點,把從請求開頭到該處的全部輸入作為緩衝首碼:第一次請求建立緩衝,有效期間內首碼相同的後續請求讀取緩衝。緩衝首碼至少為 1,024 Token。
OpenAI 兼容 Chat Completions
在 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 中的一種。
以下範例連續傳送兩次請求:第一次請求建立緩衝,第二次請求保持首碼不變、只修改問題,從而讀取緩衝。
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。數字為示意,實際取決於文件長度。
OpenAI 兼容 Responses
通過 OpenAI 兼容的 /compatible-mode/v1/responses 接口使用緩存。在請求頂層設置 prompt_cache_options;在 input 的消息內容塊上設置 prompt_cache_breakpoint。
| 字段 | 類型 | 說明 |
|---|---|---|
prompt_cache_options | object | 可選對象,配置緩存模式和有效期。 |
prompt_cache_options.mode | string | 可選,支持 implicit 和 explicit,默認 implicit。implicit 開啓顯式緩存,在最後一條輸入消息末尾自動設置斷點;手動斷點與自動斷點同時生效。explicit 需結合手動斷點纔會創建緩存,沒有斷點時不生效。 |
prompt_cache_options.ttl | string | 可選,支持 5m 和 1h,默認 5m。 |
input[].content[].prompt_cache_breakpoint | object | 內容塊上的可選對象,優先級高於頂層緩存模式。支持添加到 input_text、input_image、input_file 類型的內容塊。 |
prompt_cache_breakpoint.mode | string | 設置斷點時必填,僅支持 explicit。請顯式傳入 {"mode": "explicit"}。 |
以下示例串行發送兩次請求,保持斷點前的長文檔相同,僅改變斷點後的問題。第一次創建緩存,第二次在有效期內讀取緩存。示例使用 qwen4-max。運行前安裝 openai 並設置 DASHSCOPE_API_KEY 和 DASHSCOPE_BASE_URL;新加坡的 Base URL 爲 https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1,將 {WorkspaceId} 替換爲業務空間 ID。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DASHSCOPE_API_KEY"],
base_url=os.environ["DASHSCOPE_BASE_URL"],
)
long_text = "Cache reference: Paris is the capital of France. " * 400
for question in ["Summarize this document.", "What is the capital of France?"]:
response = client.responses.create(
model="qwen4-max",
input=[{
"role": "user",
"content": [
{
"type": "input_text",
"text": long_text,
"prompt_cache_breakpoint": {"mode": "explicit"},
},
{"type": "input_text", "text": question},
],
}],
reasoning={"effort": "none"},
max_output_tokens=128,
extra_body={"prompt_cache_options": {"mode": "explicit", "ttl": "5m"}},
)
print(response.output_text)
print(response.usage.model_dump())
curl 請求中的 DASHSCOPE_RESPONSES_URL 爲上述 Base URL 加 /responses。將佔位文檔替換爲至少 1,024 Token 的真實文檔。
curl "$DASHSCOPE_RESPONSES_URL" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen4-max",
"input": [{
"role": "user",
"content": [
{
"type": "input_text",
"text": "<DOCUMENT_WITH_AT_LEAST_1024_TOKENS>",
"prompt_cache_breakpoint": {"mode": "explicit"}
},
{"type": "input_text", "text": "Summarize this document."}
]
}],
"reasoning": {"effort": "none"},
"max_output_tokens": 128,
"prompt_cache_options": {"mode": "explicit", "ttl": "5m"}
}'
Anthropic 相容
在 system 或 messages 中需要緩衝的內容塊上新增 cache_control,值為 {"type": "ephemeral"}:
system=[
{
"type": "text",
"text": long_text,
"cache_control": {"type": "ephemeral"}, # <-- 緩衝斷點
}
],
使用多個斷點
當提示詞由變化頻率不同的幾部分組成時,可以為每一部分分別設定斷點。例如智慧客服的提示詞通常包括系統人設(幾乎不變)、知識庫檢索結果(隨諮詢主題變化)和對話歷史(持續增長)。在每部分末尾設定斷點後,即使知識庫內容發生變化,系統人設部分仍可命中緩衝。
每個請求最多保留最後 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
在請求頂層設定 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 兼容 Responses
設置 prompt_cache_options 開啓顯式緩存,mode 默認爲 implicit。系統在最後一條輸入消息末尾自動設置斷點,與手動斷點同時生效。
response = client.responses.create(
model="qwen4-max",
input=[{"role": "user", "content": [{"type": "input_text", "text": long_text}]}],
reasoning={"effort": "none"},
max_output_tokens=128,
extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "1h"}},
)
print(response.usage.model_dump())
Anthropic 相容
在請求頂層設定 cache_control,值為 {"type": "ephemeral"}。頂層 cache_control 用於開啟自動緩衝,與內容塊上的 cache_control 可以同時使用。使用 Anthropic Python SDK 時透過 extra_body 傳入:
message = client.messages.create(
model="qwen4-max",
max_tokens=1024,
messages=[{"role": "user", "content": "請概括這份文件:" + long_text}],
extra_body={"cache_control": {"type": "ephemeral"}}, # <-- 在請求頂層開啟自動緩衝
)
以下完整範例開啟自動緩衝,並連續傳送兩次相同的長文件請求:第一次請求建立緩衝,第二次請求讀取緩衝。
OpenAI 兼容 Chat Completions
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")
import OpenAI from "openai";
const client = new OpenAI({
// 若沒有設定環境變數,請將下行替換為:apiKey: "sk-xxx"
apiKey: process.env.DASHSCOPE_API_KEY,
// 以下為新加坡地域的 URL,呼叫時請將 WorkspaceId 替換為真實的業務空間 ID,各地域的 URL 不同。
baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
});
// 需要重複使用的長文件,緩衝首碼最少為 1024 Token
const longText = "<固定的長文件>".repeat(400);
async function ask() {
const completion = await client.chat.completions.create({
model: "qwen4-max",
messages: [{ role: "user", content: "請概括這份文件:" + longText }],
enable_thinking: false,
prompt_cache_options: { mode: "implicit" }, // <-- 開啟自動緩衝
});
return completion.usage.prompt_tokens_details;
}
async function main() {
for (let i = 1; i <= 2; i++) {
const details = await ask();
console.log(`第 ${i} 次請求:讀取緩衝 ${details.cached_tokens} Token,建立緩衝 ${details.cache_write_tokens} Token`);
}
}
main().catch(console.error);
# 以下為新加坡地域的 URL,呼叫時請將 WorkspaceId 替換為真實的業務空間 ID,各地域的 URL 不同。
# 將 <固定的長文件> 替換為不少於 1024 Token 的長文件,並在有效期間內傳送兩次。
curl -X POST "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen4-max",
"messages": [
{"role": "user", "content": "請概括這份文件:<固定的長文件>"}
],
"enable_thinking": false,
"prompt_cache_options": {"mode": "implicit"}
}'
OpenAI 兼容 Responses
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DASHSCOPE_API_KEY"],
base_url=os.environ["DASHSCOPE_BASE_URL"],
)
long_text = "Cache reference: Paris is the capital of France. " * 400
for question in ["Summarize this document.", "Summarize this document."]:
response = client.responses.create(
model="qwen4-max",
input=[{
"role": "user",
"content": [
{
"type": "input_text",
"text": long_text,
},
{"type": "input_text", "text": question},
],
}],
reasoning={"effort": "none"},
max_output_tokens=128,
extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "5m"}},
)
print(response.output_text)
print(response.usage.model_dump())
Anthropic 相容
import os
import anthropic
client = anthropic.Anthropic(
# 若沒有設定環境變數,請將下行替換為: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/apps/anthropic",
)
# 需要重複使用的長文件,緩衝首碼最少為 1024 Token
long_text = "<固定的長文件>" * 400
def ask():
message = client.messages.create(
model="qwen4-max",
max_tokens=1024,
messages=[{"role": "user", "content": "請概括這份文件:" + long_text}],
extra_body={"cache_control": {"type": "ephemeral"}}, # <-- 在請求頂層開啟自動緩衝
)
return message.usage
for i in range(1, 3):
usage = ask()
print(f"第 {i} 次請求:讀取緩衝 {usage.cache_read_input_tokens} Token,建立緩衝 {usage.cache_creation_input_tokens} Token")
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
// 若沒有設定環境變數,請將下行替換為:apiKey: "sk-xxx"
apiKey: process.env.DASHSCOPE_API_KEY,
// 以下為新加坡地域的 URL,呼叫時請將 WorkspaceId 替換為真實的業務空間 ID,各地域的 URL 不同。
baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic",
});
// 需要重複使用的長文件,緩衝首碼最少為 1024 Token
const longText = "<固定的長文件>".repeat(400);
async function ask() {
const message = await client.messages.create({
model: "qwen4-max",
max_tokens: 1024,
messages: [{ role: "user", content: "請概括這份文件:" + longText }],
cache_control: { type: "ephemeral" }, // <-- 在請求頂層開啟自動緩衝
});
return message.usage;
}
async function main() {
for (let i = 1; i <= 2; i++) {
const usage = await ask();
console.log(`第 ${i} 次請求:讀取緩衝 ${usage.cache_read_input_tokens} Token,建立緩衝 ${usage.cache_creation_input_tokens} Token`);
}
}
main().catch(console.error);
# 以下為新加坡地域的 URL,呼叫時請將 WorkspaceId 替換為真實的業務空間 ID,各地域的 URL 不同。
# 將 <固定的長文件> 替換為不少於 1024 Token 的長文件,並在有效期間內傳送兩次。
curl -X POST "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic/v1/messages" \
-H "Content-Type: application/json" \
-H "x-api-key: $DASHSCOPE_API_KEY" \
-d '{
"model": "qwen4-max",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"messages": [
{"role": "user", "content": "請概括這份文件:<固定的長文件>"}
]
}'
預期輸出類似如下,具體 Token 數取決於文件長度:
第 1 次請求:讀取緩衝 0 Token,建立緩衝 2048 Token
第 2 次請求:讀取緩衝 2048 Token,建立緩衝 0 Token
第二次請求的輸入與第一次相同,因此讀取了第一次建立的緩衝。
設定緩衝有效期間
緩衝有效期間(TTL)可選 5m(5 分鐘)或 1h(1 小時),預設為 5m。緩衝在有效期間內被命中時會自動續期,續期方式見續期規則。
OpenAI 兼容 Chat Completions
在請求頂層的 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 時需同時設定緩衝斷點或開啟自動緩衝。
OpenAI 兼容 Responses
在請求頂層的 prompt_cache_options.ttl 中設置緩存有效期,支持 5m 和 1h,默認爲 5m。
extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "1h"}}
Anthropic 相容
開啟自動緩衝時,在頂層 cache_control 中設定 ttl,未設定時為 5m:
extra_body={"cache_control": {"type": "ephemeral", "ttl": "1h"}}, # <-- 緩衝有效期間為 1 小時
使用緩衝斷點時,在內容塊的 cache_control 中設定 ttl:
system=[
{
"type": "text",
"text": long_text,
"cache_control": {"type": "ephemeral", "ttl": "1h"}, # <-- 緩衝有效期間為 1 小時
}
],
續期規則
首次請求或緩衝已過期時,按本次請求的 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 發起 | 5m | 13:00 | 13:00 | 讀取緩衝。12:25 早於原到期時間,到期時間不變,既不縮短,也不續到 13:20 |
| 12:58 發起 | 5m | 13:00 | 13:03 | 讀取緩衝。到期時間延長至本次開始後 5 分鐘,仍保留 1h 檔位 |
| 13:01 發起 | 1h | 13:03 | 14:01 | 讀取緩衝。緩衝已是 1h 檔位,不產生升級建立 |
以上範例基於相同首碼的串行請求。多個請求並發寫入同一緩衝時可能相互覆蓋,不保證保留最晚的到期時間。
查看緩衝用量
回應的 usage 中傳回讀取緩衝和建立緩衝的 Token 數。串流輸出時,OpenAI 相容介面需設定 stream_options 為 {"include_usage": true},從最後一個包含 usage 的資料塊中讀取。
OpenAI 兼容 Chat Completions
以下為首次建立緩衝時的 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_tokens | prompt_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。
OpenAI 兼容 Responses
響應頂層的 prompt_cache_options 返回緩存 mode(implicit 或 explicit)與 ttl(5m 或 1h)。緩存用量位於 usage.input_tokens_details。流式請求從 response.completed 事件中的 response.usage 讀取用量,不使用 Chat Completions 的 stream_options.include_usage。
| 字段 | 說明 |
|---|---|
input_tokens | 全部輸入 Token 數,包括讀取緩存、創建緩存和未使用緩存的部分。 |
input_tokens_details.cached_tokens | 讀取緩存的 Token 數。 |
input_tokens_details.cache_write_tokens | 創建緩存的 Token 數。 |
input_tokens_details.cache_write_tokens_details.ttl_5m_tokens / ttl_1h_tokens | 按 TTL 統計的創建 Token 數,兩項之和等於 cache_write_tokens。 |
以下爲北京測試端點上首次創建 5m 緩存時返回的字段示例。相同前綴的第二次請求中,cached_tokens 爲 4488,cache_write_tokens 及兩個 TTL 創建字段均爲 0。
{
"prompt_cache_options": {
"mode": "explicit",
"ttl": "5m"
},
"usage": {
"input_tokens": 4498,
"input_tokens_details": {
"cached_tokens": 0,
"cache_write_tokens": 4488,
"cache_write_tokens_details": {
"ttl_5m_tokens": 4488,
"ttl_1h_tokens": 0
}
},
"output_tokens": 32,
"output_tokens_details": {
"reasoning_tokens": 32
},
"total_tokens": 4530
}
}
不要將 Responses 的 input_tokens_details 字段與 Chat Completions 的 prompt_tokens_details 或 Anthropic 的 cache_creation 字段混用。
Anthropic 相容
以下為開啟自動緩衝並將 TTL 設定為 1h 時,首次建立緩衝的 usage:
{
"usage": {
"input_tokens": 8,
"output_tokens": 128,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 2048,
"cache_creation": {
"ephemeral_5m_input_tokens": 0,
"ephemeral_1h_input_tokens": 2048
},
"prompt_tokens_details": {
"cached_tokens": 0
}
}
}
| 欄位 | 說明 |
|---|---|
input_tokens | 未讀取緩衝、也未建立緩衝的輸入 Token 數 |
cache_read_input_tokens | 讀取緩衝的 Token 數 |
cache_creation_input_tokens | 建立緩衝的 Token 數 |
cache_creation | 按 TTL 統計的建立緩衝 Token 數 |
prompt_tokens_details.cached_tokens | 讀取緩衝的 Token 數,與 cache_read_input_tokens 相同,統計時不要重複相加 |
全部輸入 Token 數為 input_tokens、cache_read_input_tokens 與 cache_creation_input_tokens 之和,上例中為 8 + 0 + 2048 = 2056。
最佳實務
- 多輪對話優先使用自動緩衝。 自動斷點隨對話增長後移,無需逐輪調整斷點位置。
- 將固定內容放在前面。 系統提示詞、工具定義、參考文件等不變的內容放在輸入開頭,時間戳、使用者問題等每次變化的內容放在最後。
- 將斷點設定在每次請求都相同的最後一個內容塊上。 不要將斷點設定在每次都會變化的內容塊上,否則每次請求都會建立新緩衝,無法讀取。
- 追加歷史訊息,不改寫已有內容。 修改、刪減或重新排序前面的訊息或工具定義,會使之後的緩衝無法命中。
- 按變化頻率使用多個斷點。 例如工具定義很少變化、參考文件每天更新時,分別在兩者末尾設定斷點。
- 單輪新增內容塊較多時補充斷點。 每個斷點最多向前尋找 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 檔位。詳見續期規則。