AI 機能では、同じ入力トークン（コンテンツ）をモデルに繰り返し渡すことがあります。このようなユースケースでは、このコンテンツをキャッシュに保存できます。つまり、コンテンツをモデルに一度渡して保存し、後続のリクエストで参照します。
コンテキスト キャッシュを使用すると、大量のテキスト、音声ファイル、動画ファイルなど、大量のコンテンツを伴う反復タスクのレイテンシと費用を大幅に削減できます。キャッシュに保存されたコンテンツの一般的なユースケースには、詳細なペルソナ ドキュメント、コードベース、マニュアルなどがあります。
Gemini モデルには、次の 2 つの異なるキャッシュ保存メカニズムがあります。
暗黙的なキャッシュ: ほとんどのモデルで自動的に有効になりますが、費用削減は保証されません。
明示的なキャッシュ保存: ほとんどのモデルで任意で手動で有効にできます。通常、費用を削減できます。
明示的なキャッシュ保存は、コスト削減をより確実に保証したい場合に役立ちますが、開発者の作業が追加されます。
暗黙的なキャッシュ保存と明示的なキャッシュ保存の両方で、レスポンスのメタデータの cachedContentTokenCount フィールドは、入力のキャッシュに保存された部分のトークン数を示します。明示的なキャッシュ保存については、このページの下部にある料金情報を必ずご確認ください。
サポートされているモデル
次のモデルを使用する場合、キャッシュ保存がサポートされます。
gemini-3.1-pro-previewgemini-3-flash-previewgemini-3.1-flash-litegemini-2.5-progemini-2.5-flashgemini-2.5-flash-lite
メディア生成モデル（gemini-3.1-flash-image-preview などの Nana Banana モデルなど）は、コンテキスト キャッシュ保存をサポートしていません。
キャッシュに保存されたコンテンツのサイズ上限
各モデルには、キャッシュに保存されたコンテンツの最小トークン数の要件があります。最大値はモデルのコンテキスト ウィンドウによって決まります。
- Gemini Pro モデル: 最小 4,096 トークン
- Gemini Flash モデル: 最小 1,024 トークン
また、blob またはテキストを使用してキャッシュに保存できるコンテンツの最大サイズは 10 MB です。
暗黙的なキャッシュ保存
暗黙的なキャッシュ保存はデフォルトで有効になっています。ほとんどの Gemini モデルで使用できます。
リクエストがキャッシュに保存されたコンテンツにヒットした場合、Google は自動的にコスト削減を適用します。リクエストで暗黙的なキャッシュ保存が使用される可能性を高める方法は次のとおりです。
- 大規模で一般的なコンテンツは、プロンプトの先頭に配置してみてください。
- 類似した接頭辞を含むリクエストを短時間で送信しようとします。
入力のキャッシュに保存された部分のトークン数は、レスポンスのメタデータの cachedContentTokenCount フィールドで確認できます。
明示的なキャッシュ保存
明示的なキャッシュ保存はデフォルトでは有効になっていません。これは Gemini モデルのオプション機能です。
露骨なコンテンツのキャッシュを設定して使用する方法は次のとおりです。
明示的なキャッシュを管理します。これには以下が含まれます。
明示的なコンテンツ キャッシュは暗黙的なキャッシュと相互作用し、明示的にキャッシュに保存されたコンテンツを超えて追加のキャッシュ保存が行われる可能性があります。暗黙的なキャッシュ保存を無効にし、明示的なキャッシュを作成しないことで、キャッシュ データの保持を防ぐことができます。詳細については、キャッシュ保存を有効または無効にするをご覧ください。
明示的なキャッシュを作成して使用する
露骨な表現を含むコンテンツのキャッシュを作成して使用するには、次のものが必要です。
明示的なキャッシュの作成と使用に関する重要な情報
キャッシュは、アプリのプロンプト リクエストとサーバーのプロンプト テンプレートに沿ったものにする必要があります。
キャッシュは Gemini API プロバイダに固有です。アプリのプロンプト リクエストでは、同じプロバイダを使用する必要があります。
Firebase AI Logic の場合は、明示的なコンテンツ キャッシュを Vertex AI Gemini API でのみ使用することを強くおすすめします。このページの情報と例は、その Gemini API プロバイダに固有のものです。キャッシュは Gemini モデルに固有です。アプリのプロンプト リクエストでは、同じモデルを使用する必要があります。
Vertex AI Gemini API を使用する場合、キャッシュは特定の場所に固有です。
明示的なキャッシュのロケーションは、アプリのプロンプト リクエストのサーバー プロンプト テンプレートのロケーションとモデルにアクセスするロケーションと一致する必要があります。
また、明示的なキャッシュ保存には次の制限事項と要件があります。
明示的なキャッシュを作成すると、TTL または有効期限を除き、キャッシュに関する変更は一切できなくなります。
サポートされている入力ファイル MIME タイプをキャッシュに保存できます。また、キャッシュ作成リクエストで指定されたテキストのみをキャッシュに保存することもできます。
ファイルをキャッシュに含める場合は、Cloud Storage URI としてファイルを提供する必要があります。ブラウザの URL や YouTube の URL は使用できません。
また、ファイルのアクセス制限は cache-creation-time にチェックされ、user-request-time にアクセス制限が再度チェックされることはありません。そのため、明示的なキャッシュに含まれるデータは、そのキャッシュを含むリクエストを行うすべてのユーザーに適していることを確認してください。
システム指示やツール（コード実行、URL コンテキスト、
Google Search によるグラウンディング、Google Maps によるグラウンディングなど）を使用する場合は、キャッシュ自体にそれらの構成が含まれている必要があります。サーバー プロンプト テンプレートやアプリのプロンプト リクエストで構成することはできません。サーバー プロンプト テンプレートは、関数呼び出し（またはチャット）をまだサポートしていません。キャッシュ内のシステム指示とツールを構成する方法の詳細については、Vertex AI Gemini API の REST API をご覧ください。
ステップ 1: キャッシュを作成する
次の例では、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}");
}
明示的なキャッシュを管理する
このセクションでは、明示的なコンテンツ キャッシュの管理について説明します。これには、すべてのキャッシュを一覧表示する方法、キャッシュに関するメタデータを取得する方法、キャッシュの TTL または有効期限を更新する方法、キャッシュを削除する方法が含まれます。
明示的なキャッシュは、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 などの明示的なキャッシュに関するメタデータは取得できます。
キャッシュの完全修飾リソース name の最後のセグメントである CACHE_ID を指定する必要があります。
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 を追加または更新できます。キャッシュの完全修飾リソース name の最後のセグメントである CACHE_ID を指定する必要があります。
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'"
}'
キャッシュを削除する
明示的なキャッシュが不要になった場合は、削除できます。
キャッシュの完全修飾リソース name の最後のセグメントである CACHE_ID を指定する必要があります。
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 フィールドで確認できます。