> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 語義緩存

> Theo 如何緩存響應以降低成本和延遲。

Theo 會對補全響應進行語義化緩存。完全相同的請求(相同的提示詞、模式、技能和工具)會立即返回緩存結果,且零成本。

## 工作原理

1. Theo 根據請求參數(提示詞、模式、技能、工具)生成一個確定性的緩存鍵
2. 檢查服務端緩存中是否存在匹配的條目
3. **命中時**:立即返回緩存的響應 —— 零成本,延遲低於 10ms
4. **未命中時**:運行完整的編排流程,緩存結果,然後返回

被緩存的響應會在響應體中包含 `"_cached": true`,以便你判斷是否命中了緩存。

## 緩存鍵的計算方式

緩存鍵是以下內容的確定性哈希值:

* **提示詞文本**(精確匹配)
* **模式**(`auto`、`fast`、`think` 等)
* 生效的**技能 slug**
* 內聯的**工具定義**

<Note>
  帶有 `conversation_id` 的請求永遠不會被緩存,因為它們依賴於每次調用之間會變化的對話歷史。
</Note>

## TTL 行為

緩存條目會根據內容類型自動過期:

| 模式 | 典型 TTL |
| - | - |
| `fast` / `auto` | 數分鐘 |
| `think` / `code` | 數分鐘到數小時 |
| `research` | 不緩存(異步任務) |
| `image` / `video` | 不緩存(生成式內容) |

TTL 由服務端統一管理,並在新鮮度與成本節省之間做了優化權衡。

## 緩存作用域

* 緩存是**按用戶**隔離的 —— 你的緩存響應不會與其他賬戶共享
* 當使用組織級密鑰時,緩存按 **key** 隔離

## 檢測緩存命中

```typescript theme={null}
const res = await theo.complete({ prompt: "What is DNS?" });

if ((res as any)._cached) {
  console.log("Cache hit! Cost: 0");
} else {
  console.log(`Cache miss. Cost: ${res.usage.cost_cents}¢`);
}
```

## 成本影響

對於具有重複查詢特徵的應用(聊天機器人、儀表盤、分類任務),語義緩存可將成本降低 30%–60%。你可以在[使用情況儀表盤](/dashboard/usage-analytics)中監控自己的緩存命中率。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.