Firebase AI Logic 中的脈絡快取

對於 AI 功能，您可能會重複將相同的輸入權杖 (內容) 傳遞至模型。對於這些用途，您可以改為快取這類內容，也就是一次將內容傳遞至模型、儲存內容，並在後續要求中參照該內容。

對於涉及大量內容的重複性工作 (例如大量文字、音訊檔案或影片檔案)，內容快取可大幅減少延遲和成本。快取內容的常見用途包括詳細的人物誌文件、程式碼集或手冊。

Gemini 模型提供兩種不同的快取機制：

  • 隱含快取：自動在大多數機型上啟用，不保證可節省費用

  • 明確快取： 大多數模型都可手動啟用這項功能，通常可節省成本

如果您想盡可能確保節省費用，但願意增加開發人員的工作量，則可使用明確快取。

無論是隱含或明確快取，回應中繼資料的 cachedContentTokenCount 欄位都會指出輸入內容快取部分的權杖數量。如要使用明確快取，請務必查看本頁底部的定價資訊。

支援的模型

使用下列模型時，系統支援快取：

  • gemini-3.1-pro-preview
  • gemini-3-flash-preview
  • gemini-3.1-flash-lite-preview
  • gemini-2.5-pro
  • gemini-2.5-flash
  • gemini-2.5-flash-lite

生成媒體的模型 (例如 Nana Banana 模型，如 gemini-3.1-flash-image-preview)「不」支援內容快取。

快取內容大小限制

每個模型都有快取內容的最低權杖數要求。上限取決於模型的脈絡窗口。

  • Gemini Pro 模型：至少 4096 個權杖
  • Gemini Flash 模型：至少 1024 個權杖

此外，使用 blob 或文字快取內容的大小上限為 10 MB。


隱含快取

系統預設會啟用隱式快取功能，適用於大多數 Gemini 模型。

如果要求命中快取內容，Google 會自動將節省的費用轉移給您。以下提供幾種方法，提高要求使用隱含快取的機率：

  • 請嘗試在提示開頭放入大型且常見的內容。
  • 請嘗試在短時間內傳送具有類似前置字串的要求。

輸入內容快取部分的權杖數量會顯示在回應中繼資料的 cachedContentTokenCount 欄位。


明確快取

「明確快取」預設為「未」啟用，而且是 Gemini 模型的可選功能。

以下說明如何設定及使用露骨內容快取：

請注意，明確快取內容會與隱含快取互動，可能導致明確快取內容以外的額外快取。如要避免系統保留快取資料，請停用隱含快取，且不要建立明確快取。詳情請參閱「啟用及停用快取」。


建立及使用明確快取

如要建立及使用煽情露骨內容快取，必須符合下列條件：

  1. 建立明確的快取。

  2. 在伺服器提示範本中參照快取。

  3. 在應用程式的提示要求中參照伺服器提示範本。

建立及使用明確快取的重要資訊

快取必須與應用程式的提示要求和伺服器提示範本一致：

  • 快取僅適用於 Gemini API 供應商。 應用程式的提示要求必須使用相同的供應商。
    對於 Firebase AI Logic，我們強烈建議您僅搭配 Vertex AI Gemini API 使用明確內容快取。本頁的所有資訊和範例都與該 Gemini API 供應商有關。

  • 快取僅適用於 Gemini 模型。應用程式的提示要求必須使用相同的模型。

  • 使用 Vertex AI Gemini API 時，快取會與特定位置相關聯。
    明確快取的位置必須與伺服器提示範本的位置 和您在應用程式提示要求中存取模型的位置相符。

此外，也請注意下列明確快取限制和需求：

  • 建立明確快取後，除了 TTL 或到期時間，您無法變更快取的任何項目。

  • 您可以快取任何支援的輸入檔案 MIME 類型，甚至是快取建立要求中提供的文字。

  • 如要在快取中加入檔案，必須以 Cloud Storage URI 提供檔案。不得為瀏覽器網址或 YouTube 網址。

    此外，系統會在快取建立時間檢查檔案的存取限制，且不會在使用者要求時間再次檢查存取限制。因此，請確保明確快取中包含的任何資料，都適合任何提出包含該快取要求的使用者。

  • 如要使用系統指令或工具 (例如程式碼執行、網址內容或透過 Google 搜尋建立基準)，快取本身必須包含這些設定。無法在伺服器提示範本或應用程式的提示要求中設定。請注意，伺服器提示範本尚未支援函式呼叫 (或即時通訊)。如要瞭解如何在快取中設定系統指令和工具，請參閱 Vertex AI Gemini API 的 REST API。

步驟 1：建立快取

直接使用 Vertex AI Gemini API 的 REST API 建立快取。

以下範例會建立 PDF 檔案的明確快取，做為檔案內容。

語法：

PROJECT_ID="PROJECT_ID"
MODEL_ID="GEMINI_MODEL"  # for example, gemini-3-flash-preview
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-flash-preview"
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-flash-preview",
  "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：在應用程式的要求中參照伺服器提示範本

撰寫要求時，請務必注意下列事項：

  • 由於快取是使用該 Gemini API 提供者建立，因此請使用 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}");
}


管理明確快取

本節說明如何管理明確內容快取，包括如何列出所有快取、取得快取的中繼資料、更新快取的存留時間或到期時間，以及刪除快取。

您可以使用 Vertex AI Gemini API 的 REST API 管理明確快取。

建立露骨內容快取後，除了 TTL 或到期時間，您無法變更快取的任何設定。

列出所有快取

您可以列出專案可用的所有明確快取。這項指令只會傳回指定位置的快取。

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 或 expire_time。

  • ttl：快取的存留時間 (TTL)，具體來說，是指快取在建立或 ttl 更新後，到期前可存活的秒數和奈秒數。設定 ttl 時，快取會自動更新。expireTime

  • expire_time：Timestamp (例如 2024-06-30T09:00:00.000000Z)，指定快取到期的絕對日期和時間。

如未設定這兩個值，預設存留時間為 1 小時。存留時間沒有上下限。

如果是現有的明確快取，您可以新增或更新 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}


明確快取的價格

明確快取是一項付費功能，可降低費用。定價方式取決於下列因素：

  • 用於建立快取的輸入詞元：無論是隱含或明確快取，系統都會按照標準輸入詞元價格，針對用於建立快取的輸入詞元向您收費。

  • 快取儲存：如果是明確快取，儲存時間長度也會影響儲存費用。隱含快取不會產生儲存空間費用。詳情請參閱Vertex AI Gemini API的定價。

  • 使用快取內容：明確快取可確保在參照明確快取時享有折扣，也就是說，當輸入權杖參照現有快取時，您可享有折扣。如果是 Gemini 2.5 以上機型，折扣為 90%。

輸入內容快取部分的權杖數量會顯示在回應中繼資料的 cachedContentTokenCount 欄位。