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 mereferensikannya dalam permintaan berikutnya.

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

Gemini model menawarkan dua mekanisme caching yang berbeda:

• Implicit caching: otomatis diaktifkan di sebagian besar model, tidak ada penghematan biaya yang dijamin

• Explicit caching: dapat diaktifkan secara opsional dan manual di sebagian besar model, biasanya menghasilkan penghematan biaya

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

Untuk implicit caching dan explicit caching, kolom cachedContentTokenCount dalam metadata respons Anda menunjukkan jumlah token di bagian input yang di-cache. Untuk explicit caching, 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.6-flash (dan gemini-3.5-flash yang lebih lama)
• gemini-3.5-flash-lite (dan gemini-3.1-flash-lite yang lebih lama)

Model Gemini 2.5 penggunaan umum mendukung kemampuan ini, tetapi semuanya tidak digunakan lagi.Gemini 2.5

Model penghasil media (misalnya, model "Nana Banana" seperti gemini-3.1-flash-image), tidak mendukung context caching.

Batas ukuran konten yang di-cache

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

• Gemini Model Pro: minimum 4.096 token
• Gemini Model Flash: minimum 1.024 token

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

Implicit caching

Implicit caching diaktifkan secara default dan tersedia untuk sebagian besar Gemini model.

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

• Coba tempatkan konten 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.

Explicit caching

Explicit caching tidak diaktifkan secara default, dan merupakan kemampuan opsional dari model Gemini.

Berikut cara menyiapkan dan menggunakan cache konten eksplisit:

• Membuat lalu menggunakan cache eksplisit

• Mengelola cache eksplisit, termasuk:

  • Mencantumkan semua cache

  • Mendapatkan metadata tentang cache

  • Memperbarui TTL atau waktu habis masa berlaku cache

  • Menghapus cache

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

Membuat dan menggunakan cache eksplisit

Membuat dan menggunakan cache konten eksplisit memerlukan 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 pembuatan dan penggunaan cache eksplisit

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

• Cache khusus untuk penyedia Gemini API. Permintaan perintah 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 khusus untuk model Gemini. Permintaan perintah aplikasi Anda harus menggunakan model yang sama.

• Cache khusus untuk 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.

Selain itu, perhatikan batasan dan persyaratan berikut untuk explicit caching:

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

• Anda dapat menyimpan dalam 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 Cloud Storage URI. File tersebut 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 data apa pun yang disertakan dalam cache eksplisit sesuai untuk 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. Konfigurasi tersebut 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 tentang cara mengonfigurasi petunjuk dan alat sistem di cache, lihat REST API dari Agent Platform Gemini API (formerly Vertex AI).

Langkah 1: Membuat cache

Buat cache dengan menggunakan REST API Agent Platform Gemini API (formerly Vertex AI)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.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

Contoh permintaan:

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

Contoh Respons:

Respons tersebut 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 pada langkah berikutnya dalam alur kerja.

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

Langkah 2: Mereferensikan cache dalam template perintah server

Setelah membuat cache, referensikan cache tersebut berdasarkan name dalam properti cachedContent 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: Mereferensikan 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 harus cocok dengan lokasi template perintah server dan cache.

// ...

// 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")

// ...

// 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)

// ...

// 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);

// ...

// 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();

// ...

// 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);

// ...

// 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 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

Anda tidak dapat mengambil atau melihat konten yang di-cache sebenarnya. 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 cache yang sepenuhnya memenuhi syarat.

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 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 berakhir. 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 masa berlaku 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 cache yang sepenuhnya memenuhi syarat.

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

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

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}