提示缓存

要节省推理成本，您可以在支持的提供商和模型上启用提示缓存。

大多数提供商会自动启用提示缓存，但请注意，有些（如下方的 Anthropic）要求您在每条消息的基础上启用它。

当使用缓存（无论是在支持的模型中自动使用，还是通过 cache_control 属性），TopRouter 将尽最大努力继续路由到相同的提供商以利用预热的缓存。如果带有缓存提示的提供商不可用，TopRouter 将尝试使用下一个最佳的提供商。

检查缓存使用情况

要查看每次生成节省了多少缓存，您可以：

1. 点击 [活动] 页面上的详细信息按钮
2. 使用 /api/v1/generation API，[在此处记录]
3. 在请求中使用 usage: [include: true} 以在响应末尾获取缓存令牌（详情请参见 [使用会计]）

响应体中的 cache_discount 字段将告诉您响应在缓存使用上节省了多少。一些提供商，如 Anthropic，在缓存写入时会有负折扣，但在缓存读取时会有正折扣（这会减少总成本）。

OpenAI

缓存价格变化：

• 缓存写入：免费
• 缓存读取：（根据模型）按原始输入定价的 0.25x 或 0.50x 收费

点击此处查看按模型划分的 OpenAI 缓存定价。

OpenAI 的提示缓存是自动化的，不需要任何额外配置。提示的最小大小为 1024 个令牌。

点击此处了解更多关于 OpenAI 提示缓存及其限制的信息。

Grok

缓存价格变化：

• 缓存写入：免费
• 缓存读取：按原始输入定价收费

点击此处查看按模型划分的 Grok 缓存定价。

Grok 的提示缓存是自动化的，不需要任何额外配置。

Anthropic Claude

缓存价格变化：

• 缓存写入：按 [ANTHROPIC_CACHE_WRITE_MULTIPLIER] 原始输入定价收费
• 缓存读取：按 [ANTHROPIC_CACHE_READ_MULTIPLIER] 原始输入定价收费

Anthropic 的提示缓存需要使用 cache_control 断点。断点数量限制为四个，缓存将在五分钟内过期。因此，建议将缓存断点保留给大篇幅文本，例如角色卡片、CSV 数据、RAG 数据、书籍章节等。

点击此处了解更多关于 Anthropic 提示缓存及其限制的信息。

cache_control 断点只能插入到多部分消息的文本部分。

系统消息缓存示例：

[
  "messages": [
    [
      "role": "system",
      "content": [
        [
          "type": "text",
          "text": "您是一位研究罗马帝国衰落的历史学家。您非常了解以下书籍："
        },
        [
          "type": "text",
          "text": "HUGE TEXT BODY",
          "cache_control": [
            "type": "ephemeral"
          }
        }
      ]
    },
    [
      "role": "user",
      "content": [
        [
          "type": "text",
          "text": "是什么引发了崩溃？"
        }
      ]
    }
  ]
}

用户消息缓存示例：

[
  "messages": [
    [
      "role": "user",
      "content": [
        [
          "type": "text",
          "text": "根据以下书籍："
        },
        [
          "type": "text",
          "text": "HUGE TEXT BODY",
          "cache_control": [
            "type": "ephemeral"
          }
        },
        [
          "type": "text",
          "text": "列出上述书中的所有角色"
        }
      ]
    }
  ]
}

Google Gemini

隐式缓存

Gemini 2.5 Pro 和 2.5 Flash 模型现在支持隐式缓存，提供类似于 OpenAI 自动缓存的自动缓存功能。隐式缓存无缝工作 — 不需要手动设置或额外的 cache_control 断点。

价格变化：

• 没有缓存写入或存储成本。
• 缓存令牌按 [GOOGLE_CACHE_READ_MULTIPLIER] 原始输入令牌成本收费。

请注意，TTL 平均为 3-5 分钟，但会有所不同。Gemini 2.5 Flash 的最小令牌数为 [GOOGLE_CACHE_MIN_TOKENS_2_5_FLASH}，Gemini 2.5 Pro 的最小令牌数为 [GOOGLE_CACHE_MIN_TOKENS_2_5_PRO}，请求才有资格进行缓存。

Google 官方公告

要最大化隐式缓存命中率，请在请求之间保持消息数组的初始部分一致。 将变化（如用户问题或动态上下文元素）推到提示/请求的末尾。

缓存请求的价格变化：

• 缓存写入：按输入令牌成本加上 5 分钟缓存存储收费，计算如下：

缓存写入成本 = 输入令牌价格 + (缓存存储价格 × (5 分钟 / 60 分钟))

• 缓存读取：按 [GOOGLE_CACHE_READ_MULTIPLIER}× 原始输入令牌成本收费。

支持的模型和限制：

只有某些 Gemini 模型支持缓存。请查阅 Google 的 Gemini API 定价文档 以获取最新详情。

缓存写入有 5 分钟的生存时间 (TTL)，不会更新。5 分钟后，缓存过期，必须写入新缓存。

Gemini 模型通常需要 4096 个令牌的最小值才能进行缓存写入。缓存的令牌计入模型的最大令牌使用量。Gemini 2.5 Pro 的最小值为 [GOOGLE_CACHE_MIN_TOKENS_2_5_PRO} 令牌，Gemini 2.5 Flash 的最小值为 [GOOGLE_CACHE_MIN_TOKENS_2_5_FLASH} 令牌。

TopRouter 上的 Gemini 提示缓存工作原理：

TopRouter 简化了 Gemini 缓存管理，抽象了复杂性：

• 您不需要手动创建、更新或删除缓存。
• 您不需要明确管理缓存名称或 TTL。

如何启用 Gemini 提示缓存：

TopRouter 中的 Gemini 缓存需要您在消息内容中显式插入 cache_control 断点，类似于 Anthropic。我们建议主要为大内容块（如 CSV 文件、长角色卡片、检索增强生成 (RAG) 数据或大量文本源）使用缓存。

您可以在请求中包含的 cache_control 断点数量没有限制。 TopRouter 将仅使用最后一个断点进行 Gemini 缓存。包含多个断点是安全的， 可以帮助保持与 Anthropic 的兼容性，但只有最后一个将用于 Gemini。

示例：

系统消息缓存示例

[
  "messages": [
    [
      "role": "system",
      "content": [
        [
          "type": "text",
          "text": "您是一位研究罗马帝国衰落的历史学家。以下是详细的参考书："
        },
        [
          "type": "text",
          "text": "HUGE TEXT BODY HERE",
          "cache_control": [
            "type": "ephemeral"
          }
        }
      ]
    },
    [
      "role": "user",
      "content": [
        [
          "type": "text",
          "text": "是什么引发了崩溃？"
        }
      ]
    }
  ]
}

用户消息缓存示例

[
  "messages": [
    [
      "role": "user",
      "content": [
        [
          "type": "text",
          "text": "根据以下书籍文本："
        },
        [
          "type": "text",
          "text": "HUGE TEXT BODY HERE",
          "cache_control": [
            "type": "ephemeral"
          }
        },
        [
          "type": "text",
          "text": "列出上述文本中提到的所有主要角色。"
        }
      ]
    }
  ]
}