The latest Gemini models, like Gemini 3.1 Flash Image (Nano Banana 2), are available to use with Firebase AI Logic! Learn more.

Gemini 2.0 Flash and Flash-Lite models will shut down on June 1, 2026. To avoid service disruption, update to a newer model like gemini-2.5-flash-lite. Learn more.

All Imagen models will shut down on June 24, 2026. Learn about migrating your apps to use Nano Banana.

Firebase AI Logic のコンテキストキャッシュ保存

AI 機能では、同じ入力トークン（コンテンツ）をモデルに何度も渡すことがあります。このようなユースケースでは、このコンテンツをキャッシュに保存できます。つまり、コンテンツをモデルに1 回だけ渡して保存し、以降のリクエストで参照します。

コンテキストキャッシュを使用すると、大量のテキスト、音声ファイル、動画ファイルなど、 大量のコンテンツを含む反復タスクのレイテンシと費用を大幅に削減できます。キャッシュに保存されたコンテンツの一般的なユースケースとしては、詳細なペルソナドキュメント、コードベース、マニュアルなどがあります。

Gemini モデルには、次の 2 つの異なるキャッシュメカニズムがあります。

暗黙的なキャッシュ: ほとんどのモデルで__自動的に有効になりますが、費用削減は保証されません。
明示的なキャッシュ保存: ほとんどのモデルで 任意で __手動で有効にできます。通常、費用を削減できます。

明示的なキャッシュ保存は、費用削減をより確実に保証したい場合に便利ですが、デベロッパーの作業が追加されます。

暗黙的なキャッシュ保存と明示的なキャッシュ保存の両方で、レスポンスのメタデータの 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

メディア生成モデル（gemini-3.1-flash-image-preview などの Nana Banana モデル）は、コンテキストキャッシュ保存をサポートしていません。

キャッシュに保存されたコンテンツのサイズ上限

各モデルには、キャッシュに保存されたコンテンツのトークン数の 最小要件があります。最大値は、モデルのコンテキストウィンドウによって決まります。

Gemini Pro モデル: 最小 4,096 トークン
Gemini Flash モデル: 最小 1,024 トークン

また、BLOB またはテキストを使用してキャッシュに保存できるコンテンツの最大サイズは 10 MB です。

暗黙的なキャッシュ保存

暗黙的なキャッシュ保存はデフォルトで有効 になっており、ほとんどの Gemini モデルで使用できます。

リクエストがキャッシュに保存されたコンテンツにヒットした場合、Google は自動的に費用削減を適用します。リクエストで暗黙的なキャッシュ保存を使用する可能性を高める方法は次のとおりです。

大規模で一般的なコンテンツは、プロンプトの先頭に配置します。
類似した接頭辞を含むリクエストを短時間で送信します。

入力のキャッシュに保存された部分のトークン数は、レスポンスのメタデータの cachedContentTokenCount フィールドに表示されます。

明示的なキャッシュ保存

明示的なキャッシュ保存はデフォルトでは有効になっていません__。これは、Gemini モデルのオプション機能です。

重要: Firebase AI Logic では、サーバーのプロンプトテンプレート を使用する場合にのみ、明示的な コンテンツキャッシュにアクセスできます。

また、Firebase AI Logicでは、明示的なコンテンツキャッシュの作成と管理時にGemini APIキーを使用したり、誤って公開したりする心配がないように、Vertex AI Gemini APIで明示的なコンテンツキャッシュを使用することを強くおすすめします。

Note that Firebase AI Logic は明示的なキャッシュ保存ワークフローの改善に取り組んでいます。この機能に関心がある場合は、既存の User Voice エントリに賛成票を投じて、リソースを集中させるべき分野であることをお知らせください。

明示的なコンテンツキャッシュを設定して使用する方法は次のとおりです。

明示的なキャッシュを作成して使用する
明示的なキャッシュを管理する（次の操作を含む）

明示的なコンテンツキャッシュは暗黙的なキャッシュ保存と連携するため、明示的にキャッシュに保存されたコンテンツ以外にもキャッシュ保存が行われる可能性があります。キャッシュデータの保持を防ぐには、暗黙的なキャッシュ保存を無効にし、明示的なキャッシュを作成しないようにします。詳細については、キャッシュ保存を有効または無効にするをご覧ください。

明示的なキャッシュを作成して使用する

明示的なコンテンツキャッシュを作成して使用するには、次のものが必要です。

明示的なキャッシュを作成する。
サーバーのプロンプトテンプレートでキャッシュを参照する。
アプリからのプロンプトリクエストでサーバーのプロンプトテンプレートを参照する。

明示的なキャッシュの作成と使用に関する重要な情報

キャッシュは、アプリのプロンプトリクエストとサーバーのプロンプトテンプレートに沿っている必要があります。

キャッシュは Gemini API プロバイダに固有のものです。アプリのプロンプトリクエストでは、同じプロバイダを使用する必要があります。
Firebase AI Logic では、明示的なコンテンツキャッシュを Vertex AI Gemini API でのみ使用することを強くおすすめします。このページのすべての情報と例は、そのGemini APIプロバイダに固有のものです。
キャッシュは Gemini モデルに固有のものです。アプリのプロンプトリクエストでは、同じモデルを使用する必要があります。
キャッシュは、 Vertex AI Gemini APIを使用する場合、ロケーションに固有のものです。
明示的なキャッシュのロケーションは、サーバーのプロンプトテンプレートのロケーションと、アプリのプロンプトリクエストでモデルにアクセスするロケーションと一致する必要があります。

また、明示的なキャッシュ保存には次の制限事項と要件があります。

明示的なキャッシュを作成した後は、TTL または有効期限を除き、キャッシュを変更することはできません。
サポートされている入力ファイル MIME タイプ、またはキャッシュ作成リクエストで指定されたテキストのみをキャッシュに保存できます。
ファイルをキャッシュに含める場合は、ファイルとして Cloud Storage URI を指定する必要があります。ブラウザの URL や YouTube の URL は使用できません。

また、ファイルへのアクセス制限は キャッシュの作成時にチェックされます。ユーザーリクエスト時にはアクセス制限は チェックされません。そのため、明示的なキャッシュに含まれるデータは、そのキャッシュを含むリクエストを行うすべてのユーザーに適していることを確認してください。
システム命令やツール（コード実行、URL コンテキスト、Google 検索でのグラウンディングなど）を使用する場合は、キャッシュ自体にそれらの構成を含める必要があります。サーバーのプロンプトテンプレートやアプリのプロンプトリクエストで構成することはできません。サーバーのプロンプトテンプレートは、関数呼び出し（またはチャット）をまだサポートしていません。キャッシュでシステム命令とツールを構成する方法について詳しくは、 REST API の Vertex AI Gemini APIをご覧ください。

ステップ 1: キャッシュを作成する

の REST API を直接使用してキャッシュを作成しますVertex AI Gemini 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 property of a server prompt template内で name を参照します。

サーバーのプロンプトテンプレートを作成する際は、次の要件を満たしてください。

キャッシュを作成したときにレスポンスから取得した完全修飾リソース name を使用します。これは、リクエストで指定したオプションの表示名ではありません。not
サーバーのプロンプトテンプレートのロケーションは、キャッシュのロケーションと一致する必要があります。
システム命令やツールを使用するには、サーバーのプロンプトテンプレートの一部としてではなく、キャッシュの一部として構成する必要があります。

構文:

{{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 または有効期限の更新、およびキャッシュの削除が含まれます。

明示的なキャッシュは、 REST API を使用して管理しますVertex AI Gemini 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 または有効期限を更新する

明示的なキャッシュを作成するときに、必要に応じて 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'"
}'

キャッシュを削除する

明示的なキャッシュが不要になった場合は、削除できます。