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.

Caching konteks di Firebase AI Logic

Untuk fitur AI, Anda dapat meneruskan token input (konten) yang sama berulang kali ke model. Untuk kasus penggunaan ini, Anda dapat meng-cache konten ini, yang berarti Anda meneruskan konten ke model sekali, menyimpannya, dan merujuknya dalam permintaan berikutnya.

Penyimpanan cache konteks dapat secara signifikan mengurangi latensi dan biaya untuk tugas berulang yang melibatkan sejumlah besar konten, seperti sejumlah besar teks, file audio, atau file video. Beberapa kasus penggunaan umum untuk konten yang di-cache mencakup dokumen persona yang mendetail, codebase, atau manual.

Model Gemini menawarkan dua mekanisme caching yang berbeda:

Caching implisit: diaktifkan secara otomatis di sebagian besar model, tidak ada jaminan penghematan biaya
Caching eksplisit: dapat diaktifkan secara opsional dan manual di sebagian besar model, biasanya menghasilkan penghematan biaya

Penyimpanan dalam cache secara eksplisit berguna jika Anda ingin lebih menjamin penghematan biaya, tetapi dengan beberapa pekerjaan tambahan untuk developer.

Untuk penyimpanan dalam cache implisit dan eksplisit, kolom cachedContentTokenCount dalam metadata respons Anda menunjukkan jumlah token di bagian input yang di-cache. Untuk caching eksplisit, pastikan untuk meninjau informasi harga di bagian bawah halaman ini.

Model yang didukung

Caching didukung saat menggunakan model berikut:

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

Model yang menghasilkan media (misalnya, model Nana Banana seperti gemini-3.1-flash-image-preview), tidak mendukung penyiapan cache konteks.

Batas ukuran konten yang di-cache

Setiap model memiliki persyaratan jumlah token minimum untuk konten yang di-cache. Nilai maksimum ditentukan oleh jendela konteks model.

Gemini Model Pro: minimal 4096 token
Gemini Model Flash: Minimal 1024 token

Selain itu, ukuran maksimum konten yang dapat Anda simpan dalam cache menggunakan blob atau teks adalah 10 MB.

Caching implisit

Caching implisit diaktifkan secara default dan tersedia untuk sebagian besar model Gemini.

Google secara otomatis meneruskan penghematan biaya jika permintaan Anda mencapai konten yang di-cache. Berikut beberapa cara untuk meningkatkan peluang permintaan Anda menggunakan caching implisit:

Coba letakkan konten yang besar dan umum di awal perintah Anda.
Coba kirim permintaan dengan awalan yang serupa dalam waktu singkat.

Jumlah token di bagian input yang di-cache diberikan di kolom cachedContentTokenCount dalam metadata respons.

Caching eksplisit

Caching eksplisit tidak diaktifkan secara default, dan merupakan kemampuan opsional model Gemini.

Berikut cara menyiapkan dan menggunakan cache konten vulgar:

Membuat lalu menggunakan cache eksplisit
Mengelola cache eksplisit, termasuk:

Perhatikan bahwa cache konten vulgar berinteraksi dengan cache implisit, yang berpotensi menghasilkan cache tambahan di luar konten yang di-cache secara eksplisit. Anda dapat mencegah retensi data cache dengan menonaktifkan penyimpanan dalam cache implisit dan tidak membuat cache eksplisit. Untuk mengetahui informasi selengkapnya, lihat Mengaktifkan dan menonaktifkan penyimpanan ke dalam cache.

Membuat dan menggunakan cache eksplisit

Membuat dan menggunakan cache konten eksplisit memerlukan hal berikut:

Buat cache eksplisit.
Merujuk cache dalam template perintah server.
Merujuk template perintah server dalam permintaan perintah dari aplikasi Anda.

Informasi penting tentang cara membuat dan menggunakan cache eksplisit

Cache Anda harus selaras dengan permintaan perintah aplikasi dan template perintah server Anda:

Cache ini khusus untuk penyedia Gemini API. Permintaan perintah aplikasi Anda harus menggunakan penyedia yang sama.
Untuk Firebase AI Logic, sebaiknya gunakan cache konten vulgar hanya dengan Vertex AI Gemini API. Semua informasi dan contoh di halaman ini khusus untuk penyedia Gemini API tersebut.
Cache ini khusus untuk model Gemini. Permintaan perintah aplikasi Anda harus menggunakan model yang sama.
Cache khusus untuk lokasi saat menggunakan Vertex AI Gemini API.
Lokasi untuk cache eksplisit harus cocok dengan lokasi template perintah server dan lokasi tempat Anda mengakses model dalam permintaan perintah aplikasi Anda.

Selain itu, perhatikan batasan dan persyaratan berikut untuk penyimpanan dalam cache eksplisit:

Setelah cache eksplisit dibuat, Anda tidak dapat mengubah apa pun tentang cache kecuali TTL atau waktu habis masa berlaku.
Anda dapat menyimpan dalam cache jenis MIME file input yang didukung atau bahkan hanya teks yang diberikan dalam permintaan pembuatan cache.
Jika Anda ingin menyertakan file dalam cache, Anda harus memberikan file sebagai URI Cloud Storage. Tidak boleh berupa URL browser atau URL YouTube.

Selain itu, batasan akses ke file diperiksa pada waktu pembuatan cache, dan batasan akses tidak diperiksa lagi pada waktu permintaan pengguna. Oleh karena itu, pastikan semua data yang disertakan dalam cache eksplisit cocok untuk semua pengguna yang membuat permintaan yang menyertakan cache tersebut.
Jika Anda ingin menggunakan petunjuk atau alat sistem (seperti eksekusi kode, konteks URL, atau perujukan dengan Google Penelusuran), maka cache itu sendiri harus berisi konfigurasinya. Mereka tidak dapat dikonfigurasi dalam template perintah server atau dalam permintaan perintah aplikasi Anda. Perhatikan bahwa template perintah server belum mendukung panggilan fungsi (atau chat). Untuk mengetahui detail cara mengonfigurasi petunjuk dan alat sistem dalam cache Anda, lihat REST API Vertex AI Gemini API.

Langkah 1: Buat cache

Buat cache dengan menggunakan REST API Vertex AI Gemini API secara langsung.

Berikut adalah contoh yang membuat cache eksplisit file PDF sebagai kontennya.

Sintaksis:

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

Contoh permintaan:

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

Contoh Respons:

Respons menyertakan name resource yang sepenuhnya memenuhi syarat dan unik secara global untuk cache (perhatikan bahwa segmen terakhir adalah ID cache). Anda akan menggunakan seluruh nilai name ini di langkah alur kerja berikutnya.

{
  "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"
}

Langkah 2: Merujuk cache dalam template perintah server

Setelah membuat cache, referensikan berdasarkan name dalam properti cachedContent dari template perintah server.

Pastikan Anda mengikuti persyaratan berikut saat membuat template perintah server:

Gunakan name resource yang sepenuhnya memenuhi syarat dari respons saat Anda membuat cache. Ini bukan nama tampilan opsional yang Anda tentukan dalam permintaan.
Lokasi untuk template perintah server harus cocok dengan lokasi cache.
Untuk menggunakan petunjuk atau alat sistem, petunjuk atau alat tersebut harus dikonfigurasi sebagai bagian dari cache dan bukan sebagai bagian dari template perintah server.

Sintaksis:

{{cachedContent name="YOUR_CACHE_RESOURCE_NAME"}}

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

Contoh:

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

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

Atau, nilai parameter name dalam template perintah server dapat berupa variabel input dinamis. Misalnya, {{cachedContent name=someVariable}} memungkinkan Anda menyertakan name cache sebagai input untuk permintaan dari aplikasi Anda.

Langkah 3: Merujuk template perintah server dalam permintaan dari aplikasi Anda

Berhati-hatilah dengan hal-hal berikut saat menulis permintaan Anda:

Gunakan Vertex AI Gemini API karena cache dibuat dengan penyedia Gemini API tersebut.
Lokasi tempat Anda mengakses model dalam permintaan perintah aplikasi Anda harus cocok dengan lokasi template perintah server dan cache.

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}");
}

Mengelola cache eksplisit

Bagian ini menjelaskan cara mengelola cache konten vulgar, termasuk cara mencantumkan semua cache, mendapatkan metadata tentang cache, memperbarui TTL atau waktu habis masa berlaku cache, dan menghapus cache.

Anda mengelola cache eksplisit menggunakan REST API Vertex AI Gemini API.

Setelah cache konten dewasa dibuat, Anda tidak dapat mengubah apa pun tentang cache, kecuali TTL atau waktu habis masa berlaku.

Mencantumkan semua cache

Anda dapat mencantumkan semua cache eksplisit yang tersedia untuk project Anda. Perintah ini hanya akan menampilkan cache di lokasi yang ditentukan.

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

Mendapatkan metadata tentang cache

Konten yang di-cache sebenarnya tidak dapat diambil atau dilihat. Namun, Anda dapat mengambil metadata tentang cache eksplisit, termasuk name, model, display_name, usage_metadata, create_time, update_time, dan expire_time.

Anda harus memberikan CACHE_ID, yang merupakan segmen terakhir dalam name resource yang sepenuhnya memenuhi syarat dari cache.

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}

Memperbarui TTL atau waktu habis masa berlaku untuk cache

Saat membuat cache eksplisit, Anda dapat secara opsional menetapkan ttl atau expire_time.

ttl: TTL (time-to-live) untuk cache, khususnya jumlah detik dan nanodetik yang digunakan cache setelah dibuat atau setelah ttl diperbarui sebelum habis masa berlakunya. Saat Anda menyetel ttl, expireTime cache akan otomatis diperbarui.
expire_time: Timestamp (seperti 2024-06-30T09:00:00.000000Z) yang menentukan tanggal dan waktu absolut saat cache berakhir.

Jika Anda tidak menetapkan salah satu nilai ini, TTL default adalah 1 jam. Tidak ada batas minimum atau maksimum pada TTL.

Untuk cache eksplisit yang ada, Anda dapat menambahkan atau memperbarui ttl atau expire_time. Anda harus memberikan CACHE_ID, yang merupakan segmen terakhir dalam name resource yang sepenuhnya memenuhi syarat dari cache.

Pembaruan 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'"
}'

Pembaruan 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'"
}'

Menghapus cache

Jika cache eksplisit tidak lagi diperlukan, Anda dapat menghapusnya.