Caching konteks di Firebase AI Logic

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

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

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 pada sebagian besar model, biasanya menghasilkan penghematan biaya

Caching eksplisit berguna jika Anda ingin lebih menjamin penghematan biaya, tetapi dengan beberapa pekerjaan developer tambahan.

Untuk caching 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-4-argon (hanya penyimpanan dalam cache implisit; penyimpanan dalam cache eksplisit tidak didukung)
  • gemini-3.8-flash
  • gemini-3.5-flash-lite (dan gemini-3.1-flash-lite yang lebih lama)

Model Gemini 3.x Flash penggunaan umum yang lebih lama mendukung kemampuan ini, tetapi tidak lagi direkomendasikan untuk digunakan karena tanggal penonaktifan yang akan datang dan/atau perutean otomatis ke model yang lebih baru.

Model pembuat media (misalnya, model Gemini Nano Banana seperti gemini-nano-banana-2.1) tidak mendukung cache konteks.

Batas ukuran konten yang di-cache

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

  • Gemini 4 Argon: minimum 4.096 token (Gemini Developer API) atau minimum 6.144 token (Agent Platform Gemini API (formerly Vertex AI))
  • Model Gemini Pro: minimum 4.096 token
  • Model Gemini Flash: minimum 1.024 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 memberikan 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 disediakan di kolom cachedContentTokenCount dalam metadata respons.


Caching eksplisit

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

Perhatikan bahwa model gemini-4-argon tidak mendukung caching eksplisit.

Berikut cara menyiapkan dan menggunakan cache konten vulgar:

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


Membuat dan menggunakan cache eksplisit

Untuk membuat dan menggunakan cache konten eksplisit, diperlukan hal berikut:

  1. Membuat cache eksplisit.

  2. Mereferensikan cache dalam template perintah server.

  3. Mereferensikan 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 dialog aplikasi Anda harus menggunakan penyedia yang sama.
    Untuk Firebase AI Logic, sebaiknya gunakan cache konten eksplisit hanya dengan Agent Platform Gemini API (formerly Vertex AI). 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 bersifat spesifik untuk suatu lokasi saat menggunakan Agent Platform Gemini API (formerly Vertex AI).
    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 caching eksplisit:

  • Setelah cache eksplisit dibuat, Anda tidak dapat mengubah apa pun tentang cache tersebut, kecuali TTL atau waktu habis masa berlaku.

  • Anda dapat meng-cache jenis MIME file input yang didukung atau bahkan hanya teks yang disediakan dalam permintaan pembuatan cache.

  • Jika ingin menyertakan file dalam cache, Anda harus menyediakan file sebagai URI Cloud Storage. URL ini 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 sesuai untuk setiap pengguna yang membuat permintaan yang menyertakan cache tersebut.

  • Jika Anda ingin menggunakan petunjuk atau alat sistem (seperti eksekusi kode, konteks URL, Grounding dengan Google Search, atau Grounding dengan Google Maps), cache itu sendiri harus berisi konfigurasinya. Parameter ini tidak dapat dikonfigurasi di template perintah server atau dalam permintaan perintah aplikasi Anda. Perhatikan bahwa template perintah server belum mendukung panggilan fungsi (atau chat). Untuk mengetahui detail tentang cara mengonfigurasi petunjuk dan alat sistem di cache Anda, lihat REST API Agent Platform Gemini API (formerly Vertex AI).

Langkah 1: Membuat cache

Buat cache dengan langsung menggunakan REST API Agent Platform Gemini API (formerly Vertex AI).

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

Sintaksis:

PROJECT_ID="PROJECT_ID"
MODEL_ID="GEMINI_MODEL"  # for example, gemini-3.8-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

Contoh permintaan:

PROJECT_ID="my-amazing-app"
MODEL_ID="gemini-3.8-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

Contoh Respons:

Responsnya 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 berikutnya dalam alur kerja.

{
  "name": "projects/861083271981/locations/global/cachedContents/4545031458888089601",
  "model": "projects/my-amazing-app/locations/global/publishers/google/models/gemini-3.8-flash",
  "createTime": "2024-06-04T01:11:50.808236Z",
  "updateTime": "2024-06-04T01:11:50.808236Z",
  "expireTime": "2024-06-04T02:11:50.794542Z"
}

Langkah 2: Mereferensikan cache dalam template perintah server

Setelah membuat cache, referensikan cache tersebut 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: Referensikan template perintah server dalam permintaan dari aplikasi Anda

Berhati-hatilah dengan hal berikut saat menulis permintaan Anda:

  • Gunakan Agent Platform Gemini API (formerly Vertex AI) 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 Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
let model = FirebaseAI.firebaseAI(backend: .agentPlatform(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 Agent Platform Gemini API backend service (formerly Vertex AI).
// 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.agentPlatform(location = "LOCATION"))
                        .templateGenerativeModel()

val response = model.generateContent(
    // Specify your template ID.
    "TEMPLATE_ID",
)

val text = response.text
println(text)

Java 

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance(GenerativeBackend.agentPlatform("LOCATION"))
      .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 Agent Platform Gemini API backend service (formerly Vertex AI).
// Make sure to specify the same location as the server prompt template and the cache.
const ai = getAI(app, { backend: new AgentPlatformBackend('LOCATION') });

// Create a `TemplateGenerativeModel` instance
const model = getTemplateGenerativeModel(ai);

const result = await model.generateContent({
  // Specify your template ID.
  templateId: 'TEMPLATE_ID',
  templateVariables: {},
});

const response = result.response;
const text = response.text();

Dart 

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
var _model = FirebaseAI.agentPlatform(location: 'LOCATION').templateGenerativeModel();

var response = await _model.generateContent(
        // Specify your template ID.
        'TEMPLATE_ID',
        inputs: {},
      );

var text = response?.text;
print(text);

Unity 

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Make sure to specify the same location as the server prompt template and the cache.
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.AgentPlatform(location: "LOCATION"));

// Create a `TemplateGenerativeModel` instance.
var model = firebaseAI.GetTemplateGenerativeModel();

try
{
  var response = await model.GenerateContentAsync(
      // Specify your template ID.
      "TEMPLATE_ID",
      new Dictionary<string, object>()
  );
  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 eksplisit, 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 Agent Platform Gemini API (formerly Vertex AI).

Setelah cache konten eksplisit dibuat, Anda tidak dapat mengubah apa pun tentang cache tersebut 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 menetapkan ttl atau expire_time secara opsional.

  • ttl: TTL (time-to-live) untuk cache, khususnya jumlah detik dan nanodetik cache aktif setelah dibuat atau setelah ttl diperbarui sebelum masa berlakunya habis. Saat Anda menetapkan 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 defaultnya 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.

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

Perbarui 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.

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 DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}


Harga untuk caching eksplisit

Caching eksplisit adalah fitur berbayar yang dirancang untuk mengurangi biaya. Harga didasarkan pada faktor-faktor berikut:

  • Token input untuk pembuatan cache: Untuk caching implisit dan eksplisit, Anda akan ditagih untuk token input yang digunakan untuk membuat cache dengan harga token input standar.

  • Penyimpanan cache: Untuk caching eksplisit, ada juga biaya penyimpanan berdasarkan durasi penyimpanan cache. Tidak ada biaya penyimpanan untuk caching implisit. Untuk mengetahui informasi selengkapnya, lihat harga untuk Agent Platform Gemini API (formerly Vertex AI).

  • Penggunaan konten yang di-cache: Cache eksplisit memastikan diskon saat cache eksplisit direferensikan, yang berarti Anda mendapatkan diskon untuk token input saat token tersebut mereferensikan cache yang ada. Untuk model Gemini 2.5 dan yang lebih baru, diskon ini sebesar 90%.

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