上下文缓存

Python Node.js

在典型的 AI 工作流中，您可能会将相同的输入令牌反复传递给模型。使用 Gemini API 上下文缓存功能，您可以将一些内容传递给模型一次，缓存输入令牌，然后引用缓存的令牌以用于后续请求。在某些数量下，使用缓存的令牌比重复传入同一语料库的令牌更低的费用（并且延迟更低）。

缓存一组令牌时，您可以选择在令牌自动删除之前缓存存在的时长。此缓存时长称为存留时间 (TTL)。缓存的费用取决于输入令牌大小以及您希望令牌保留的时长。

上下文缓存支持 Gemini 1.5 Pro 和 Gemini 1.5 Flash。

何时使用上下文缓存

上下文缓存特别适用于通过较短请求重复引用大量初始上下文的情况。对于以下用例，请考虑使用上下文缓存：

• 提供详尽的系统说明的聊天机器人
• 重复分析冗长的视频文件
• 对大型文档集的周期性查询
• 频繁分析代码库或修复 bug

缓存如何降低费用

上下文缓存是一项付费功能，旨在降低总体运营费用。 结算取决于以下因素：

1. 缓存令牌计数：已缓存的输入令牌的数量，包含在后续提示中时按优惠费率计费。
2. 存储时长：缓存令牌的存储时间 (TTL)，根据缓存令牌计数的 TTL 时长计费。TTL 没有上下限。
3. 其他因素：会产生其他费用，例如未缓存的输入令牌和输出令牌。

如需了解最新的价格详情，请参阅 Gemini API 价格页面。如需了解如何统计令牌数量，请参阅令牌指南。

如何使用上下文缓存

本部分假定您已安装 Gemini SDK 并配置了 API 密钥，如quickstart中所示。

其他注意事项

使用上下文缓存时，请注意以下事项：

• 上下文缓存的输入词元数量下限为 32768，且最大值与给定模型的最大值相同。如需详细了解如何统计令牌，请参阅令牌指南。
• 您可以为缓存设置存留时间 (TTL)，如示例代码所示。如果未设置，TTL 默认为 1 小时。
• 模型对缓存的令牌和常规输入令牌没有任何区别。缓存的内容只是提示的前缀。
• 缓存服务提供删除操作，用于从缓存中手动移除内容。如需了解详情，请参阅所选 SDK 的文档。
• 对于付费层级，上下文缓存没有特殊速率或使用限制；GenerateContent 的标准速率限制适用，令牌限制包括缓存的令牌。对于免费层级，Gemini 1.5 Flash 的存储上限为 100 万个令牌，并且 Gemini 1.5 Pro 不支持缓存。
• 您无法检索或查看缓存的内容，但可以检索元数据（name、display_name、model 以及创建、更新和过期时间）。
• 可以设置新的 ttl 或 expire_time。不支持更改关于缓存内容的任何其他信息。
• 缓存令牌的数量会在缓存服务的创建、获取和列出操作中返回 usage_metadata，使用缓存时也会在 GenerateContent 中返回。