Кэширование контекста

В типичном рабочем процессе ИИ вы можете передавать одни и те же входные токены модели снова и снова. API Gemini предлагает два различных механизма кэширования:

  • Неявное кэширование (автоматически включается на моделях Gemini 2.5, экономия средств не гарантируется)
  • Явное кэширование (можно включить вручную на большинстве моделей, гарантия экономии средств)

Явное кэширование полезно в случаях, когда вы хотите гарантировать экономию средств, но с некоторой дополнительной работой разработчика.

Неявное кэширование

Неявное кэширование включено по умолчанию для всех моделей Gemini 2.5. Мы автоматически передаем экономию средств, если ваш запрос попадает в кэш. Для включения этой функции вам ничего делать не нужно. Она вступает в силу с 8 мая 2025 года. Минимальное количество входных токенов для кэширования контекста составляет 1024 для 2.5 Flash и 4096 для 2.5 Pro.

Чтобы увеличить вероятность неявного попадания в кэш:

  • Попробуйте поместить объемное и распространенное содержимое в начало вашего запроса.
  • Попробуйте отправлять запросы с похожим префиксом за короткий промежуток времени.

Количество токенов, попавших в кэш, можно увидеть в поле usage_metadata объекта ответа.

Явное кэширование

Используя функцию явного кэширования API Gemini, вы можете один раз передать часть контента модели, кэшировать входные токены, а затем обращаться к кэшированным токенам для последующих запросов. При определённых объёмах использование кэшированных токенов обходится дешевле, чем многократная передача одного и того же набора токенов.

При кэшировании набора токенов вы можете выбрать длительность существования кэша, после чего токены будут автоматически удалены. Этот срок кэширования называется временем жизни (TTL). Если значение не задано, TTL по умолчанию равен 1 часу. Стоимость кэширования зависит от размера входного токена и желаемого срока хранения токенов.

В этом разделе предполагается, что вы установили Gemini SDK (или установили curl) и настроили ключ API, как показано в кратком руководстве .

Генерация контента с использованием кэша

В следующем примере показано, как генерировать контент с использованием кэшированной системной инструкции и видеофайла.

Видео 

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)

Список кэшей

Невозможно извлечь или просмотреть кэшированное содержимое, но можно извлечь метаданные кэша ( 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)

Явное кэширование с использованием библиотеки OpenAI

Если вы используете библиотеку OpenAI , вы можете включить явное кэширование с помощью свойства cached_content в extra_body .

Когда следует использовать явное кэширование

Кэширование контекста особенно хорошо подходит для сценариев, где к существенному исходному контексту многократно обращаются короткие запросы. Рассмотрите возможность использования кэширования контекста в таких случаях:

  • Чат-боты с подробными системными инструкциями
  • Повторный анализ длинных видеофайлов
  • Повторяющиеся запросы к большим наборам документов
  • Частый анализ репозитория кода или исправление ошибок

Как явное кэширование снижает затраты

Кэширование контекста — платная функция, разработанная для снижения общих эксплуатационных расходов. Тарификация рассчитывается на основе следующих факторов:

  1. Количество кэшированных токенов ввода: количество кэшированных токенов ввода, тарифицируемых по сниженной ставке при включении в последующие запросы.
  2. Срок хранения: время хранения кэшированных токенов (TTL), тарифицируемое на основе срока хранения количества кэшированных токенов. Ограничений по минимальному или максимальному сроку хранения нет.
  3. Другие факторы: применяются другие сборы, например, за некэшированные входные токены и выходные токены.

Актуальную информацию о ценах можно найти на странице цен Gemini API. Чтобы узнать, как считать токены, см. руководство по токенам .

Дополнительные соображения

При использовании кэширования контекста следует учитывать следующие соображения:

  • Минимальное количество входных токенов для кэширования контекста составляет 1024 для 2.5 Flash и 2048 для 2.5 Pro. Максимальное количество совпадает с максимальным количеством для данной модели. (Подробнее о подсчёте токенов см. в руководстве по токенам ).
  • Модель не делает различий между кэшированными токенами и обычными входными токенами. Кэшированное содержимое — это префикс к приглашению.
  • Никаких специальных ограничений по скорости или использованию кэширования контекста не существует; действуют стандартные ограничения по скорости для GenerateContent , а ограничения по токенам включают кэшированные токены.
  • Количество кэшированных токенов возвращается в usage_metadata из операций create, get и list службы кэширования, а также в GenerateContent при использовании кэша.