上下文缓存

在典型的 AI 工作流中，您可能会反复将相同的输入令牌传递给模型。Gemini API 提供两种不同的缓存机制：

隐式缓存（自动，无法保证节省费用）
显式缓存（手动，保证节省费用）

默认情况下，Gemini 2.5 模型启用了隐式缓存。如果请求包含缓存命中的内容，我们会自动将节省的费用返还给您。

如果您希望保证节省费用，但需要增加一些开发者工作量，则显式缓存非常有用。

隐式缓存

默认情况下，系统会为所有 Gemini 2.5 模型启用隐式缓存。如果您的请求命中缓存，我们会自动将节省的费用返还给您。您无需执行任何操作即可启用此功能。自 2025 年 5 月 8 日起生效。上下文缓存的最小输入令牌数为 2.5 Flash 为 1,024，2.5 Pro 为 2,048。

如需提高隐式缓存命中的几率，请执行以下操作：

尝试将较大且常见的内容放在问题开头
尝试在短时间内发送前缀相似的请求

您可以在响应对象的 usage_metadata 字段中查看缓存命中 token 的数量。

显式缓存

使用 Gemini API 显式缓存功能，您可以将一些内容传递给模型一次，缓存输入 token，然后在后续请求中引用缓存的 token。在某些数据量下，使用缓存的令牌比重复传入同一令牌集更经济。

缓存一组令牌时，您可以选择缓存在令牌被自动删除之前存在的时长。此缓存时长称为存留时间 (TTL)。如果未设置，TTL 默认为 1 小时。缓存的开销取决于输入令牌的大小以及您希望令牌保留多长时间。

本部分假定您已安装 Gemini SDK（或已安装 curl），并且已配置 API 密钥，如快速入门中所示。

使用缓存生成内容

以下示例展示了如何使用缓存的系统指令和文本文件生成内容。

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

async function main() {
  const doc = await ai.files.upload({
    file: "path/to/file.txt",
    config: { mimeType: "text/plain" },
  });
  console.log("Uploaded file name:", doc.name);

  const modelName = "gemini-2.0-flash-001";
  const cache = await ai.caches.create({
    model: modelName,
    config: {
      contents: createUserContent(createPartFromUri(doc.uri, doc.mimeType)),
      systemInstruction: "You are an expert analyzing transcripts.",
    },
  });
  console.log("Cache created:", cache);

  const response = await ai.models.generateContent({
    model: modelName,
    contents: "Please summarize this transcript",
    config: { cachedContent: cache.name },
  });
  console.log("Response text:", response.text);
}

await main();

列出缓存

您无法检索或查看缓存的内容，但可以检索缓存元数据（name、model、displayName、usageMetadata、createTime、updateTime 和 expireTime）。

如需列出所有已上传缓存的元数据，请使用 GoogleGenAI.caches.list()：

console.log("My caches:");
const pager = await ai.caches.list({ config: { pageSize: 10 } });
let page = pager.page;
while (true) {
  for (const c of page) {
    console.log("    ", c.name);
  }
  if (!pager.hasNextPage()) break;
  page = await pager.nextPage();
}

更新缓存

您可以为缓存设置新的 ttl 或 expireTime。不支持更改缓存的任何其他内容。

以下示例展示了如何使用 GoogleGenAI.caches.update() 更新缓存的 ttl。

const ttl = `${2 * 3600}s`; // 2 hours in seconds
const updatedCache = await ai.caches.update({
  name: cache.name,
  config: { ttl },
});
console.log("After update (TTL):", updatedCache);

删除缓存

缓存服务提供了删除操作，用于手动从缓存中移除内容。以下示例展示了如何使用 GoogleGenAI.caches.delete() 删除缓存。

await ai.caches.delete({ name: cache.name });

何时使用显式缓存

上下文缓存特别适合较短的请求重复引用大量初始上下文的场景。例如，对于以下使用场景，可以考虑使用上下文缓存：

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

显式缓存如何降低费用

虽然上下文缓存是一项付费功能，但它的目的是为了降低整体的运营成本。结算取决于以下因素：

缓存词元数：缓存的输入词元数，如果相同的词元在后续提示中被重复使用，则按折扣费率计费。
存储时长：所缓存词元的存储时长 (TTL)，按缓存词元数的 TTL 时长计费。TTL 没有最小值或最大值。
其他因素：可能还会产生其他费用，例如非缓存输入词元和输出词元的费用。

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

其他注意事项

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

上下文缓存的最小输入令牌数为 2.5 Flash 版为 1,024，2.5 Pro 版为 2,048。上限与给定模型的上限相同。（如需详细了解如何统计令牌，请参阅令牌指南。）
该模型不会区分缓存的令牌和常规输入令牌。缓存的内容是提示的前缀。
上下文缓存没有特殊的速率或使用限制；适用 GenerateContent 的标准速率限制，并且令牌限制包括缓存的令牌。
缓存的令牌数量会在缓存服务的创建、获取和列表操作的 usage_metadata 中返回，在使用缓存时也会在 GenerateContent 中返回。