Cache konteks

Dalam alur kerja AI biasa, Anda mungkin meneruskan token input yang sama berulang kali ke model. Gemini API menawarkan dua mekanisme caching yang berbeda:

  • Caching implisit (diaktifkan secara otomatis pada model Gemini 2.5, tidak ada jaminan penghematan biaya)
  • Caching eksplisit (dapat diaktifkan secara manual di sebagian besar model, jaminan penghematan biaya)

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

Caching implisit

Caching implisit diaktifkan secara default untuk semua model Gemini 2.5. Kami secara otomatis meneruskan penghematan biaya jika permintaan Anda mencapai cache. Anda tidak perlu melakukan apa pun untuk mengaktifkannya. Kebijakan ini berlaku mulai 8 Mei 2025. Jumlah token input minimum untuk penyimpanan dalam cache konteks adalah 1.024 untuk 2.5 Flash dan 4.096 untuk 2.5 Pro.

Untuk meningkatkan peluang cache implisit ditemukan:

  • Coba letakkan konten besar dan umum di awal perintah Anda
  • Mencoba mengirim permintaan dengan awalan yang serupa dalam waktu singkat

Anda dapat melihat jumlah token yang merupakan hit cache di kolom usage_metadata objek respons.

Caching eksplisit

Dengan menggunakan fitur caching eksplisit Gemini API, Anda dapat meneruskan beberapa konten ke model sekali, menyimpan token input dalam cache, lalu merujuk ke token yang di-cache untuk permintaan berikutnya. Pada volume tertentu, penggunaan token yang di-cache lebih murah daripada meneruskan korpus token yang sama secara berulang.

Saat menyimpan cache sekumpulan token, Anda dapat memilih durasi keberadaan cache sebelum token dihapus secara otomatis. Durasi penyimpanan dalam cache ini disebut time to live (TTL). Jika tidak disetel, TTL defaultnya adalah 1 jam. Biaya untuk melakukan caching bergantung pada ukuran token input dan durasi yang Anda inginkan untuk token tetap ada.

Bagian ini mengasumsikan bahwa Anda telah menginstal Gemini SDK (atau telah menginstal curl) dan telah mengonfigurasi kunci API, seperti yang ditunjukkan dalam mulai cepat.

Membuat konten menggunakan cache

Contoh berikut menunjukkan cara membuat konten menggunakan petunjuk sistem dan file video yang di-cache.

Video

import os
import pathlib
import requests
import time

from google import genai
from google.genai import types

client = genai.Client()

# Download video file
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():
  with path_to_video_file.open('wb') as wf:
    response = requests.get(url, stream=True)
    for chunk in response.iter_content(chunk_size=32768):
      wf.write(chunk)

# 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':
  print('Waiting for video to be processed.')
  time.sleep(2)
  video_file = client.files.get(name=video_file.name)

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

# You must use an explicit version suffix: "-flash-001", not just "-flash".
model='models/gemini-2.0-flash-001'

# Create a cache with a 5 minute TTL
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",
  )
)

# Construct a GenerativeModel which uses the created cache.
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)

# The output should look something like this:
#
# prompt_token_count: 696219
# cached_content_token_count: 696190
# candidates_token_count: 214
# total_token_count: 696433

print(response.text)

PDF

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

client = genai.Client()

long_context_pdf_path = "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.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-2.0-flash-001"
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],
    )
)

# Display the cache details
print(f'{cache=}')

# Generate content using the cached prompt and document
response = client.models.generate_content(
  model=model_name,
  contents="Please summarize this transcript",
  config=types.GenerateContentConfig(
    cached_content=cache.name
  ))

# (Optional) Print usage metadata for insights into the API call
print(f'{response.usage_metadata=}')

# Print the generated text
print('\n\n', response.text)

Mencantumkan cache

Anda tidak dapat mengambil atau melihat konten dalam cache, tetapi Anda dapat mengambil metadata cache (name, model, display_name, usage_metadata, create_time, update_time, dan expire_time).

Untuk mencantumkan metadata semua cache yang diupload, gunakan CachedContent.list():

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

Untuk mengambil metadata satu objek cache, jika Anda mengetahui namanya, gunakan get:

client.caches.get(name=name)

Memperbarui cache

Anda dapat menyetel ttl atau expire_time baru untuk cache. Perubahan lain pada cache tidak didukung.

Contoh berikut menunjukkan cara mengupdate ttl cache menggunakan client.caches.update().

from google import genai
from google.genai import types

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

Untuk menetapkan waktu habis masa berlaku, metode ini akan menerima objek datetime atau string tanggal dan waktu berformat ISO (dt.isoformat(), seperti 2025-01-27T16:02:36.473528+00:00). Waktu Anda harus menyertakan zona waktu (datetime.utcnow() tidak melampirkan zona waktu, datetime.now(datetime.timezone.utc) melampirkan zona waktu).

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

Menghapus cache

Layanan caching menyediakan operasi penghapusan untuk menghapus konten secara manual dari cache. Contoh berikut menunjukkan cara menghapus cache:

client.caches.delete(cache.name)

Caching eksplisit menggunakan library OpenAI

Jika menggunakan library OpenAI, Anda dapat mengaktifkan penyimpanan cache eksplisit menggunakan properti cached_content di extra_body.

Kapan harus menggunakan caching eksplisit

Penyimpanan cache konteks sangat cocok untuk skenario saat konteks awal yang besar dirujuk berulang kali oleh permintaan yang lebih pendek. Pertimbangkan untuk menggunakan penyimpanan cache konteks untuk kasus penggunaan seperti:

  • Chatbot dengan petunjuk sistem yang ekstensif
  • Analisis berulang pada file video panjang
  • Kueri berulang terhadap set dokumen besar
  • Analisis repositori kode atau perbaikan bug yang sering

Cara caching eksplisit mengurangi biaya

Caching konteks adalah fitur berbayar yang dirancang untuk mengurangi biaya operasional secara keseluruhan. Penagihan didasarkan pada faktor-faktor berikut:

  1. Jumlah token cache: Jumlah token input yang di-cache, ditagih dengan tarif yang lebih rendah jika disertakan dalam perintah berikutnya.
  2. Durasi penyimpanan: Jumlah waktu token yang di-cache disimpan (TTL), ditagih berdasarkan durasi TTL jumlah token yang di-cache. Tidak ada batas minimum atau maksimum pada TTL.
  3. Faktor lain: Biaya lain berlaku, seperti untuk token input dan token output yang tidak di-cache.

Untuk mengetahui detail harga terbaru, lihat halaman harga Gemini API. Untuk mempelajari cara menghitung token, lihat panduan Token.

Pertimbangan tambahan

Perhatikan hal-hal berikut saat menggunakan penyiapan cache konteks:

  • Jumlah token input minimum untuk penyimpanan dalam cache konteks adalah 1.024 untuk 2.5 Flash dan 2.048 untuk 2.5 Pro. Maksimum sama dengan maksimum untuk model yang diberikan. (Untuk mengetahui informasi selengkapnya tentang menghitung token, lihat Panduan token).
  • Model tidak membedakan antara token yang di-cache dan token input reguler. Konten yang di-cache adalah awalan untuk perintah.
  • Tidak ada batas penggunaan atau tarif khusus untuk caching konteks; batas tarif standar untuk GenerateContent berlaku, dan batas token mencakup token yang di-cache.
  • Jumlah token yang di-cache ditampilkan di usage_metadata dari operasi buat, dapatkan, dan cantumkan layanan cache, serta di GenerateContent saat menggunakan cache.