GPT 提示詞快取

​

快速開始

curl https://aihubmix.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -d '{
    "model": "gpt-5.6-sol",
    "prompt_cache_key": "my-app-report-assistant-v1",
    "messages": [
      {
        "role": "system",
        "content": "You are a meticulous assistant for analyzing quarterly financial reports... [此處放置固定不變的長指令或參考資料，≥1024 Token]"
      },
      {
        "role": "user",
        "content": "Summarize the key figures in one sentence."
      }
    ]
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AIHUBMIX_API_KEY"],  # 金鑰從環境變數讀取
    base_url="https://aihubmix.com/v1",
)

long_context = "You are a meticulous assistant for analyzing quarterly financial reports... [固定不變的長指令或參考資料，≥1024 Token]"

# 相同前綴連續請求兩次，第二次命中快取
for i in range(2):
    completion = client.chat.completions.create(
        model="gpt-5.6-sol",
        prompt_cache_key="my-app-report-assistant-v1",
        messages=[
            {"role": "system", "content": long_context},
            {"role": "user", "content": "Summarize the key figures in one sentence."},
        ],
    )
    print(completion.usage.prompt_tokens_details)

// 第 1 次呼叫：無命中
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 0}

// 第 2 次呼叫：前綴命中快取
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 2816}

​

快取計費

​

快取如何自動生效

1. 前綴達到 1,024 Token 且找到一致的快取前綴時，命中部分按快取讀取價計費，並降低首 Token 延遲；
2. 未找到時按常規輸入處理，並把前綴寫入快取（GPT-5.6 及之後按 1.25x 計寫入費）；
3. 命中要求前綴逐位元組一致，前綴中任何一處變化都會使該位置之後的快取全部失效。

• 固定的長系統指令或大量 few-shot 範例
• RAG 場景中重複引用的長參考資料
• 攜帶大量工具定義（tools）的 Agent 工作流
• 只往後追加訊息的長多輪對話

​

GPT-5.6 快取參數

1. 預設（implicit 模式）：不傳任何快取參數也會自動寫快取——系統在最新一條訊息的位置自動設定斷點。GPT-5.6 及之後，自動發生的快取寫入同樣按 1.25x 計費。
2. implicit 模式 + 顯式斷點：在自動斷點之外，可在內容區塊上設定 prompt_cache_breakpoint，把快取邊界固定在穩定內容的末尾；斷點之後的內容變化不會破壞斷點之前的前綴快取。
3. explicit 模式：prompt_cache_options.mode 設為 "explicit" 後只使用手動斷點；完全不設定斷點時該請求不使用快取、也不產生快取寫入費。官方原文：“If the conversation contains no explicit breakpoints, the request does not use prompt caching or incur cache-write charges.”

{
  "model": "gpt-5.6-sol",
  "prompt_cache_options": {"mode": "explicit"},
  "messages": [
    {"role": "user", "content": "[不會重複使用的一次性長內容]"}
  ]
}

{
  "model": "gpt-5.6-sol",
  "prompt_cache_key": "my-app-report-assistant-v1",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "[固定不變的長指令或參考資料，≥1024 Token]",
          "prompt_cache_breakpoint": {"mode": "explicit"}
        }
      ]
    },
    {"role": "user", "content": "Summarize the key figures in one sentence."}
  ]
}

• 每個請求最多建立 4 個新的快取寫入；implicit 模式下自動斷點佔用其中 1 個；
• 斷點之前的前綴仍需達到 1,024 Token 才會被快取；
• 讀取時在最近 50 個斷點中取最長匹配前綴；
• 斷點設定在不支援的內容區塊上會返回 400 invalid_request_error。Chat Completions 支援 text / image_url / input_audio / file / refusal 區塊，Responses API 支援 input_text / input_image / input_file 區塊。

​

為什麼快取沒有命中

• 前綴不足 1,024 Token：低於最小快取長度的請求按常規輸入處理；
• 前綴中混入了變化內容：時間戳、會話 ID、使用者變數等應放到固定內容之後，前綴中任何一處變化都會使之後的快取失效；
• tools 定義或順序變化：工具列表參與前綴計算，定義與排列順序都必須完全一致；
• 圖片 detail 參數不一致：detail 影響圖片 Token 化結果，需保持相同；
• 結構化輸出 schema 變化：response_format 的 JSON Schema 作為系統訊息前綴參與快取，schema 變化即前綴變化；
• reasoning_effort 變化：官方將其列為快取命中率降低的常見原因之一（“Changes to reasoning effort”）；
• 超過快取保留期：GPT-5.6 之前不活躍 5–10 分鐘後清除，GPT-5.6 及之後至少保留 30 分鐘；
• 未設定 prompt_cache_key（GPT-5.6）：不設定時仍可能自動命中，但不使用更可靠的匹配機制。

​

最佳實踐

• 固定內容（系統指令、範例、參考資料、工具定義）放在請求最前面，每輪變化的內容放在最後；
• 為共享同一前綴的流量設定同一個穩定的 prompt_cache_key，單個 key 的總流量控制在約 15 次/分鐘內，超出時按業務拆分更多 key；
• 多輪對話只向後追加訊息，避免修改歷史訊息；
• 保持相同前綴的請求有持續流量，減少快取被清除；
• 前綴不會重複使用的一次性長請求，用 explicit 模式避免快取寫入費（GPT-5.6 及之後）；
• 透過 usage.prompt_tokens_details.cached_tokens 持續監控命中情況。

​

常見問題

​

GPT 的提示快取需要手動開啟嗎？

​

GPT-5.6 的快取寫入費如何計算？如何避免不必要的寫入費？

​

快取能保留多久？

​

GPT-5.6 的顯式斷點和 Claude 的 cache_control 有什麼區別？

​

快取會影響輸出內容嗎？

​

官方參考

• GPT-5.6 發布公告：快取寫入 1.25x / 讀取 90% 折扣的計費規則
• 提示快取指南：機制、參數、usage 欄位與限制
• OpenAI Pricing：各模型官方標價
• GPT-5.6 模型文件：上下文視窗、長上下文計費閾值