Session Pruning：優化長對話的快取與成本

在使用 LLM 開發長對話應用時，你可能遇過這種情況：隨著對話輪數增加，工具輸出的內容（tool results）會迅速堆積，導致 context 變得非常臃腫。這不僅會讓 API 回應變慢，最煩人的是當快取（Cache）過期後，下一次請求就必須重新寫入龐大的歷史紀錄，導致成本飆升。

Session Pruning 就是為了解決這個痛點而生，它能在發送請求給 LLM 前，自動修剪掉記憶體中過時的工具執行結果，幫你省錢又提速。

需要準備的東西

• 使用 Anthropic API 或 OpenRouter 的 Anthropic 模型
• 已設定好的 Gateway 設定檔
• 了解基礎的 JSON 格式

快速開始

預設情況下 Session Pruning 是關閉的。如果你想開啟基於 TTL（存活時間）的自動修剪，只需要在你的配置中加入以下程式碼：

{
  agent: {
    contextPruning: {
      mode: "cache-ttl",
      ttl: "5m"
    },
  },
}

這樣設定後，如果距離上次 Anthropic API 呼叫已經超過 5 分鐘，系統就會在下一次請求前自動清理舊的工具輸出。

運作機制與細節

什麼時候會觸發？

Session Pruning 只會影響發送給模型的訊息，不會改寫硬碟上的 *.jsonl 歷史檔案。它主要針對 Anthropic 模型，因為這對優化 Prompt Caching 特別有效。

• OAuth 或 setup-token 設定檔：預設開啟 cache-ttl，heartbeat 為 1h。
• API key 設定檔：預設開啟 cache-ttl，heartbeat 為 30m，且 Anthropic 模型的 cacheControlTtl 預設為 1h。

什麼會被修剪？

為了確保對話不崩潰，修剪機制非常謹慎：

• 只修剪 toolResult：使用者（User）和助理（Assistant）的訊息絕對不會被動到。
• 保護最新訊息：預設會保留最後 3 個助理訊息（keepLastAssistants）之後的工具結果。
• 跳過圖片：包含圖片型別（image blocks）的工具結果永遠不會被修剪。
• 軟修剪 (Soft-trim)：針對超長結果，保留頭尾並在中間插入 ...。
• 硬清理 (Hard-clear)：將整個工具結果替換為預設的提示文字。

特定工具過濾

如果你只想修剪特定工具的輸出，可以使用 allow 或 deny 清單（支援 * 萬用字元）：

{
  agent: {
    contextPruning: {
      mode: "cache-ttl",
      tools: {
        allow: ["exec", "read"],
        deny: ["*image*"]
      },
    },
  },
}

疑難排解

為什麼修剪沒有執行？

1. 助理訊息太少：如果對話中助理訊息的數量不足以判斷 keepLastAssistants 的切分點，系統會跳過修剪。
2. 包含圖片內容：只要工具結果裡有圖片，為了避免模型失去視覺脈絡，該條訊息會被完整保留。
3. 未達 TTL 時間：修剪只會在距離上次呼叫超過 ttl 設定時間（預設 5 分鐘）時觸發。

修剪會增加費用嗎？ 不會。修剪本身不消耗 Token，它反而能減少 TTL 過期後第一次請求所需的 cacheWrite 大小。一旦修剪完成並重新快取，後續請求就能繼續使用這份較小的快取。

---

如果你在設定過程中遇到困難，可以詢問 AI Setup Assistant 獲取即時協助。

下一步

• Gateway Configuration：查看完整的配置參數
• /concepts/compaction：了解如何持久化地壓縮歷史紀錄