上下文缓存概览

上下文缓存有助于降低包含重复内容的 Gemini 请求的费用并缩短延迟时间。Gemini Enterprise Agent Platform 提供两种类型的缓存：

  • 隐式缓存 ：默认启用的自动缓存，在发生缓存命中时可节省费用。隐式缓存包括内存缓存和持久缓存。
  • 显式缓存 ：使用 Gemini Enterprise API 手动启用的缓存，您需要在其中明确声明要缓存的内容，以及提示是否应引用缓存的内容。

无论是隐式缓存还是显式缓存，回答的元数据中的 cachedContentTokenCount 字段均表示输入中已缓存 部分的 token 数。

缓存存储费用

无论是隐式缓存还是显式缓存，您都需要按标准输入 token 价格支付用于创建缓存的输入 token 费用。对于显式缓存，还会根据缓存的存储时长收取存储费用。隐式缓存不收取存储费用。如需了解详情，请参阅 Agent Platform 价格。

隐式缓存

所有 Google Cloud 项目默认都启用了隐式缓存。与标准输入 token 相比，隐式缓存可为缓存的 token 提供 90% 的折扣。启用后，系统会自动将隐式缓存命中节省的费用返还给您。

隐式缓存将前缀存储在两个存储层中：

  • 内存缓存 ：缓存的前缀保留在内存中。内存容量有限，因此前缀会在容量回收时被逐出。
  • 持久缓存 ：当某个前缀从内存存储中逐出时，它会移至持久存储，而不是被舍弃。稍后重复使用该前缀的请求仍然可以命中缓存，这会提高在较长时间间隔内重复使用相同上下文的工作负载的缓存命中率。

这两个层默认处于启用状态。缓存的前缀会在创建后 24 小时内过期，大多数条目会更早被逐出。您可以停用持久缓存并保留内存缓存，也可以完全停用隐式缓存。如果您担心数据保留问题，请参阅零数据保留， 其中介绍了如何处理缓存的数据以及如何停用每个层。

如要提高隐式缓存命中的可能性，请执行以下操作：

  • 将较大且常见的内容放置在提示的开头。
  • 在短时间内发送具有相似前缀的请求。

支持的模型

受支持的 Gemini 模型支持隐式缓存，其中一部分模型支持持久缓存。

内存缓存

使用以下模型时，支持内存缓存：

点击即可展开支持的模型

持久缓存

使用以下模型时，支持持久缓存：

隐式缓存还支持开放模型。如需了解详情，请参阅 Agent Platform 的 MaaS 类开放模型。

显式缓存

显式缓存提供了更多的控制，并确保在引用现有上下文缓存的输入 token 可享受一定的折扣。对于 Gemini 2.5 或更高版本的模型，此折扣为 90%；对于 Gemini 2.0 模型，此折扣为 75%。

使用 Gemini Enterprise API，您可以执行以下任务：

您还可以使用 Gemini Enterprise API 来 检索有关上下文缓存的信息。

显式缓存会与隐式缓存相互影响，可能会导致超出指定内容的 额外缓存，当创建缓存时。如要防止缓存数据保留，可停用隐式缓存并避免创建显式缓存。如需了解详情，请参阅启用和停用缓存。

支持的模型

使用以下模型时，支持显式缓存：

点击即可展开支持的模型

应在何时使用上下文缓存

上下文缓存特别适合后续请求重复引用大量初始上下文的场景。

可以在对 Gemini API 发起的提示请求中使用缓存的上下文项（例如大量的文本，或者一个音频文件或视频文件）来生成输出。虽然请求可以在提示中使用同样的缓存内容，但也会包含每个提示独有的文本。例如，构成某个聊天对话的每个提示请求都可以包含引用一个视频的相同上下文缓存以及构成每轮聊天内容的独有文本。

对于以下应用场景，请考虑使用上下文缓存：

  • 有大量系统指令的聊天机器人
  • 对较长的视频文件进行的重复分析
  • 针对大型文档集的定期查询
  • 频繁的代码库分析或 bug 修复

预配吞吐量支持隐式和显式缓存 （预览版）。如需了解详情，请参阅预配吞吐量指南 。缓存适用于各种流量类型。例如，在使用预配吞吐量时创建的缓存也适用于 PayGo。

可用性

可在提供 Agent Platform 上的生成式 AI 的区域使用上下文缓存。如需了解详情，请参阅 Agent Platform 上的生成式 AI 位置。

限制

上下文缓存遵循下表中的限制：

上下文缓存限制

隐式缓存和显式缓存的缓存 token 数下限
  • Gemini 3（例外情况除外）和 Gemini 4 模型 ：4,096 个 token
  • Gemini 3.0 Flash 预览版、3.1 Pro 预览版、3.7 Flash 和 3.8 Flash（仅限隐式缓存） ：6,144 个 token
  • Gemini 2 系列模型 ：2,048 个 token

您可以使用 blob 或文本缓存的内容的大小上限

 10 MB

缓存创建后的最短到期时间

 1 分钟

缓存创建后的最长到期时间

 没有最长缓存时长限制

隐式缓存的前缀的最长生命周期

 最长 24 小时

智能体工作负载的缓存数据隔离和安全性

Google Cloud 使用您的项目编号来隔离缓存的数据，并且缓存的内容绝不会在项目之间共享。

为防止智能体工作负载中发生跨用户数据泄露，请将缓存的提示数据和输出限定在每个用户会话的范围内。当您运行后台智能体或多租户代理时，请将缓存边界与最终用户权限对齐，以便智能体无法跨用户重复使用缓存的凭据或数据。

VPC Service Controls 支持

上下文缓存支持 VPC Service Controls，这意味着您的缓存无法渗漏到服务边界之外。如果您使用 Cloud Storage 构建缓存，请将您的存储桶添加到服务边界中，以保护您的缓存内容。

如需了解详情，请参阅 Agent Platform 文档中的将 VPC Service Controls 与 Agent Platform 搭配使用 。

后续步骤