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

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

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

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

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

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

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

キャッシュ保存によって費用が削減される仕組み

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

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

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

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

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

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

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

import os
import google.generativeai as genai
from google.generativeai import caching
import datetime
import time

# Get your API key from https://aistudio.google.com/app/apikey
# and access your API key as an environment variable.
# To authenticate from a Colab, see
# https://github.com/google-gemini/cookbook/blob/main/quickstarts/Authentication.ipynb
genai.configure(api_key=os.environ['API_KEY'])

# Download video file
# curl -O https://storage.googleapis.com/generativeai-downloads/data/Sherlock_Jr_FullMovie.mp4

path_to_video_file = 'Sherlock_Jr_FullMovie.mp4'

# Upload the video using the Files API
video_file = genai.upload_file(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 = genai.get_file(video_file.name)

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

# Create a cache with a 5 minute TTL
cache = caching.CachedContent.create(
    model='models/gemini-1.5-flash-001',
    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=datetime.timedelta(minutes=5),
)

# Construct a GenerativeModel which uses the created cache.
model = genai.GenerativeModel.from_cached_content(cached_content=cache)

# Query the model
response = model.generate_content([(
    'Introduce different characters in the movie by describing '
    'their personality, looks, and names. Also list the timestamps '
    'they were introduced for the first time.')])

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)

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

キャッシュに保存されたコンテンツを取得または表示することはできませんが、キャッシュメタデータ（name、model、display_name、usage_metadata、create_time、update_time、expire_time）は取得できます。

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

for c in caching.CachedContent.list():
  print(c)

キャッシュの更新

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

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

import datetime

cache.update(ttl=datetime.timedelta(hours=2))

キャッシュを削除する

キャッシュサービスは、キャッシュからコンテンツを手動で削除する削除オペレーションを提供します。次の例は、CachedContent.delete() を使用してキャッシュを削除する方法を示しています。

cache.delete()

その他の考慮事項

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

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