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'te bağlamı önbelleğe alma

Yapay zeka özelliğiniz için aynı giriş jetonlarını (içerik) tekrar tekrar bir modele iletebilirsiniz. Bu kullanım alanlarında, bu içeriği önbelleğe alabilirsiniz. Yani içeriği modele bir kez iletir, depolar ve sonraki isteklerde buna başvurursunuz.

Bağlam önbelleğe alma, büyük miktarda içerik içeren tekrarlayan görevlerde (ör. büyük miktarda metin, ses dosyası veya video dosyası) gecikmeyi ve maliyeti önemli ölçüde azaltabilir. Önbelleğe alınmış içeriklerin yaygın kullanım alanlarından bazıları şunlardır: ayrıntılı karakter belgeleri, kod tabanları veya kılavuzlar.

Gemini modelleri iki farklı önbelleğe alma mekanizması sunar:

Örtülü önbelleğe alma: Çoğu modelde otomatik olarak etkinleştirilir, maliyet tasarrufu garanti edilmez.
Açık önbelleğe alma: Çoğu modelde isteğe bağlı ve manuel olarak etkinleştirilebilir. Genellikle maliyet tasarrufu sağlar.

Açık önbelleğe alma, maliyet tasarrufunu daha olası hale getirmek istediğiniz durumlarda faydalıdır ancak geliştiricinin biraz daha fazla çalışması gerekir.

Hem örtülü hem de açık önbelleğe alma için yanıtınızın meta verilerindeki cachedContentTokenCount alanı, girişinizin önbelleğe alınan bölümündeki jeton sayısını gösterir. Açık önbelleğe alma için bu sayfanın alt kısmındaki fiyatlandırma bilgilerini incelediğinizden emin olun.

Desteklenen modeller

Aşağıdaki modeller kullanılırken önbelleğe alma desteklenir:

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

Medya oluşturan modeller (ör. gemini-3.1-flash-image-preview gibi Nana Banana modelleri), bağlam önbelleğe almayı desteklemez.

Önbelleğe alınan içerik boyutu sınırları

Her modelin, önbelleğe alınmış içerik için minimum jeton sayısı koşulu vardır. Maksimum değer, modelin bağlam penceresi tarafından belirlenir.

Gemini Pro modelleri: En az 4.096 jeton
Gemini Flash modelleri: En az 1.024 jeton

Ayrıca, blob veya metin kullanarak önbelleğe alabileceğiniz içeriğin maksimum boyutu 10 MB'tır.

Örtülü önbelleğe alma

Örtülü önbelleğe alma varsayılan olarak etkindir ve çoğu Gemini modelinde kullanılabilir.

İsteğiniz önbelleğe alınmış içeriğe isabet ederse Google, maliyet tasarruflarını otomatik olarak aktarır. İsteğinizin örtülü önbelleğe alma özelliğini kullanma olasılığını artırmanın bazı yolları şunlardır:

Büyük ve yaygın içerikleri isteminizin başına eklemeyi deneyin.
Kısa süre içinde benzer öneklere sahip istekler göndermeyi deneyin.

Girişinizin önbelleğe alınmış bölümündeki jeton sayısı, yanıtın meta verilerindeki cachedContentTokenCount alanında sağlanır.

Açık önbelleğe alma

Açıkça önbelleğe alma varsayılan olarak etkin değildir ve Gemini modellerinin isteğe bağlı bir özelliğidir.

Uygunsuz içerik önbelleklerini nasıl ayarlayacağınız ve kullanacağınız aşağıda açıklanmıştır:

Açık önbellek oluşturma ve kullanma
Aşağıdakiler dahil olmak üzere açık önbellekleri yönetin:

Uygunsuz içerik önbelleklerinin, örtülü önbelleğe alma ile etkileşime girdiğini ve bu durumun, açıkça önbelleğe alınmış içeriğin ötesinde ek önbelleğe almaya yol açabileceğini unutmayın. Örtülü önbelleğe almayı devre dışı bırakarak ve açık önbellek oluşturmayarak önbellek verilerinin saklanmasını önleyebilirsiniz. Daha fazla bilgi için Önbelleğe almayı etkinleştirme ve devre dışı bırakma başlıklı makaleyi inceleyin.

Açık önbellek oluşturma ve kullanma

Uygunsuz içerik önbelleği oluşturmak ve kullanmak için aşağıdakiler gerekir:

Açık bir önbellek oluşturun.
Sunucu istemi şablonunda önbelleğe referans verin.
Uygulamanızdan gelen bir istem isteğinde sunucu istem şablonuna referans verin.

Açık önbellek oluşturma ve kullanmayla ilgili önemli bilgiler

Önbelleğiniz, uygulamanızın istem istekleriyle ve sunucu istem şablonunuzla uyumlu olmalıdır:

Önbellek, Gemini API sağlayıcısına özgüdür. Uygulamanızın istem isteği aynı sağlayıcıyı kullanmalıdır.
Firebase AI Logic için, açık içerik önbelleklerini yalnızca Vertex AI Gemini API ile birlikte kullanmanızı önemle tavsiye ederiz. Bu sayfadaki tüm bilgiler ve örnekler söz konusu Gemini API sağlayıcısına özeldir.
Önbellek, Gemini modeline özgüdür. Uygulamanızın istem isteği aynı modeli kullanmalıdır.
Vertex AI Gemini API kullanılırken önbellek konuma özeldir.
Açık önbelleğin konumu, uygulamanızın istem isteğindeki sunucu istem şablonunun konumu ve<0x0x0A>modele eriştiğiniz konumla eşleşmelidir.

Ayrıca, açıkça önbelleğe alma ile ilgili aşağıdaki sınırlamaları ve koşulları göz önünde bulundurun:

Açık önbellek oluşturulduktan sonra, TTL veya son kullanma tarihi dışında önbellekle ilgili hiçbir şeyi değiştiremezsiniz.
Herhangi bir desteklenen giriş dosyası MIME türünü veya yalnızca önbellek oluşturma isteğinde sağlanan metni önbelleğe alabilirsiniz.
Önbelleğe bir dosya eklemek istiyorsanız dosyayı Cloud Storage URI'si olarak sağlamanız gerekir. Tarayıcı URL'si veya YouTube URL'si olamaz.

Ayrıca, dosyaya erişim kısıtlamaları cache-creation-time'da kontrol edilir ve access restrictions are not checked again at user-request-time. Bu nedenle, açık önbelleğe dahil edilen tüm verilerin, bu önbelleği içeren bir istekte bulunan tüm kullanıcılar için uygun olduğundan emin olun.
Sistem talimatlarını veya araçlarını (ör. kod yürütme, URL bağlamı ya da Google Arama ile temellendirme) kullanmak istiyorsanız önbelleğin kendisi bu talimatların veya araçların yapılandırmalarını içermelidir. Bu parametreler, sunucu istem şablonunda veya uygulamanızın istem isteğinde yapılandırılamaz. Sunucu istemi şablonlarının işlev çağrısını (veya sohbeti) henüz desteklemediğini unutmayın. Önbelleğinizde sistem talimatlarını ve araçlarını yapılandırma hakkında ayrıntılı bilgi için Vertex AI Gemini API REST API'sini inceleyin.

1. adım: Önbelleği oluşturun

Doğrudan Vertex AI Gemini API REST API'sini kullanarak önbelleği oluşturun.

Aşağıda, içeriği bir PDF dosyası olan açık bir önbellek oluşturan bir örnek verilmiştir.

Söz dizimi:

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

Örnek istek:

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

Örnek Yanıt:

Yanıt, önbellek için genel olarak benzersiz olan tam nitelikli bir kaynak name içerir (son segmentin önbellek kimliği olduğunu unutmayın). Bu name değerinin tamamını iş akışının sonraki adımında kullanacaksınız.

{
  "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. adım: Sunucu istemi şablonunda önbelleğe referans verin

Önbelleği oluşturduktan sonra, name ile cachedContent özelliğinde sunucu istemi şablonuna referans verin.

Sunucu istemi şablonunuzu oluştururken aşağıdaki koşulları karşıladığınızdan emin olun:

Önbelleği oluşturduğunuzda yanıttaki tam nitelikli kaynağı name kullanın. Bu, istekte belirttiğiniz isteğe bağlı görünen ad değildir.
Sunucu istemi şablonunun konumu, önbelleğin konumuyla eşleşmelidir.
Sistem talimatlarını veya araçlarını kullanmak için bunların önbelleğin bir parçası olarak yapılandırılması ve sunucu istemi şablonunun bir parçası olmaması gerekir.

Söz dizimi:

{{cachedContent name="YOUR_CACHE_RESOURCE_NAME"}}

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

Örnek:

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

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

Alternatif olarak, sunucu istemi şablonundaki name parametresinin değeri dinamik giriş değişkeni olabilir. Örneğin, {{cachedContent name=someVariable}}, uygulamanızdan gelen istek için giriş olarak önbelleğin name öğesini eklemenize olanak tanır.

3. adım: Uygulamanızdan gelen istekte sunucu istemi şablonuna referans verin

İsteğinizi yazarken aşağıdakilere çok dikkat edin:

Önbellek bu Vertex AI Gemini API sağlayıcısıyla oluşturulduğundan Gemini API kullanın.
Uygulamanızın istem isteğinde modele eriştiğiniz konum, sunucu istem şablonunun ve önbelleğin konumuyla eşleşmelidir.

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

Açık önbellekleri yönetme

Bu bölümde, tüm önbellekleri listeleme, önbellekle ilgili meta verileri alma, önbelleğin TTL'sini veya geçerlilik bitiş süresini güncelleme ve önbelleği silme dahil olmak üzere uygunsuz içerik önbelleklerini yönetme açıklanmaktadır.

Açık önbellekleri Vertex AI Gemini API'nin REST API'si ile yönetirsiniz.

Açık içerik önbelleği oluşturulduktan sonra, TTL veya geçerlilik süresi dışında önbellekle ilgili hiçbir şeyi değiştiremezsiniz.

Tüm önbellekleri listeleme

Projeniz için kullanılabilen tüm açık önbellekleri listeleyebilirsiniz. Bu komut yalnızca belirtilen konumdaki önbellekleri döndürür.

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

Önbellek hakkında meta veri alma

Önbelleğe alınan gerçek içeriği almak veya görüntülemek mümkün değildir. Ancak name, model, display_name, usage_metadata, create_time, update_time ve expire_time dahil olmak üzere açık bir önbellekle ilgili meta verileri alabilirsiniz.

Önbelleğin tam nitelikli kaynak name öğesinin son segmenti olan CACHE_ID değerini sağlamanız gerekir.

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}

Önbelleğin TTL'sini veya son kullanma süresini güncelleme

Açık önbellek oluşturduğunuzda isteğe bağlı olarak ttl veya expire_time değerini ayarlayabilirsiniz.

ttl: Önbelleğin geçerlilik süresi (TTL), özellikle önbelleğin oluşturulduktan sonra veya ttl güncellendikten sonra sona ermeden önce geçerli olduğu saniye ve nanosaniye sayısı. ttl ayarladığınızda önbelleğin expireTime otomatik olarak güncellenir.
expire_time: Önbelleğin geçerliliğinin sona ereceği mutlak tarih ve saati belirten bir Timestamp (ör. 2024-06-30T09:00:00.000000Z).

Bu değerlerden hiçbirini ayarlamazsanız varsayılan TTL 1 saattir. TTL için minimum veya maksimum sınır yoktur.

Mevcut açık önbellekler için ttl veya expire_time ekleyebilir ya da bunları güncelleyebilirsiniz. Önbelleğin tam nitelikli kaynak name öğesinin son segmenti olan CACHE_ID değerini sağlamanız gerekir.

Güncelleme 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'"
}'

Güncelleme 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'"
}'

Önbelleği silme

Artık ihtiyaç duymadığınız açık önbellekleri silebilirsiniz.