OpenRouter 推出提示詞快取與黏性路由教學

你的代理在每一回合都會傳送相同的系統提示、工具定義、架構與政策指示。在一個六回合的會話中，你可能會被收費六次這同一開場區塊，即使唯一變動的是使用者最新訊息或代理最新工具結果。

提示快取解決了這個問題。供應商會從快取讀取重複的提示部分，而非每次都以全價收費。粘性路由透過將會話送回持有溫熱快取的相同供應商，確保此功能在多回閤中持續有效。

本文將說明金錢面向：快取代幣的成本、快取讀寫定價差異的原因、session_id 如何從第一回合就保持代理會話溫熱，以及如何檢查快取是否真的在運作。

簡而言之

• 快取讀取成本介於 0.1 倍到 0.5 倍新輸入代幣之間，視供應商而定。在 Claude Sonnet 4.6 上，快取讀取費率為 $0.30/M，與 $3.00/M 的輸入費率相比，正好是 0.1 倍。
• 首次請求會付費快取寫入。Anthropic 的寫入費用為 1.25 倍（5 分鐘 TTL）或 2.0 倍（1 小時 TTL）的輸入成本，因此一次未重複使用的寫入成本高於完全不快取。
• 溫熱快取僅在下一個請求落在相同供應商端點時才有效。在超過 70 家供應商中，第二回合可能會觸及冷端點，並需支付全價。
• 我們的粘性路由將後續請求固定到持有溫熱快取的供應商，而 session_id 從第一個成功請求開始就強制執行，甚至在任何快取命中之前。
• 快取未命中有四個原因：提示過短、快取已過期、開場區塊持續變動、或請求轉移至不同供應商。檢查使用回覆中的 cached_tokens 以確認是否命中。

提示快取能降低多少代幣成本？

快取讀取成本介於 0.1 倍至 0.5 倍常規輸入價格，視供應商而定。這個範圍說明瞭快取為何能使代理迴圈成本大幅下降。

重複的部分通常是最昂貴的：長的系統提示、工具定義、JSON 架構、守門線、檢索檔案或保持模型一致性的範例。若不快取，每回合都需再次支付全部成本。快取後，第一個請求將其寫入快取，隨後的請求以較低費率讀取。

以下為供應商層級的概覽：

《prompt caching docs》提供完整的細節。實際金額仍取決於模型與供應商路徑；乘數告訴你對於該供應商，快取輸入與正常輸入的比率。

對於代理程式開發者而言，模式很簡單：第一回合可能需要支付設定快取的費用，但只要重複使用相同的開頭區塊，之後每一回合都會便宜許多。

成本究竟分配在哪裡：快取寫入還是快取讀取？

提示快取有兩項成本：寫入與讀取。

寫入發生於供應商儲存可重複使用的提示部分時。讀取發生於後續請求再次使用該儲存內容時。當相同內容被讀取足夠多次以抵消寫入成本時，你就會獲利。

在某些供應商上，寫入成本高於正常輸入。Anthropic 的快取寫入在預設的 5 分鐘 TTL 下成本為 1.25 倍輸入，1 小時 TTL 下為 2.0 倍輸入。一次從未被重複使用的 Anthropic 快取寫入，成本甚至高於不使用快取直接傳送相同提示。

對於一次性請求，快取可能不會帶來幫助。對於多輪代理，重複是預設行為：代理在整個會話中持續使用相同的指令、工具、架構與政策上下文。因此，寫入成本會在幾輪之後自我抵消。

在短暫的高頻互動中，使用 5 分鐘的快取壽命（TTL）。若會話可能會暫停至足以讓預設快取過期，但內容仍值得保留，則使用 1 小時的 TTL。

為什麼熱快取不總是能在下一個請求中發揮作用？

熱快取只有在下一個請求落在擁有該快取的供應商端點時才有幫助。

當請求能路由到多個供應商時，第一輪可能在一個供應商寫入快取，而第二輪則落在另一個供應商。第二個供應商沒有熱快取可供讀取。請求仍能執行，但你仍須支付全額費用，且 cached_tokens 仍保持低或零。

這就是我們為何將黏性路由與提示快取結合的原因。快取請求之後，若同一模型的後續請求且該供應商的快取讀取價格低於正常輸入，我們會將請求路由回同一供應商端點。若該黏性供應商不可用，OpenRouter 會回退至下一個可用供應商，而不是失敗。

預設情況下，OpenRouter 透過雜湊其第一條系統或開發者訊息以及第一條非系統訊息來識別對話。當這些開場訊息保持不變時，這種方式有效。

代理經常會打破這一規則。某些代理在總結狀態、重新排序工具上下文或新增執行元資料時會重寫第一條訊息。當開場訊息改變時，雜湊值也會改變，對話可能落到不同的供應商。解決方法是明確使用 session_id。

從第一輪就強制使用熱快取，設定 session_id

對於代理迴圈，設定 session_id。當你傳遞它時，OpenRouter 會直接將其作為黏性路由鍵，而不是從開場訊息推導鍵值。

有了 session_id，黏性路由會在第一個成功請求之後啟動，且在任何快取命中發生之前。若沒有它，黏性僅在偵測到快取命中後才開始。對於多輪代理而言，這就是從第一輪就可靠的快取與僅偶爾熱快取之間的差別。

你可以將 session_id 作為頂層請求主體欄位或透過 x-session-id 標頭傳送。保持它在整個對話或代理執行期間穩定，且長度不超過 256 個字元。

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.6",
    "session_id": "my-agent-session-abc123",
    "messages": [{"role": "system", "content": "..."}]
  }'

from openrouter import OpenRouter

client = OpenRouter()

resp = client.chat.send(
    model="anthropic/claude-sonnet-4.6",
    session_id="my-agent-session-abc123",
    messages=[{"role": "system", "content": "..."}],
)

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });

const response = await openRouter.chat.send({
  model: 'anthropic/claude-sonnet-4.6',
  session_id: 'my-agent-session-abc123',
  messages: [{ role: 'system', content: '...' }],
});

使用與工作單位相符的值：聊天執行緒、工單、工作流程執行或代理任務。不要為每一輪都建立新的 session_id，否則請求將不再落在擁有快取的供應商上。

若你使用如 Auto Router 或 Pareto Router 的路由模型，會話黏性亦會在最佳努力基礎上重複使用路由器所選模型，而不僅限於供應商：記住的模型在後續輪次中若仍在路由器目前的候選模型中，將被優先使用；因此，當任務或設定改變時，路由器仍可能選擇不同模型。

如何確認提示快取是否正常運作？

最快檢查方式是 檢視使用量。

在回應中，usage.prompt_tokens_details.cached_tokens 顯示從快取讀取的 token 數量。若大於零，表示請求命中快取。cache_write_tokens 顯示在快取寫入請求期間寫入的 token 數量。

{
  "usage": {
    "prompt_tokens": 10339,
    "completion_tokens": 60,
    "total_tokens": 10399,
    "prompt_tokens_details": {
      "cached_tokens": 10318,
      "cache_write_tokens": 0
    }
  }
}

在此範例中，大部分提示 token 來自快取，此回合未寫入新的快取條目。

可以在三個地方檢查快取行為：活動頁面的詳細檢視、/api/v1/generation API，以及 API 回應中返回的 usage.prompt_tokens_details 物件。

使用 cache_discount 可檢視一次生成所節省的量。在收費寫入的供應商上，寫入回合可能會顯示負折扣，因為快取寫入成本高於正常輸入。之後的快取讀取回合，折扣應該變為正值。

為什麼快取會遺漏，如何避免？

當快取看似失效時，通常是以下四項原因之一：提示過短、快取已過期、開頭內容已變更，或請求被轉至不同的供應商。

提示低於供應商的最小限制

每個供應商都有最小提示尺寸，低於此尺寸時不會被快取。Anthropic 上，Claude Opus 4.5 至 4.8 與 Claude Haiku 4.5 需要 4,096 個 token；Claude Haiku 3.5 需要 2,048；Claude Sonnet 4、4.5 與 4.6（以及 Opus 4 / 4.1）需要 1,024；OpenAI 需要 1,024；Gemini 2.5 Pro 需要 4,096；Gemini 2.5 Flash 需要 1,024。

若可重用內容低於此最小值，快取將不會啟動。不要僅為強制快取而在請求中填充佔位文字。將快取應用於已具備大量可重用內容的場景：工具、架構、已檢索檔案、範例或政策文字。

快取在回合之間已過期

快取的存活時間有限。Anthropic 的預設為 5 分鐘，亦可選擇 1 小時以延長會話。Gemini 的隱式快取大約持續 3-5 分鐘，且在讀取時不會重設。快取過期後，下一個請求必須寫入新的快取。

若使用者經常在回合間暫停，請在支援的情況下使用更長的 TTL，或設計代理以在閒置期間接收新的寫入。

提示開頭持續變動

自動與隱式快取在提示開頭保持不變時效果最佳。將穩定內容放在前面：系統指令、工具、架構與固定參考資料。將變動內容放在後面：使用者問題、時間戳、暫時狀態、工具輸出與短暫元資料。

細節也很重要。若第一條系統訊息包含時間戳，提示會在每回合看起來都是新的。若該時間戳不必成為快取內容，請將其移至後續的使用者或工具訊息。

請求漂移至不同的供應商

快取存在於寫入的地方。若後續請求被路由至不同的供應商端點，該端點將無法讀取先前的快取。

對於代理工作流程，設定 session_id 並讓黏性路由保持會話於熱供應商。需要注意的是：若自行設定 provider.order，則你的順序會覆蓋黏性路由。若需特定供應商順序，請使用 供應商路由控制。

將快取與黏性路由結合於代理迴圈

若代理每回合傳送相同內容，以下為檢查清單：

1. 先放置穩定內容：系統提示、工具定義、架構、政策與長期上下文。
2. 將變動內容放在後面：使用者訊息、工具結果、時間戳與執行特定狀態。
3. 為需要明確 cache_control 的供應商啟用提示快取。
4. 為對話或工作流程執行設定穩定的 session_id。
5. 檢查 cached_tokens 與 cache_discount 以確認已進行讀取。

粗略來說，想像一個代理在 6 個回合中重複相同的 10,000 個 token。

此範例僅涵蓋重複的內容，忽略較小的變動訊息與模型輸出 token。隨著回合數增加，節省金額也會成長。

何時使用哪些設定：

• 在多回合對話中，若重複內容隨對話增長，請使用自動快取。
• 當您確定哪些大型區塊應該快取時（如已檢索檔案、長篇參考檔、角色卡、CSV 資料或政策文字），請使用明確的快取分割點。
• 對於代理會話、支援票證、聊天串、工作流程執行，以及任何開頭訊息可能在回合間變動的對話，請使用 session_id。
• 對於較長的 Anthropic 會話，若預設 5 分鐘快取可能在回合間失效，請使用 1 小時快取；對於短且密集的往返對話，則使用預設。

當代理重複傳送相同昂貴內容時，快取讀取與穩定路由可避免其成為迴圈中最昂貴的部分。快取可降低您傳送 token 的價格。欲瞭解先前降低每 token 價格的路由設定，請參閱 如何在 OpenRouter 上取得最低成本的 LLM 推論。

常見問題

OpenRouter 支援 prompt 快取嗎？

是的。OpenRouter 支援跨受支援的供應商與模型的 prompt 快取。大多數供應商會自動啟用，而 Anthropic 與 Alibaba Qwen 則使用 cache_control 進行明確快取。根據供應商不同，快取讀取的成本為正常輸入價格的 0.1x 至 0.5x，因此重複使用的字首在首次請求後會大幅降低成本。

在 OpenRouter 上快取 token 的成本是多少？

快取讀取的成本為正常輸入價格的 0.1x 至 0.5x，視供應商而定。Anthropic、DeepSeek 與 Alibaba Qwen 的讀取成本為 0.1x；OpenAI 為 0.25x 至 0.50x；Gemini、Grok 與 Moonshot 為 0.25x；Groq 為 0.5x。

為什麼透過 OpenRouter 的 prompt 快取無法正常工作？

常見原因包括：prompt 低於供應商的 token 最小值、快取已過期、不穩定的 prompt 字首，或供應商在回合間漂移。對於代理工作流程，先設定一個穩定的 session_id，然後檢查使用回應中的 cached_tokens；任何大於零的值皆表示快取命中。

如何在代理的回合之間保持快取熱度？

為對話、票證或工作流程執行傳遞一個穩定的 session_id。OpenRouter 將其作為穩定路由鍵，因此後續請求會導向同一個持有熱快取的供應商端點。當設定 session_id 時，穩定性會在第一次成功請求後啟動，且在觀察到任何快取命中之前。

如何確認快取是否節省成本？

檢查 usage.prompt_tokens_details.cached_tokens 以檢視快取讀取，檢查 cache_write_tokens 以檢視快取寫入；若 cached_tokens 值大於零即表示命中。您亦可在回應中閱讀 cache_discount 以檢視每次生成的成本影響，或在 Activity 頁面 或 /api/v1/generation API 中開啟詳細檢視。

快取功能適用於 Auto Router 嗎？

是的。設定 session_id 後，Auto Router 與 Pareto Router 等路由模型會將對話的已解析模型與供應商固定，因而後續回合仍會命中同一個熱快取。