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

В типичном рабочем процессе ИИ вы можете передавать одни и те же входные токены модели снова и снова. 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, как показано в кратком руководстве .

Явное кэширование с использованием библиотеки 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 при использовании кэша.