對於 AI 功能，您可能會重複將相同的輸入權杖 (內容) 傳遞至模型。在這些情況下，您可以快取這類內容，也就是一次將內容傳遞至模型、儲存內容，並在後續要求中參照該內容。
脈絡快取功能可大幅減少延遲，並降低涉及大量內容的重複性工作成本，例如大量文字、音訊檔案或影片檔案。快取內容的常見用途包括詳細的人物誌文件、程式碼集或手冊。
Gemini 模型提供兩種不同的快取機制：
如果您想盡可能節省費用，但願意多花一些開發人員心力，明確快取就非常實用。
無論是隱含或明確快取，回應中繼資料的 cachedContentTokenCount 欄位都會指出輸入內容快取部分的權杖數量。如要使用明確快取，請務必查看本頁底部的定價資訊。
支援的模型
使用下列模型時，系統支援快取：
gemini-3.1-pro-previewgemini-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)「不」支援內容快取。
快取內容大小限制
每個模型對快取內容都有最低詞元數要求。上限取決於模型的脈絡窗口。
- Gemini Pro 模型：至少 4096 個權杖
- Gemini Flash 模型：至少 1024 個權杖
此外，使用 Blob 或文字快取內容的大小上限為 10 MB。
隱含快取
系統預設會啟用隱式快取功能，適用於大多數Gemini模型。
如果要求命中快取內容，Google 會自動將節省的費用轉移給您。以下提供幾種方法，可提高要求使用隱含快取的機率：
- 請嘗試在提示開頭放入大型且常見的內容。
- 請嘗試在短時間內傳送具有類似前置字串的要求。
輸入內容快取部分的權杖數量會顯示在回應中繼資料的 cachedContentTokenCount 欄位。
明確快取
明確快取不會預設啟用，而且是 Gemini 模型的選用功能。
以下說明如何設定及使用露骨內容快取：
管理明確快取，包括：
請注意，明確快取內容會與隱含快取互動，可能導致除了明確快取內容以外的額外快取。您可以停用隱含快取，並避免建立明確快取，防止系統保留快取資料。詳情請參閱「啟用及停用快取」。
建立及使用明確快取
如要建立及使用煽情露骨內容快取，必須符合下列條件：
建立及使用明確快取的重要資訊
快取必須與應用程式的提示要求和伺服器提示詞範本保持一致：
快取僅適用於 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 檔案的明確快取，做為檔案內容。
語法：
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：在應用程式的要求中參照伺服器提示詞範本
撰寫要求時，請務必注意下列事項：
由於快取是使用該 Gemini API 提供者建立，因此請使用 Agent Platform Gemini API (formerly Vertex AI)。
應用程式提示要求中存取模型的位置，必須與伺服器提示範本和快取的位置相符。
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}");
}
管理明確快取
本節說明如何管理露骨內容快取，包括如何列出所有快取、取得快取的中繼資料、更新快取的存留時間或到期時間，以及刪除快取。
您可以使用 Agent Platform Gemini API (formerly Vertex AI) 的 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}
明確快取的價格
明確快取是付費功能，可降低成本。定價依據下列因素：
用於建立快取的輸入權杖：無論是隱含或明確快取，系統都會按照標準輸入權杖價格，針對用於建立快取的輸入權杖向您收費。
快取儲存：如果是明確快取，儲存時間長度也會影響儲存費用。隱含快取不會產生儲存空間費用。詳情請參閱 Agent Platform Gemini API (formerly Vertex AI) 的定價。
使用快取內容：明確快取可確保在參照明確快取時享有折扣，也就是說，當輸入權杖參照現有快取時，您可享有折扣。如果是 Gemini 2.5 以上機型，折扣為 90%。
輸入內容快取部分的權杖數量會顯示在回應中繼資料的 cachedContentTokenCount 欄位。