> ## 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.