TaleAPI 文档中心

主题

Prompt Cache（提示词缓存） ​

什么是 Prompt Cache ​

Prompt Cache 是模型提供商在服务端实现的缓存机制。当你的请求与之前的请求共享相同的前缀（prefix）时，提供商可以复用已计算的中间结果（KV Cache），从而降低延迟和输入 Token 费用。

这是上游提供商的能力，与本站的线路缓存无关。

工作原理 ​

大模型处理输入时，会逐 Token 计算注意力矩阵（KV Cache）。如果两次请求的前 N 个 Token 完全相同，第二次请求可以直接复用前 N 个 Token 的计算结果，只需要计算后面新增的部分。

请求 1: [system 提示词] [用户消息 A]          ← 全部计算
请求 2: [system 提示词] [用户消息 B]          ← system 提示词命中缓存，只计算用户消息 B
请求 3: [system 提示词] [用户消息 B] [回复] [用户消息 C]  ← 前面全部命中，只计算用户消息 C

关键点：只有前缀匹配才能命中。如果中间插入了不同的内容，后面的所有 Token 都无法命中缓存。

各提供商的实现对比 ​

OpenAIAnthropicGoogle Gemini
触发方式自动，无需代码修改需显式设置 cache_control，也支持自动缓存隐式缓存（自动）+ 显式缓存 API
最低 Token 数1,0241,024 ~ 4,096（因模型而异）因模型而异
缓存粒度128 Token 增量按 cache_control 断点按前缀
缓存有效期5 ~ 10 分钟（低峰期可达 1 小时）默认 5 分钟（每次命中刷新），可付费延长至 1 小时因缓存类型而异
费用优惠缓存命中的输入 Token 降价 50%（部分模型达 90%）缓存命中降价 90%，缓存写入加价 25%隐式缓存最高降价 90%

通过中转站使用时

本站作为中转层会透传上游的 Prompt Cache 行为。你发送的请求会原样转发给上游，上游的缓存机制正常生效。响应中的缓存相关字段（如 cached_tokens、cache_creation_input_tokens 等）也会原样返回。

如何利用 Prompt Cache 省钱 ​

1. 把不变的内容放在前面 ​

Prompt Cache 只匹配前缀。把 system 提示词、工具定义、Few-shot 示例等不变的内容放在 messages 最前面，把用户输入等变化的内容放在最后面：

json
{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "这是一段很长的系统提示词..." },  // ← 不变，放前面
    { "role": "user", "content": "历史消息1" },                      // ← 多轮对话，逐渐增长
    { "role": "assistant", "content": "历史回复1" },
    { "role": "user", "content": "新的用户输入" }                    // ← 变化的部分，放最后
  ]
}

2. 保持前缀稳定 ​

避免在 system 提示词中插入时间戳、随机 ID 等动态内容——这会破坏前缀匹配，导致缓存完全失效。

❌ 错误做法：

你是一个助手。当前时间：2025-06-23 14:30:00

✅ 正确做法：把时间戳放在用户消息中，而不是 system 提示词里。

3. 多轮对话天然适合 Prompt Cache ​

多轮对话中，每次请求都会携带完整的历史消息。随着对话推进，前面的消息保持不变，只有最后一条是新增的——这正好是前缀匹配的理想场景。

如何确认 Prompt Cache 是否生效 ​

API 响应的 usage 字段中会包含缓存相关信息：

OpenAI：

json
{
  "usage": {
    "prompt_tokens": 2048,
    "prompt_tokens_details": {
      "cached_tokens": 1920
    }
  }
}

Anthropic：

json
{
  "usage": {
    "input_tokens": 100,
    "cache_creation_input_tokens": 1500,
    "cache_read_input_tokens": 1500
  }
}

如果 cached_tokens（OpenAI）或 cache_read_input_tokens（Anthropic）大于 0，说明 Prompt Cache 已生效。

参考文档

TaleAPI 导航