Кэширование промптов (Google)

Модели Google Gemini 2.5 и новее поддерживают автоматическое (имплицитное) кэширование. Оно включено по умолчанию — никаких изменений в коде не требуется. Если запрос содержит совпадающий префикс с предыдущими запросами, скидка применяется автоматически.

Как работает

1. Каждый запрос к Gemini 2.5+ автоматически проверяется на совпадение с ранее обработанными запросами
2. Если начало запроса (префикс) совпадает — токены берутся из кэша со скидкой до 90%
3. Запись в кэш бесплатна — дополнительных расходов нет
4. Кэшируется всё содержимое: текст, изображения, аудио, видео, документы

Минимальная длина

Минимальная длина запроса для срабатывания кэша зависит от модели:

Стоимость

• Запись в кэш: бесплатно
• Чтение из кэша: до 90% дешевле обычных входных токенов (зависит от модели и платформы)

У моделей с расширенным контекстом (Pro при >200K токенов) кэшированные токены также тарифицируются по сниженной ставке.

Как увеличить частоту попаданий

• Размещайте неизменяемое содержимое (инструкции, документы) в начале запроса
• Изменяемую часть (вопрос пользователя) — в конце
• Отправляйте запросы с одинаковым префиксом в короткий промежуток времени — это увеличивает вероятность попадания в кэш

Как отслеживать

При работе через нативный API Google информация о кэшировании возвращается в usageMetadata:

{
  "usageMetadata": {
    "promptTokenCount": 10523,
    "candidatesTokenCount": 512,
    "totalTokenCount": 11035,
    "cachedContentTokenCount": 9800
  }
}

Значение cachedContentTokenCount показывает количество токенов, обработанных из кэша.

При работе через OpenAI-совместимый эндпоинт информация доступна в стандартном формате usage.prompt_tokens_details.cached_tokens.

Пример через ProxyAPI (нативный API)

curlpythonnode.js
curl "https://api.proxyapi.ru/google/v1beta/models/gemini-2.5-flash:generateContent" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <КЛЮЧ>" \
    -d '{
        "contents": [
            {
                "role": "user",
                "parts": [
                    {"text": "Длинный контекст (более 1024 токенов)..."},
                    {"text": "Вопрос пользователя"}
                ]
            }
        ]
    }'

Отправьте два одинаковых запроса подряд. Во втором ответе cachedContentTokenCount будет больше нуля — кэш сработал.