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

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

  • Неявное кэширование (автоматическое, без гарантии экономии средств)
  • Явное кэширование (ручное, гарантия экономии средств)

Неявное кэширование включено в моделях Gemini 2.5 по умолчанию. Если запрос содержит контент, который является кэшированным хитом, мы автоматически передаем вам экономию затрат.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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