コンテキストのキャッシュ保存

一般的な AI ワークフローでは、同じ入力トークンをモデルに何度も渡すことがあります。Gemini API のコンテキスト キャッシュ保存機能を使用すると、一部のコンテンツをモデルに一度渡し、入力トークンをキャッシュに保存してから、キャッシュに保存されたトークンを後続のリクエストで参照できます。一定のボリュームでは、キャッシュに保存されたトークンを使用する方が、同じトークン コーパスを繰り返し渡すよりも費用が低くなります。

一連のトークンをキャッシュに保存する場合は、トークンが自動的に削除されるまでのキャッシュの存続期間を選択できます。このキャッシュ保存期間は有効期間(TTL)と呼ばれます。設定しない場合、TTL はデフォルトで 1 時間になります。キャッシュに保存する費用は、入力トークンのサイズとトークンを保持する時間によって異なります。

コンテキスト キャッシュ保存は、Gemini 1.5 Pro と Gemini 1.5 Flash の両方をサポートしています。

コンテキスト キャッシュ保存を使用する状況

コンテキスト キャッシュ保存は、初期コンテキストの実体部分が、短いリクエストで繰り返し参照されるシナリオに特に適しています。次のようなユースケースでは、コンテキスト キャッシュ保存の使用を検討してください。

  • 広範なシステム指示を伴う chatbot
  • 長時間の動画ファイルの繰り返し分析
  • 大規模なドキュメント セットに対する繰り返しのクエリ
  • 頻繁なコード リポジトリの分析やバグ修正

キャッシュによって費用を削減する方法

コンテキスト キャッシュ保存は、全体的な運用コストを削減するために設計された有料の機能です。ご請求は次の項目に基づいて行われます。

  1. キャッシュ トークン数: キャッシュに保存された入力トークンの数。後続のプロンプトに含まれる場合は、割引料金で請求されます。
  2. 保存期間: キャッシュに保存されたトークンの保存時間(TTL)。キャッシュに保存されたトークン数の TTL 時間に基づいて課金されます。TTL の最小値や最大値はありません。
  3. その他の項目: 入力トークンや出力トークンがキャッシュされていない場合などは、別の料金が適用されます。

最新の料金の詳細については、Gemini API の料金ページをご覧ください。トークンをカウントする方法については、トークン ガイドをご覧ください。

コンテキスト キャッシュ保存を使用する方法

このセクションでは、クイックスタートに記載されているように、Gemini SDK がインストールされていること(または curl がインストールされていること)と、API キーが構成されていることを前提としています。

キャッシュを使用してコンテンツを生成する

次の例は、キャッシュに保存されたシステム インストラクションと動画ファイルを使用してコンテンツを生成する方法を示しています。

import os
import pathlib
import requests
import time

from google import genai
from google.genai import types

# Get your API key from https://aistudio.google.com/app/apikey
# Put it in a "GOOGLE_API_KEY" environment variable.
# For more details, see
# https://github.com/google-gemini/cookbook/blob/main/quickstarts/Authentication.ipynb
client = genai.Client()

# Download video file
url = 'https://storage.googleapis.com/generativeai-downloads/data/Sherlock_Jr_FullMovie.mp4'
path_to_video_file = pathlib.Path('Sherlock_Jr_FullMovie.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(path=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-1.5-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)

キャッシュを一覧表示する

キャッシュに保存されたコンテンツを取得または表示することはできませんが、キャッシュ メタデータ(namemodeldisplay_nameusage_metadatacreate_timeupdate_timeexpire_time)を取得できます。

アップロードされたすべてのキャッシュのメタデータを一覧表示するには、CachedContent.list() を使用します。

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

1 つのキャッシュ オブジェクトのメタデータを取得するには、その名前がわかっている場合は get を使用します。

client.caches.get(name=name)

キャッシュを更新する

キャッシュに新しい ttl または expire_time を設定できます。キャッシュのその他の変更はサポートされていません。

次の例は、client.caches.update() を使用してキャッシュの ttl を更新する方法を示しています。

from google import genai
from google.genai import types

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

有効期限を設定するには、datetime オブジェクトまたは ISO 形式の日時文字列(dt.isoformat()2025-01-27T16:02:36.473528+00:00 など)を指定します。時刻にはタイムゾーンを含める必要があります(datetime.utcnow() はタイムゾーンを付加しませんが、datetime.now(datetime.timezone.utc) はタイムゾーンを付加します)。

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

キャッシュを削除する

キャッシュ サービスには、キャッシュからコンテンツを手動で削除するための削除オペレーションが用意されています。次の例は、キャッシュを削除する方法を示しています。

client.caches.delete(cache.name)

その他の考慮事項

コンテキスト キャッシュを使用する場合は、次の点に注意してください。

  • コンテキスト キャッシュの最小入力トークン数は 32,768 で、最大数は特定のモデルの最大数と同じです。(トークンのカウントについて詳しくは、トークンのガイドをご覧ください)。
  • モデルは、キャッシュに保存されたトークンと通常の入力トークンを区別しません。キャッシュに保存されたコンテンツは、プロンプトの接頭辞にすぎません。
  • コンテキスト キャッシュには特別なレートや使用量の上限はありません。GenerateContent の標準レートの上限が適用され、トークンの上限にはキャッシュに保存されたトークンが含まれます。
  • キャッシュに保存されているトークン数は、キャッシュ サービスの create、get、list オペレーションから usage_metadata で返されます。また、キャッシュを使用している場合は GenerateContent でも返されます。