В типичном рабочем процессе ИИ вы можете снова и снова передавать в модель одни и те же входные токены. Используя функцию кэширования контекста Gemini API, вы можете один раз передать некоторый контент в модель, кэшировать входные токены, а затем обращаться к кэшированным токенам для последующих запросов. В определенных объемах использование кэшированных токенов обходится дешевле, чем повторная передача одного и того же набора токенов.
Когда вы кэшируете набор токенов, вы можете выбрать, как долго вы хотите, чтобы кеш существовал, прежде чем токены будут автоматически удалены. Эта продолжительность кэширования называется временем жизни (TTL). Если значение не установлено, значение TTL по умолчанию составляет 1 час. Стоимость кэширования зависит от размера входного токена и того, как долго вы хотите, чтобы токены сохранялись.
Кэширование контекста поддерживает как Gemini 1.5 Pro, так и Gemini 1.5 Flash.
Когда использовать контекстное кэширование
Кэширование контекста особенно хорошо подходит для сценариев, в которых к существенному исходному контексту неоднократно обращаются более короткие запросы. Рассмотрите возможность использования контекстного кэширования в таких случаях, как:
- Чат-боты с подробными системными инструкциями
- Повторный анализ длинных видеофайлов
- Повторяющиеся запросы к большим наборам документов
- Частый анализ репозитория кода или исправление ошибок
Как кэширование снижает затраты
Кэширование контекста — это платная функция, предназначенная для снижения общих эксплуатационных расходов. Выставление счетов зависит от следующих факторов:
- Количество токенов кэша: количество кэшированных входных токенов, оплачиваемых по сниженной ставке при включении в последующие запросы.
- Продолжительность хранения: количество времени хранения кэшированных токенов (TTL), оплата взимается на основе продолжительности TTL количества кэшированных токенов. Для TTL нет минимальных или максимальных границ.
- Другие факторы: взимаются другие сборы, например, за некэшированные входные токены и выходные токены.
Актуальную информацию о ценах можно найти на странице цен на 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)
Получение списка кешей
Невозможно получить или просмотреть кэшированный контент, но вы можете получить метаданные кэша ( name
, model
, display_name
, usage_metadata
, create_time
, update_time
и expire_time
).
Чтобы вывести метаданные для всех загруженных кешей, используйте CachedContent.list()
:
for cache in client.caches.list():
print(cache)
Чтобы получить метаданные для одного объекта кэша, если вы знаете его имя, используйте get
:
client.caches.get(name=name)
Обновить кэш
Вы можете установить новый ttl
или expire_time
для кеша. Изменение чего-либо еще в кеше не поддерживается.
В следующем примере показано, как обновить ttl
кэша с помощью client.caches.update()
.
from google import genai
from google.genai import types
client.caches.update(
name = cache.name,
config = types.UpdateCachedContentConfig(
ttl='300s'
)
)
Чтобы установить время истечения срока действия, он принимает либо объект datetime
, либо строку 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
, а ограничения токенов включают кэшированные токены. - Количество кэшированных токенов возвращается в
usage_metadata
из операций создания, получения и списка службы кэша, а также вGenerateContent
при использовании кэша.