Firebase AI Logic 中的上下文缓存

对于 AI 功能，您可能会反复将相同的输入令牌（内容）传递给模型。对于这些使用情形，您可以改为缓存此内容，也就是说，您只需将内容传递给模型一次，然后存储该内容，并在后续请求中引用该内容。

对于涉及大量内容（例如大量文本、音频文件或视频文件）的重复性任务，上下文缓存可以显著缩短延迟时间并降低费用。缓存内容的一些常见应用场景包括详细的角色文档、代码库或手册。

Gemini 模型提供两种不同的缓存机制：

  • 隐式缓存：在大多数模型上自动启用，但无法保证节省费用

  • 显式缓存：可在大多数型号上选择性手动启用，通常可节省费用

如果您希望更可靠地保证节省费用，但需要增加一些开发者工作，那么显式缓存会很有用。

无论是隐式缓存还是显式缓存，回答的元数据中的 cachedContentTokenCount 字段均表示输入中已缓存部分的 token 数。对于显式缓存，请务必查看本页面底部的价格信息。

支持的模型

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

  • gemini-3.1-pro-preview
  • gemini-3.6-flash（以及较旧的 gemini-3.5-flash）
  • gemini-3.5-flash-lite（以及较旧的 gemini-3.1-flash-lite）

通用 Gemini 2.5 模型支持此功能，但均已弃用。

生成媒体的模型（例如“Nana Banana”模型，如 gemini-3.1-flash-image）不支持上下文缓存。

缓存内容大小限制

每种模型对缓存内容都有最低 token 数量要求。最大值取决于模型的上下文窗口。

  • Gemini Pro 模型：至少 4,096 个 token
  • Gemini Flash 模型：至少 1024 个词元

此外，您可以使用 blob 或文本缓存的内容的大小上限为 10 MB。


隐式缓存

默认情况下，系统会启用隐式缓存，并且该功能适用于大多数 Gemini 型号。

如果您的请求命中缓存的内容，Google 会自动将节省的费用转给您。以下是一些可提高请求使用隐式缓存的几率的方法：

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

输入的缓存部分中的 token 数量在回答的元数据中的 cachedContentTokenCount 字段中提供。


显式缓存

显式缓存默认处于停用状态，是 Gemini 模型的可选功能。

您可以按以下步骤设置和使用露骨内容缓存：

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


创建和使用显式缓存

创建和使用露骨内容缓存需要满足以下条件：

  1. 创建显式缓存。

  2. 在服务器提示模板中引用缓存。

  3. 在应用的提示请求中引用服务器提示模板。

有关创建和使用显式缓存的重要信息

缓存必须与应用的提示请求和服务器提示模板保持一致：

  • 缓存特定于 Gemini API 提供方。应用的提示请求必须使用相同的提供方。
    对于 Firebase AI Logic，我们强烈建议仅将显式内容缓存与 Agent Platform Gemini API (formerly Vertex AI) 搭配使用。本页上的所有信息和示例均专门针对该 Gemini API 提供商。

  • 缓存特定于 Gemini 模型。 应用的提示请求必须使用相同的模型。

  • 使用 Agent Platform Gemini API (formerly Vertex AI) 时，缓存特定于某个位置。
    显式缓存的位置必须与服务器提示模板的位置以及应用提示请求中访问模型的位置相匹配。

另请注意以下有关显式缓存的限制和要求：

  • 创建显式缓存后，您无法更改缓存的任何内容，TTL 或过期时间除外。

  • 您可以缓存任何受支持的输入文件 MIME 类型，甚至可以只缓存缓存创建请求中提供的文本。

  • 如果您想在缓存中包含某个文件，必须以 Cloud Storage URI 的形式提供该文件。不得为浏览器网址或 YouTube 网址。

    此外，系统会在创建缓存时检查对文件的访问限制，而不会在用户请求时再次检查访问限制。因此，请确保显式缓存中包含的任何数据都适合发出包含该缓存的请求的任何用户。

  • 如果您想使用系统指令或工具（例如代码执行、网址上下文、依托 Google Search 进行接地或依托 Google Maps 进行接地），则缓存本身必须包含这些指令或工具的配置。这些参数无法在服务器提示模板或应用的提示请求中进行配置。请注意，服务器提示模板尚不支持函数调用（或聊天）。如需详细了解如何在缓存中配置系统指令和工具，请参阅 Agent Platform Gemini API (formerly Vertex AI) 的 REST API。

第 1 步：创建缓存

通过直接使用 Agent Platform Gemini API (formerly Vertex AI) 的 REST API 来创建缓存。

以下示例会创建一个 PDF 文件的显式缓存作为其内容。

Cloud Shell

语法：

PROJECT_ID="PROJECT_ID"
MODEL_ID="GEMINI_MODEL"  # for example, gemini-3.6-flash
LOCATION="LOCATION"  # location for both the cache and the model
MIME_TYPE="MIME_TYPE"
CACHED_CONTENT_URI="CLOUD_STORAGE_FILE_URI"  # must be a Cloud Storage URI
CACHE_DISPLAY_NAME="CACHE_DISPLAY_NAME"  # optional
TTL="CACHE_TIME_TO_LIVE"  # optional (if not specified, defaults to 3600s)

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents \
-d @- <<EOF
{
  "model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "${MIME_TYPE}",
            "fileUri": "${CACHED_CONTENT_URI}"
          }
        }
      ]
    }
  ],
  "displayName": "${CACHE_DISPLAY_NAME}",
  "ttl": "${TTL}"
}
EOF

示例请求：

PROJECT_ID="my-amazing-app"
MODEL_ID="gemini-3.6-flash"
LOCATION="global"
MIME_TYPE="application/pdf"
CACHED_CONTENT_URI="gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf"
CACHE_DISPLAY_NAME="Gemini - A Family of Highly Capable Multimodal Model (PDF)"
TTL="7200s"

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents \
-d @- <<EOF
{
  "model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "${MIME_TYPE}",
            "fileUri": "${CACHED_CONTENT_URI}"
          }
        }
      ]
    }
  ],
  "displayName": "${CACHE_DISPLAY_NAME}",
  "ttl": "${TTL}"
}
EOF

示例回答：

响应包含一个完全限定的资源 name，该资源在缓存中具有全局唯一性（请注意，最后一个段是缓存 ID）。您将在工作流程的下一步中使用整个 name 值。

{
  "name": "projects/861083271981/locations/global/cachedContents/4545031458888089601",
  "model": "projects/my-amazing-app/locations/global/publishers/google/models/gemini-3.6-flash",
  "createTime": "2024-06-04T01:11:50.808236Z",
  "updateTime": "2024-06-04T01:11:50.808236Z",
  "expireTime": "2024-06-04T02:11:50.794542Z"
}

第 2 步：在服务器提示模板中引用缓存

创建缓存后，在服务器提示模板的 cachedContent 属性中通过 name 引用该缓存。

创建服务器提示模板时，请务必遵循以下要求：

  • 使用创建缓存时响应中的完全限定资源 name。这不是您在请求中指定的可选显示名称。

  • 服务器提示模板的位置必须与缓存的位置一致。

  • 如需使用系统指令或工具，必须将其配置为缓存的一部分，而不是服务器提示模板的一部分。

语法：

{{cachedContent name="YOUR_CACHE_RESOURCE_NAME"}}

{{role "user"}}
{{userPrompt}}

示例：

{{cachedContent name="projects/861083271981/locations/global/cachedContents/4545031458888089601"}}

{{role "user"}}
{{userPrompt}}

或者，服务器提示模板中 name 参数的值可以是动态输入变量。例如，{{cachedContent name=someVariable}} 可让您将缓存的 name 作为应用请求的输入内容。

第 3 步：在应用发出的请求中引用服务器提示模板

在撰写请求时，请务必注意以下事项：

  • 使用 Agent Platform Gemini API (formerly Vertex AI)，因为缓存是使用该 Gemini API 提供方创建的。

  • 应用提示请求中访问模型的位置必须与服务器提示模板和缓存的位置一致。

Swift

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
let model = FirebaseAI.firebaseAI(backend: .vertexAI(location: "LOCATION"))
                                  .templateGenerativeModel()

do {
    let response = try await model.generateContent(
        // Specify your template ID
        templateID: "TEMPLATE_ID"
    )
    if let text = response.text {
        print("Response Text: \(text)")
    }
} catch {
    print("An error occurred: \(error)")
}
print("\n")

Kotlin 

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
val model = Firebase.ai(backend = GenerativeBackend.vertexAI(location = "LOCATION"))
                        .templateGenerativeModel()

val response = model.generateContent(
    // Specify your template ID
    "TEMPLATE_ID",
)

val text = response.text
println(text)

Java 

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance().templateGenerativeModel();

TemplateGenerativeModelFutures model = TemplateGenerativeModelFutures.from(generativeModel);

Future<GenerateContentResponse> response = model.generateContent(
    // Specify your template ID
    "TEMPLATE_ID"
);
addCallback(response,
      new FutureCallback<GenerateContentResponse>() {
          public void onSuccess(GenerateContentResponse result) {
            System.out.println(result.getText());
          }
          public void onFailure(Throwable t) {
            reportError(t);
          }
    }
executor);

Web 

// ...

// Initialize the Vertex AI Gemini API backend service
// Make sure to specify the same location as the server prompt template and the cache
const ai = getAI(app, { backend: new VertexAIBackend('LOCATION') });

// Create a `TemplateGenerativeModel` instance
const model = getTemplateGenerativeModel(ai);

const result = await model.generateContent(
  // Specify your template ID
  'TEMPLATE_ID'
);

const response = result.response;
const text = response.text();

Dart 

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
var _model = FirebaseAI.vertexAI(location: 'LOCATION').templateGenerativeModel()

var response = await _model.generateContent(
        // Specify your template ID
        'TEMPLATE_ID',
      );

var text = response?.text;
print(text);

Unity 

// ...

// Initialize the Vertex AI Gemini API backend service
// Make sure to specify the same location as the server prompt template and the cache
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.VertexAI(location: "LOCATION"));

// Create a `TemplateGenerativeModel` instance
var model = firebaseAI.GetTemplateGenerativeModel();

try
{
  var response = await model.GenerateContentAsync(
      // Specify your template ID
      "TEMPLATE_ID"
  );
  Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
  Debug.LogError($"An error occurred: {e.Message}");
}


管理显式缓存

本部分介绍了如何管理显式内容缓存，包括如何列出所有缓存、获取有关缓存的元数据、更新缓存的 TTL 或过期时间，以及删除缓存。

您可以使用 Agent Platform Gemini API (formerly Vertex AI) 的 REST API 管理显式缓存。

创建显式内容缓存后，您无法更改缓存的任何内容，TTL 或过期时间除外。

Cloud Shell

列出所有缓存

您可以列出适用于您项目的所有显式缓存。此命令只会返回指定位置中的缓存。

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"

curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents

获取有关缓存的元数据

无法检索或查看实际的缓存内容。不过，您可以检索有关显式缓存的元数据，包括 name、model、display_name、usage_metadata、create_time、update_time 和 expire_time。

您需要提供 CACHE_ID，即缓存的完全限定资源 name 中的最后一段。

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache

curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}

更新缓存的 TTL 或失效时间

创建显式缓存时，您可以选择设置 ttl 或 expire_time。

  • ttl：缓存的 TTL（存留时间），具体是指缓存自创建或 ttl 更新后到过期前的存留时间（以秒和纳秒为单位）。当您设置 ttl 时，缓存的 expireTime 会自动更新。

  • expire_time：一个 Timestamp（例如 2024-06-30T09:00:00.000000Z），用于指定缓存过期时的绝对日期和时间。

如果您未设置这两个值中的任何一个，则默认 TTL 为 1 小时。TTL 没有最小值或最大值限制。

对于现有的显式缓存，您可以添加或更新 ttl 或 expire_time。 您需要提供 CACHE_ID，即缓存的完全限定资源 name 中的最后一段。

更新 ttl

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache
TTL="CACHE_TIME_TO_LIVE"

curl \
-X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID} -d \
'{
  "ttl": "'$TTL'"
}'

更新 expire_time

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache
EXPIRE_TIME="ABSOLUTE_TIME_CACHE_EXPIRES"

curl \
-X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID} -d \
'{
  "expire_time": "'$EXPIRE_TIME'"
}'

删除缓存

不再需要显式缓存时，您可以将其删除。

您需要提供 CACHE_ID，即缓存的完全限定资源 name 中的最后一段。

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache

curl \
-X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}


显式缓存的价格

显式缓存是一项付费功能，旨在降低费用。价格取决于以下因素：

  • 用于创建缓存的输入 token：无论是隐式缓存还是显式缓存，您都需要按标准输入 token 价格支付用于创建缓存的输入 token 费用。

  • 缓存存储：对于显式缓存，还会根据缓存的存储时长收取存储费用。隐式缓存不收取存储费用。如需了解详情，请参阅 Agent Platform Gemini API (formerly Vertex AI) 的价格。

  • 缓存内容的使用：显式缓存可确保在引用显式缓存时享受折扣，这意味着当输入 token 引用现有缓存时，您可享受折扣。对于 Gemini 2.5 及更高版本的模型，此折扣为 90%。

输入的缓存部分中的 token 数量在回答的元数据中的 cachedContentTokenCount 字段中提供。