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

Python JavaScript Go REST

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

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

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

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

Неявное кэширование включено по умолчанию и доступно для большинства моделей Gemini. Мы автоматически передаем экономию средств, если ваш запрос попадает в кэш. Вам ничего не нужно делать для его включения. Оно вступает в силу с 8 мая 2025 года. Минимальное количество входных токенов для контекстного кэширования указано в следующей таблице для каждой модели:

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

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

Количество токенов, попавших в кэш, можно увидеть в поле 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 a test video file and save it locally
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():
    path_to_video_file.write_bytes(requests.get(url).content)

# 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':
    time.sleep(2.5)
    video_file = client.files.get(name=video_file.name)

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

model='models/gemini-3-flash-preview'

# Create a cache with a 5 minute TTL (300 seconds)
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",
    )
)

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)

print(response.text)

from google import genai
from google.genai import types
import io
import httpx

client = genai.Client()

long_context_pdf_path = "https://sma.nasa.gov/SignificantIncidents/assets/a11_missionreport.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-3-flash-preview"
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],
    )
)

print(f'{cache=}')

response = client.models.generate_content(
  model=model_name,
  contents="Please summarize this transcript",
  config=types.GenerateContentConfig(
    cached_content=cache.name
  ))

print(f'{response.usage_metadata=}')

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), оплата производится исходя из срока хранения количества кэшированных токенов. Минимальных или максимальных ограничений по TTL нет.
3. Другие факторы: Взимаются дополнительные сборы, например, за некэшированные входные и выходные токены.

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

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

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

• Минимальное количество входных токенов для контекстного кэширования варьируется в зависимости от модели. Максимальное значение совпадает с максимальным значением для данной модели. (Более подробную информацию о подсчете токенов см. в руководстве по токенам ).
• Данная модель не делает различий между кэшированными токенами и обычными входными токенами. Кэшированное содержимое является префиксом к подсказке.
• Для контекстного кэширования нет специальных ограничений по скорости или использованию; применяются стандартные ограничения скорости для GenerateContent , а ограничения на токены включают кэшированные токены.
• Количество кэшированных токенов возвращается в переменной usage_metadata из операций создания, получения и перечисления в службе кэширования, а также в GenerateContent при использовании кэша.