Bağlamı önbelleğe alma

Python JavaScript Go REST

Tipik bir yapay zeka iş akışında, aynı giriş jetonlarını bir modele tekrar tekrar iletebilirsiniz. Gemini API iki farklı önbelleğe alma mekanizması sunar:

• Örtülü önbelleğe alma (Çoğu Gemini modelinde otomatik olarak etkinleştirilir, maliyet tasarrufu garantisi yoktur)
• Açık önbelleğe alma (Çoğu modelde manuel olarak etkinleştirilebilir, maliyet tasarrufu garantisi)

Açıkça önbelleğe alma, maliyet tasarrufu sağlamak istediğiniz ancak biraz daha fazla geliştirici çalışması yapmanız gereken durumlarda faydalıdır.

Örtülü önbelleğe alma

Örtülü önbelleğe alma varsayılan olarak etkindir ve çoğu Gemini modelinde kullanılabilir. İsteğiniz önbelleklere isabet ederse maliyet tasarruflarını otomatik olarak aktarırız. Bu özelliği etkinleştirmek için herhangi bir işlem yapmanız gerekmez. 8 Mayıs 2025'ten itibaren geçerlidir. Bağlam önbelleğe alma için minimum giriş jetonu sayısı, her model için aşağıdaki tabloda listelenmiştir:

Örtülü önbellek isabeti olasılığını artırmak için:

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

Yanıt nesnesinin usage_metadata alanında, önbellek isabeti olan jeton sayısını görebilirsiniz.

Açık önbelleğe alma

Gemini API'nin açık önbelleğe alma özelliğini kullanarak bazı içerikleri modele bir kez iletebilir, giriş jetonlarını önbelleğe alabilir ve ardından sonraki istekler için önbelleğe alınmış jetonlara başvurabilirsiniz. Belirli hacimlerde, önbelleğe alınmış jetonları kullanmak, aynı jeton gövdesini tekrar tekrar iletmekten daha düşük maliyetlidir.

Bir dizi jetonu önbelleğe aldığınızda, jetonlar otomatik olarak silinmeden önce önbelleğin ne kadar süreyle var olmasını istediğinizi seçebilirsiniz. Bu önbelleğe alma süresine geçerlilik süresi (TTL) adı verilir. Ayarlanmazsa TTL varsayılan olarak 1 saat olur. Önbelleğe alma maliyeti, giriş jetonu boyutuna ve jetonların ne kadar süre boyunca kalıcı olmasını istediğinize bağlıdır.

Bu bölümde, bir Gemini SDK'sını yüklediğiniz (veya curl'ü yüklediğiniz) ve hızlı başlangıç bölümünde gösterildiği gibi bir API anahtarı yapılandırdığınız varsayılır.

Önbelleği kullanarak içerik oluşturma

Aşağıdaki örnekte, önbelleğe alınmış bir sistem talimatı ve video dosyası kullanarak nasıl içerik oluşturulacağı gösterilmektedir.

import os
import pathlib
import requests
import time

from google import genai
from google.genai import types

client = genai.Client()

# Download a test video file and save it locally
url = 'https://storage.googleapis.com/generativeai-downloads/data/SherlockJr._10min.mp4'
path_to_video_file = pathlib.Path('SherlockJr._10min.mp4')
if not path_to_video_file.exists():
    path_to_video_file.write_bytes(requests.get(url).content)

# Upload the video using the Files API
video_file = client.files.upload(file=path_to_video_file)

# Wait for the file to finish processing
while video_file.state.name == 'PROCESSING':
    time.sleep(2.5)
    video_file = client.files.get(name=video_file.name)

print(f'Video processing complete: {video_file.uri}')

model='models/gemini-3-flash-preview'

# Create a cache with a 5 minute TTL (300 seconds)
cache = client.caches.create(
    model=model,
    config=types.CreateCachedContentConfig(
        display_name='sherlock jr movie', # used to identify the cache
        system_instruction=(
            'You are an expert video analyzer, and your job is to answer '
            'the user\'s query based on the video file you have access to.'
        ),
        contents=[video_file],
        ttl="300s",
    )
)

response = client.models.generate_content(
    model = model,
    contents= (
    'Introduce different characters in the movie by describing '
    'their personality, looks, and names. Also list the timestamps '
    'they were introduced for the first time.'),
    config=types.GenerateContentConfig(cached_content=cache.name)
)

print(response.usage_metadata)

print(response.text)

from google import genai
from google.genai import types
import io
import httpx

client = genai.Client()

long_context_pdf_path = "https://sma.nasa.gov/SignificantIncidents/assets/a11_missionreport.pdf"

# Retrieve and upload the PDF using the File API
doc_io = io.BytesIO(httpx.get(long_context_pdf_path).content)

document = client.files.upload(
  file=doc_io,
  config=dict(mime_type='application/pdf')
)

model_name = "gemini-3-flash-preview"
system_instruction = "You are an expert analyzing transcripts."

# Create a cached content object
cache = client.caches.create(
    model=model_name,
    config=types.CreateCachedContentConfig(
      system_instruction=system_instruction,
      contents=[document],
    )
)

print(f'{cache=}')

response = client.models.generate_content(
  model=model_name,
  contents="Please summarize this transcript",
  config=types.GenerateContentConfig(
    cached_content=cache.name
  ))

print(f'{response.usage_metadata=}')

print('\n\n', response.text)

Önbellekleri listeleme

Önbelleğe alınmış içerikleri almak veya görüntülemek mümkün değildir ancak önbellek meta verilerini (name, model, display_name, usage_metadata, create_time, update_time ve expire_time) alabilirsiniz.

Yüklenen tüm önbelleklerin meta verilerini listelemek için CachedContent.list() kullanın:

for cache in client.caches.list():
  print(cache)

Adını biliyorsanız bir önbellek nesnesinin meta verilerini getirmek için get kullanın:

client.caches.get(name=name)

Önbelleği güncelleme

Bir önbellek için yeni bir ttl veya expire_time ayarlayabilirsiniz. Önbellekle ilgili başka bir şeyin değiştirilmesi desteklenmez.

Aşağıdaki örnekte, client.caches.update() kullanılarak bir önbelleğin ttl değerinin nasıl güncelleneceği gösterilmektedir.

from google import genai
from google.genai import types

client.caches.update(
  name = cache.name,
  config  = types.UpdateCachedContentConfig(
      ttl='300s'
  )
)

Geçerlilik bitiş zamanını ayarlamak için datetime nesnesi veya ISO biçimli bir tarih/saat dizesi (dt.isoformat(), örneğin 2025-01-27T16:02:36.473528+00:00) kabul edilir. Zamanınız bir saat dilimi içermelidir (datetime.utcnow() saat dilimi eklemez, datetime.now(datetime.timezone.utc) saat dilimi ekler).

from google import genai
from google.genai import types
import datetime

# You must use a time zone-aware time.
in10min = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(minutes=10)

client.caches.update(
  name = cache.name,
  config  = types.UpdateCachedContentConfig(
      expire_time=in10min
  )
)

Önbelleği silme

Önbelleğe alma hizmeti, içeriği önbellekten manuel olarak kaldırmak için silme işlemi sağlar. Aşağıdaki örnekte önbelleğin nasıl silineceği gösterilmektedir:

client.caches.delete(cache.name)

OpenAI kitaplığını kullanarak açık önbelleğe alma

OpenAI kitaplığı kullanıyorsanız extra_body üzerinde cached_content özelliğini kullanarak açık önbelleğe almayı etkinleştirebilirsiniz.

Açık önbelleğe alma ne zaman kullanılır?

Bağlamı önbelleğe alma, özellikle önemli bir ilk bağlamın daha kısa isteklerle tekrar tekrar referans alındığı senaryolar için uygundur. Aşağıdaki gibi kullanım alanlarında bağlamı önbelleğe alma özelliğini kullanabilirsiniz:

• Kapsamlı sistem talimatlarına sahip chatbot'lar
• Uzun video dosyalarının tekrar tekrar analiz edilmesi
• Büyük doküman kümelerine karşı yinelenen sorgular
• Sık kod deposu analizi veya hata düzeltme

Açıkça önbelleğe alma maliyetleri nasıl azaltır?

Bağlam önbelleğe alma, maliyeti düşürmek için tasarlanmış ücretli bir özelliktir. Faturalandırma aşağıdaki faktörlere göre yapılır:

1. Önbelleğe alınan jeton sayısı: Önbelleğe alınan giriş jetonlarının sayısı. Bu jetonlar, sonraki istemlere dahil edildiğinde daha düşük bir ücretle faturalandırılır.
2. Depolama süresi: Önbelleğe alınmış jetonların depolandığı süre (TTL), önbelleğe alınmış jeton sayısının TTL süresine göre faturalandırılır. TTL için minimum veya maksimum sınır yoktur.
3. Diğer faktörler: Giriş ve çıkış jetonları gibi önbelleğe alınmamış jetonlar için diğer ücretler geçerlidir.

En güncel fiyatlandırma ayrıntıları için Gemini API fiyatlandırma sayfasını inceleyin. Jetonları nasıl sayacağınızı öğrenmek için Jeton kılavuzu başlıklı makaleyi inceleyin.

Göz önünde bulundurulacak diğer noktalar

Bağlam önbelleğe almayı kullanırken aşağıdaki hususları göz önünde bulundurun:

• Bağlam önbelleğe alma için minimum giriş jetonu sayısı modele göre değişir. Maksimum, belirli modelin maksimum değeriyle aynıdır. (Jeton sayma hakkında daha fazla bilgi için Jeton kılavuzu'na bakın).
• Model, önbelleğe alınmış jetonlar ile normal giriş jetonları arasında herhangi bir ayrım yapmaz. Önbelleğe alınmış içerik, istemin ön ekidir.
• Bağlam önbelleğe alma konusunda özel bir oran veya kullanım sınırı yoktur. GenerateContent için standart oran sınırları geçerlidir ve jeton sınırlarına önbelleğe alınmış jetonlar da dahildir.
• Önbelleğe alınan jeton sayısı, önbellek hizmetinin oluşturma, alma ve listeleme işlemlerinden usage_metadata içinde ve önbellek kullanılırken GenerateContent içinde döndürülür.