內容快取

在一般 AI 工作流程中，您可能會將相同的輸入符記傳遞給模型您可以透過 Gemini API 內容快取功能傳送某些內容快取輸入符記，然後參照快取符記以供後續要求使用在特定磁碟區下，使用快取權杖的成本較低而不是重複傳遞同一語料庫。

快取一組權杖時，你可以選擇快取保留時間長度即自動刪除權杖。這個快取時間長度為稱為「存留時間」 (TTL)。如未設定，TTL 會預設為 1 小時。快取費用取決於輸入符記大小，以及所需的權杖的保留時間。

內容快取功能同時支援 Gemini 1.5 Pro 和 Gemini 1.5 Flash。

使用內容快取的時機

內容快取特別適用於較短的要求會重複參照初始背景資訊。建議做法適合不同用途的情境快取功能

具備豐富系統操作說明的聊天機器人
重複分析長篇影片檔案
針對大型文件集執行週期性查詢
頻繁分析程式碼存放區或修正錯誤

快取功能如何降低成本

內容快取是一項付費功能，旨在降低整體作業成本。費用取決於下列因素：

快取權杖數量：快取的輸入權杖數量，由多個降低比率
儲存時間長度：儲存快取權杖的時間 (TTL)、計費依據為快取權杖數量的存留時間。沒有最低金額限制或存留時間的最大值
其他因素：可能須支付其他費用，例如非快取輸入權杖輸出符記

如要查看最新的定價詳細資料，請參閱 Gemini API 定價頁面。如要瞭解如何計算符記，請參閱指南。

如何使用內容快取

本節假設您已安裝 Gemini SDK 並設定 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。變更任何其他設定就不支援快取

以下範例說明如何使用用於更新快取的 ttl CachedContent.update()。

import datetime

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

刪除快取

快取服務提供手動移除內容的刪除作業。從快取中取得以下範例顯示如何刪除快取 CachedContent.delete()。

cache.delete()

其他注意事項

使用內容快取時，請注意下列事項：

內容快取的「下限」輸入符記數量為 32,768；而 max 與指定模型的上限相同。(如需進一步瞭解計算符記，請參閱符記指南)。
模型不會在快取符記和一般符記之間做出任何區別輸入符記快取內容就是提示的前置字串。
內容快取沒有特殊費率或用量限制；標準適用 GenerateContent 的頻率限制，權杖限制包括快取符記
系統會在 usage_metadata 建立、取得和列出快取服務的作業，以及在 GenerateContent (使用快取)。