本文目錄
Perplexity 在 Agent API 官方文件(docs.perplexity.ai/docs/agent-api/prompt-caching)中設置了獨立的 Prompt Caching 技術專頁,系統說明模型服務商對重複提示詞前綴的快取機制、Cache read / Cache write 計費欄位,以及基於 prompt_cache_key 和斷點標記的細粒度控制方式。在此之前,Perplexity 已於 2026 年 8 月為 Agent API 預設(presets)引入自動穩定的提示詞快取鍵(官方註明高頻使用預設時可降低約 5% 成本),相關生態介面動態亦可參閱站內 Perplexity Monitor API 文件與價表、Perplexity Decisions API 更新 以及 Perplexity 專題主頁。
預設快取機制與 Cache read / write 計費規則
預設情況下,Agent API 會在系統指令(system instructions)和最新一條訊息上自動放置快取斷點,底層模型提供商也可能主動執行快取;單次代理執行(agent run)無需修改請求參數即可享受前綴快取。回應主體中的 usage 物件透過以下欄位區分快取用量與成本:
快取讀取(input_tokens_details.cache_read_input_tokens):命中快取並讀取的輸入 token 數,按對應模型的 Cache read 費率計費;為相容 OpenAI 格式,cached_tokens 欄位同步回傳相同數值,實際讀取費用記錄在 cost.cache_read_cost。
快取寫入(input_tokens_details.cache_creation_input_tokens):首次寫入提示詞快取的輸入 token 數,按對應模型的 Cache write 費率計費,寫入費用記錄在 cost.cache_creation_cost。具體費率按模型公布在 Agent API Models 價表中;若某模型價表未列出 Cache write 欄或顯示破折號,則寫入 token 直接按標準 Input 單價計費。
高寫入費率模型的成本風險:部分模型的 Cache write 單價高於普通輸入單價——例如官方範例中的 openai/gpt-6.1-sol,在 Perplexity 價表中標準輸入為 $2.00/1M(≤272k)或 $4.00/1M(>272k),Cache write 為 $2.50/1M(≤272k)或 $5.00/1M(>272k),Cache read 為 95% off input。對這類模型,如果整段提示詞寫入快取後沒有被後續請求複用,單次呼叫反而比不快取更貴。
Agent API Models 參考與定價計算器已列入 openai/gpt-6.2-sol、openai/gpt-6.2-astra 及預設處理價,快取讀寫按該表 cache 價計,而不按 input 價計;這兩個模型在 Perplexity 渠道上的預設處理價,亦見OpenAI 正式推出 GPT-6.2 Astra 與 GPT-6.2 Sol:旗艦推理與日常高效雙線齊發,API 定價及 Ultrafast 檔位公布。
用 prompt_cache_key 實現跨請求前綴複用
對於重試或包含多輪互動的任務,開發者應在共享相同前綴的每次請求中傳入相同的 prompt_cache_key,使請求按快取親和性路由,從而讀取前序請求寫入的快取:
帳號隔離與路由邊界:prompt_cache_key 嚴格限定在目前帳號作用域內,即使不同帳號使用相同鍵名也不會共享快取;該參數也不會改變實際處理請求的底層模型。
按業務負載拆分鍵名:建議為每一類共享前綴的工作負載分配獨立鍵名(例如每個固定文件或提示詞範本對應一個 key),無關任務不要共用。不同的推理力度檔位(effort levels)會為共享的系統提示詞與工具定義生成預設鍵,手動傳入的 prompt_cache_key 會覆蓋該預設值。
前綴排列與多輪續接:由於快取讀取要求前綴完全匹配,固定內容(指令、參考文件、資料結構)必須放在提示詞開頭,動態變化的內容放在末尾。延續對話時,既可攜帶相同的 prompt_cache_key 並追加新輪次重新發送,也可直接傳入 previous_response_id,使歷史輪次原樣抵達模型以命中快取。
implicit 與 explicit 斷點控制模式
開發者可透過 prompt_cache_options.mode 搭配內容區塊中的 prompt_cache_breakpoint 精確指定快取邊界:
implicit 模式(預設):Agent API 自動設定預設斷點,同時允許服務商自動快取。一旦請求中的 input_text 片段手動添加了 prompt_cache_breakpoint,自訂標記將替代預設斷點,單次請求最多允許 3 個標記。
explicit 模式:關閉所有預設斷點與自動快取,僅對明確標記的 input_text 片段執行快取,單次請求最多允許 4 個標記。針對前綴絕不會複用的單次請求,傳入 "prompt_cache_options": {"mode": "explicit"} 且不加任何標記即可完全避免快取寫入費用。
斷點生效規則、TTL 與 SDK 串接提示:在某段可複用前綴末尾的 input_text 放置斷點後,其前方所有內容(含系統指令與更早訊息)都會一併寫入快取;斷點隨回應儲存,使用 previous_response_id 續接時會自動保留(若累計斷點超出目前模式上限,則保留最新的幾個)。若斷點數量超限或標註在非 input_text 片段上,介面將回傳 HTTP 400。此外,prompt_cache_options.ttl 欄位僅為相容 OpenAI 格式而保留,傳入後會被忽略(與 OpenAI 支援設定 12 小時快取保留期 不同,Perplexity 底層直接採用各服務商預設快取生命週期)。呼叫端點 https://api.perplexity.ai/v1/agent 時,官方 Python 與 TypeScript 範例註明 prompt_cache_options 和 prompt_cache_breakpoint 尚未加入 SDK 類型定義,需透過請求主體 extra_body(Python)或 @ts-expect-error(TypeScript)傳入。
