gemini-3
Gemini 3 上下文缓存：何时用、如何验收
Gemini3 Team · 2026年10月14日 · 12 分钟阅读
同一份资料被反复发送，才值得考虑缓存
假设团队针对同一本产品手册提出二十个不同问题。如果每次请求都附上完整手册，就会重复传入大量相同内容。当资料体量较大、版本稳定且会被反复使用时，上下文缓存值得评估；如果每次处理的都是不同的短文档，缓存未必是最值得优先做的优化。
本文面向 Gemini API 使用者，以原创的手册审阅场景和流程图说明如何做判断。示例没有实测节省比例，也不承诺更快响应，更不代表 MidassAI Chat 中存在某个缓存开关。第三方聊天服务可能采用自己的上下文处理方式，应另外核对其说明。
先确认你实际使用哪套 API。 Google 当前的 Interactions 缓存文档说明了隐式缓存；generateContent 缓存文档还介绍了受支持的 Gemini 3 和 2.5 模型如何使用显式缓存对象。不要把显式缓存的接入步骤直接套进 Interactions。
不同问题之间，哪些内容应保持一致？
图中的蓝色部分代表同一版本的手册，旁边的 Q1、Q2、Q3 代表不同问题。可复用的请求通常把共同资料放在前面，把每次变化的问题放在后面。这个图解释的是请求组织方式，并不保证一定命中隐式缓存。
共享上下文应经过整理：包括手册正文、版本标识，以及真正适用于每个问题的说明。避免在稳定内容前面插入不断变化的时间戳、随机编号或无关问候。日志追踪编号若不参与推理，就保留在应用日志中，不必加入模型输入。
优化之前，先回答三个问题：资料在本轮审阅中会不会变化？每位使用者是否都有权阅读全部资料？每个答案能不能追溯到具体版本？只要其中一点不明确，就应先整理来源和访问权限，再考虑减少重复 Token。
两种缓存机制，管理责任不同
| 判断项 | 隐式缓存 | 显式缓存 |
|---|---|---|
| 谁管理缓存对象？ | 应用无需自行创建对象 | 应用负责创建并引用缓存 |
| 相似请求能否保证复用？ | 不能，要查看实际用量 | 要核对缓存引用和返回用量 |
| 采用哪套 API？ | 按当前 API 的缓存文档接入 | 使用支持显式缓存的 generateContent 模型和方法 |
| 需要规划什么？ | 稳定前缀和用量观察 | 来源版本、有效期、清理和完整成本 |
官方文档说明，Gemini 2.5 及更新模型默认启用隐式缓存，但具体模型有相应的最低输入要求。它建议把共同内容放在开头，并在较短时间内发送相似前缀。这里的门槛按 Token 计算，不等于字数或文件大小；不要假定所有 Gemini 3 型号的限制相同。
显式缓存还需要管理资源生命周期。当前 generateContent 文档指出，未指定 TTL 时默认有效期为一小时，并区分了缓存输入、存储时长和其他请求费用。理解这些计费组成，并不意味着已经知道最终账单；接入时仍需核对所用模型和 API 的具体规则。
用一次有明确结束时间的手册审阅来规划
下面是可复现的规划示例，不是生产环境的测试记录。团队准备审阅第 7 版手册，预计开展一次短期讨论，分别询问入职流程的变化、需要审批的例外情况，以及问题上报流程所在的位置。
如果采用隐式缓存，每次请求保持同一段稳定的资料前缀，只改变后面的具体问题，并记录每次响应返回的用量。内容相似只是复用机会，是否真正复用，要以用量信息为准。
如果采用支持显式缓存的 generateContent 集成，可按以下顺序实施：
- 整理已获准使用的手册版本，并用相应工具计算 Token 数。
- 创建资源前，核对模型是否支持缓存以及具体限制。
- 选择适合本轮任务的有效期，创建缓存，并保存缓存标识、模型和来源版本。
- 提问时引用该缓存，确保使用的模型与缓存一致。
- 记录返回用量，并逐项对照手册检查答案。
- 审阅结束后删除缓存，或按已规划的有效期自动过期。
这些步骤必须由应用程序实现；自然语言提示词不能自行创建或管理缓存。API 凭据应留在服务端，不得写入文章、浏览器端代码或分析日志。
资料换版，不能只延长旧缓存
生命周期图把版本变化作为重新建立上下文的原因。Google 的 generateContent 文档允许修改缓存的到期时间或 TTL，却不允许直接修改缓存内容。如果第 8 版手册改变了答案，就应创建新的已审核上下文，并停止把新问题发给旧版本。
应用可以把缓存标识与来源校验和、准确的模型、创建时间、到期时间和访问范围关联起来。这是应用侧的记录建议，不是 Gemini API 承诺提供的字段列表。人类可读的显示名称也不能保证唯一对应正确资料。
缓存清理与文档保留是两件事。删除缓存，并不能证明上传的源文件、本地副本和日志都已删除；每个位置都要遵守自己的保留规则。官方文档允许读取缓存元数据，却不能将缓存内容当作资料归档重新下载，因此权威源文件仍应由现有文档系统管理。
对比整轮任务的成本，而不是单个好看的数字
决定是否保留显式缓存前，先准备一张小型评估表。固定来源版本、问题集和模型，记录真实用量与持续时间，不预设一个节省百分比。
| 记录内容 | 作用 |
|---|---|
| 准确的 API、模型和来源版本 | 确保两轮测试可比较 |
| 实际提问次数 | 衡量真实复用程度，而非预计需求 |
| 缓存与未缓存的输入用量 | 看清哪些输入被复用 |
| 输出用量 | 输入缓存并不免除生成答案的工作 |
| 缓存有效期和存储费用 | 长时间闲置可能改变成本结论 |
| 答案核验及失败记录 | 用错版本时，低成本也没有意义 |
按你的账户、模型和 API 当时适用的规则计算总额，包含适用的缓存创建或输入处理费用、存储时长、未缓存的问题 Token，以及输出费用。再与相同任务、不自行管理显式缓存的方案比较。基准方案也可能命中隐式缓存，因此未查看实际用量前，不应把它称为“完全未缓存”。
本文不列固定价格表，因为价格和模型可用性都可能变化。实际评估时，请查阅官方价格页面。
哪些情况下，先优化别的环节？
一次性的短问题、持续变动的资料集合，或者缺乏可靠版本记录的项目，通常更值得先改善输入选择。删掉无关页面、拆分独立任务，并先检查答案质量。不要为了达到缓存门槛而刻意填长提示词，这可能抵消优化的意义。
如果缓存中途过期，应明确处理错误，重新加载原本要使用的资料版本，并判断剩余任务是否值得重新创建缓存。不要悄悄换成其他文档，也不要反复重试已经失效的引用。保留用户的问题，方便恢复任务。
缓存复用的是输入，不会替你验证答案，也不会扩大模型允许的上下文窗口。如果结果还要交给下游程序读取，可以配合结构化输出验收流程一起使用：资料组织与结果校验，分别解决可靠性问题的不同部分。