Кеширование запросов

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

Уменьшите стоимость использования моделей ИИ с помощью функции кэширования промптов AITUNNEL. Узнайте, как кэшировать и повторно использовать ответы для моделей OpenAI, Anthropic Claude, DeepSeek, Google Gemini и других.

Для экономии на стоимости запросов вы можете включить кэширование промптов для поддерживаемых провайдеров и моделей.

Большинство провайдеров автоматически включают кэширование промптов, но обратите внимание, что некоторые (например, Alibaba и Anthropic) требуют включения кэширования для каждого сообщения отдельно через параметр cache_control.

При использовании кэширования AITUNNEL применяет sticky routing для максимизации cache hit — подробнее см. раздел Provider Sticky Routing ниже.

Provider Sticky Routing

Для максимального количества попаданий в кэш AITUNNEL использует sticky routing: последующие запросы направляются к тому же провайдеру, который обслуживал предыдущий кэшированный запрос. Это работает как для неявного кэширования (OpenAI, DeepSeek, Gemini 2.5), так и для явного (Anthropic cache_control breakpoints).

Как это работает:

После запроса с использованием кэша AITUNNEL запоминает, какой провайдер обслуживал запрос.
Последующие запросы к той же модели направляются к тому же провайдеру, сохраняя кэш «тёплым».
Sticky routing активируется только если чтение из кэша у провайдера дешевле обычной цены входных токенов.
Если sticky-провайдер недоступен, автоматически используется fallback на следующего подходящего провайдера.
Sticky routing не применяется, если вы явно задали порядок провайдеров — в этом случае ваш порядок имеет приоритет.

Гранулярность sticky routing:

Привязка ведётся на уровне аккаунта, модели и диалога. По умолчанию AITUNNEL идентифицирует диалог по хешу первого system (или developer) сообщения и первого non-system сообщения в запросе. Запросы с одинаковыми начальными сообщениями направляются к одному провайдеру, что обеспечивает равномерную балансировку нагрузки и сохранение кэша в рамках диалога.

Использование `session_id` для sticky-сессий

Для более явного управления sticky routing можно передать session_id в запросе. При наличии session_id он используется как ключ sticky routing напрямую, вместо хеширования сообщений. Это особенно полезно для мультиагентных воркфлоу, где начальные сообщения могут меняться от запроса к запросу, но вы хотите оставаться у одного провайдера.

session_id можно передать двумя способами:

В теле запроса: добавьте session_id как поле верхнего уровня. Если указаны оба варианта, приоритет у значения в теле.
В заголовке: передайте HTTP-заголовок x-session-id.

Максимальная длина session_id — 256 символов.

json

{
  "model": "claude-sonnet-4-5",
  "session_id": "my-agent-session-abc123",
  "messages": [
    {
      "role": "user",
      "content": "Продолжим наш разговор..."
    }
  ]
}

Информация

При использовании session_id sticky routing активируется при первом же успешном запросе — ещё до обнаружения cache hit. Без session_id sticky routing активируется только после первого попадания в кэш.

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

Проверить эффект кэширования можно:

В деталях генерации в интерфейсе AITUNNEL (история/логи запросов).
Через API генераций/логов в вашем проекте.
Через объект usage.prompt_tokens_details в ответе модели.

Поле cache_discount в ответе показывает экономию от кэша. Для некоторых провайдеров (например, Anthropic) запись в кэш может давать отрицательный discount, а чтение из кэша — положительный (снижающий итоговую стоимость).

Поля объекта usage

json

{
  "usage": {
    "prompt_tokens": 10339,
    "completion_tokens": 60,
    "total_tokens": 10399,
    "prompt_tokens_details": {
      "cached_tokens": 10318,
      "cache_write_tokens": 0
    }
  }
}

cached_tokens — токены, считанные из кэша (cache hit). Значение больше нуля означает, что кэш работает.
cache_write_tokens — токены, записанные в кэш при создании новой кэш-записи.

OpenAI

Изменения в ценообразовании при кэшировании:

Запись в кэш: бесплатно
Чтение из кэша: (в зависимости от модели) оплачивается по цене 0.25x или 0.50x от оригинальной стоимости входных токенов

Посмотреть цены на кэширование для каждой модели OpenAI.

Кэширование промптов с OpenAI происходит автоматически и не требует дополнительной настройки. Минимальный размер промпта составляет 1024 токена.

Подробнее о кэшировании промптов OpenAI и его ограничениях.

Grok

Изменения в ценообразовании при кэшировании:

Запись в кэш: бесплатно
Чтение из кэша: оплачивается по сниженному коэффициенту к входной цене

Посмотреть цены Grok по моделям.

Кэширование промптов с Grok происходит автоматически и не требует дополнительной настройки.

Moonshot AI

Изменения в ценообразовании при кэшировании:

Запись в кэш: бесплатно
Чтение из кэша: оплачивается по сниженному коэффициенту к входной цене

Кэширование промптов с Moonshot AI происходит автоматически и не требует дополнительной настройки.

Groq

Изменения в ценообразовании при кэшировании:

Запись в кэш: бесплатно
Чтение из кэша: оплачивается по сниженному коэффициенту к входной цене

Кэширование промптов с Groq происходит автоматически и не требует дополнительной настройки. На текущий момент доступно для моделей Kimi K2.

Документация Groq по кэшированию.

Alibaba Qwen

Изменения в ценообразовании при явном кэшировании:

Запись в кэш: оплачивается по повышенному коэффициенту к входной цене
Чтение из кэша: оплачивается по сниженному коэффициенту к входной цене

Кэширование Alibaba требует явных точек разрыва. Добавьте cache_control: { "type": "ephemeral" } к блокам контента, которые нужно кэшировать — синтаксис аналогичен Anthropic. TTL кэш-записи — 5 минут.

Явное кэширование доступно для следующих моделей: deepseek-v3.2, qwen3-max, qwen-plus, qwen3.6-plus, qwen3-coder-plus, qwen3-coder-flash. Snapshot-эндпоинты (например, qwen3.5-plus-02-15, qwen3.5-flash-02-23) явное кэширование не поддерживают.

Пример

json

{
  "model": "qwen3-coder-plus",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Используй приведённую ниже документацию при ответе."
        },
        {
          "type": "text",
          "text": "БОЛЬШОЙ ТЕКСТ",
          "cache_control": {
            "type": "ephemeral"
          }
        },
        {
          "type": "text",
          "text": "Опиши основные детали реализации."
        }
      ]
    }
  ]
}

Anthropic Claude

Изменения в ценообразовании при кэшировании:

Запись в кэш (TTL 5 минут): ~1.25x от стоимости входных токенов
Запись в кэш (TTL 1 час): 2x от стоимости входных токенов
Чтение из кэша: ~0.1x от стоимости входных токенов

Кэширование с Anthropic поддерживает два режима:

Автоматическое кэширование: cache_control задаётся на верхнем уровне запроса — система автоматически применяет точку разрыва к последнему кэшируемому блоку и продвигает её вперёд по мере роста диалога. Лучше всего подходит для многошаговых диалогов.
Явные точки кэширования: cache_control ставится на конкретные блоки контента для точного управления тем, что кэшируется. Максимум 4 breakpoint в одном запросе. Рекомендуется использовать их для больших блоков: character cards, CSV, RAG-контекст, главы книг и т.д.

Предупреждение

Автоматическое кэширование (top-level cache_control) поддерживается только при маршрутизации непосредственно к провайдеру Anthropic. Amazon Bedrock и Google Vertex AI в настоящее время не поддерживают top-level cache_control. Явные per-block cache_control breakpoints работают у всех Anthropic-совместимых провайдеров, включая Bedrock и Vertex.

Responses API

Для Responses API поддерживается только автоматическое кэширование через top-level cache_control. Явные per-block breakpoints внутри элементов input через Responses API не поддерживаются — используйте Chat Completions API, если требуется точечное управление кэшированием.

По умолчанию TTL — 5 минут. Для продления до 1 часа используйте "ttl": "1h" внутри cache_control.

Подробнее о кэшировании промптов Anthropic и его ограничениях.

Минимальные требования по токенам

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

4096 токенов: Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Opus 4.5, Claude Haiku 4.5
2048 токенов: Claude Haiku 3.5
1024 токенов: Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4

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

Параметры TTL

AITUNNEL поддерживает два значения TTL для Anthropic:

5 минут (по умолчанию): "cache_control": { "type": "ephemeral" }
1 час: "cache_control": { "type": "ephemeral", "ttl": "1h" }

TTL 1 час полезен для длинных сессий, где важно реже переписывать кэш. Запись с TTL 1 час стоит дороже (2x от базовой входной цены против 1.25x для 5 минут), но может сэкономить деньги на длинных сессиях за счёт отсутствия повторных записей.

Автоматическое кэширование (рекомендуется для multi-turn)

При автоматическом кэшировании cache_control задаётся на верхнем уровне запроса:

json

{
  "model": "claude-sonnet-4-5",
  "cache_control": { "type": "ephemeral" },
  "messages": [
    {
      "role": "system",
      "content": "Вы историк, изучающий падение Римской империи. Вы хорошо знаете следующую книгу: БОЛЬШОЙ ТЕКСТ"
    },
    {
      "role": "user",
      "content": "Что послужило причиной краха?"
    }
  ]
}

По мере роста диалога cache breakpoint автоматически сдвигается вперёд и покрывает всё большую часть истории сообщений.

Автоматическое кэширование с TTL 1 час:

json

{
  "model": "claude-sonnet-4-5",
  "cache_control": { "type": "ephemeral", "ttl": "1h" },
  "messages": [
    {
      "role": "system",
      "content": "Вы полезный ассистент."
    },
    {
      "role": "user",
      "content": "В чем смысл жизни?"
    }
  ]
}

Явные точки кэширования (fine-grained control)

Пример кэширования системного сообщения (TTL 5 минут):

json

{
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "Вы историк, изучающий падение Римской империи. Вы хорошо знаете следующую книгу:"
        },
        {
          "type": "text",
          "text": "БОЛЬШОЙ ТЕКСТ",
          "cache_control": {
            "type": "ephemeral"
          }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Что послужило причиной краха?"
        }
      ]
    }
  ]
}

Пример кэширования пользовательского сообщения (TTL 1 час):

json

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Учитывая книгу ниже:"
        },
        {
          "type": "text",
          "text": "БОЛЬШОЙ ТЕКСТ",
          "cache_control": {
            "type": "ephemeral",
            "ttl": "1h"
          }
        },
        {
          "type": "text",
          "text": "Перечислите всех персонажей в книге выше"
        }
      ]
    }
  ]
}

DeepSeek

Изменения в ценообразовании при кэшировании:

Запись в кэш: оплачивается по той же цене, что и оригинальные входные токены
Чтение из кэша: оплачивается по сниженному коэффициенту к входной цене

Кэширование промптов с DeepSeek происходит автоматически и не требует дополнительной настройки.

Google Gemini

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

Модели Gemini 2.5 Pro и 2.5 Flash поддерживают неявное кэширование — автоматическую функциональность, аналогичную кэшированию OpenAI. Не требует ручной настройки или точек разрыва cache_control.

Изменения в ценообразовании:

Нет стоимости записи или хранения в кэше.
Кэшированные токены оплачиваются по сниженному коэффициенту к входной цене.

TTL в среднем составляет 3–5 минут, но может варьироваться. Минимальный размер промпта: 2048 токенов для Gemini 2.5 Flash и 4096 токенов для Gemini 2.5 Pro.

Официальное объявление от Google.

Совет

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

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

Изменения в ценообразовании для явного кэша:

Запись в кэш: стоимость входных токенов + 5 минут хранения, рассчитывается как:

Стоимость записи = Цена входных токенов + (Цена хранения × (5 минут / 60 минут))

Чтение из кэша: оплачивается по сниженному коэффициенту к входной цене.

Поддерживаемые модели и ограничения

Только определённые модели Gemini поддерживают кэширование. Актуальную информацию смотрите в документации по ценообразованию Gemini API.

Записи в кэш имеют TTL 5 минут, который не обновляется. После истечения TTL кэш удаляется и при необходимости создаётся новый. Кэшированные токены учитываются в лимите токенов модели.

Как работает кэширование Gemini в AITUNNEL

AITUNNEL упрощает управление кэшем Gemini:

Вам не нужно вручную создавать, обновлять или удалять кэши.
Вам не нужно явно управлять именами кэша или TTL.

Как включить явное кэширование Gemini

Явное кэширование Gemini в AITUNNEL требует вставки точек разрыва cache_control в содержимое сообщений — аналогично Anthropic. Рекомендуется использовать для больших блоков контента: CSV-файлы, длинные карточки персонажей, RAG-данные, обширные текстовые источники.

Совет

Нет ограничения на количество точек разрыва cache_control в запросе. AITUNNEL использует только последнюю точку разрыва для кэширования Gemini. Включение нескольких breakpoints безопасно и сохраняет совместимость с Anthropic, но для Gemini учитывается только последняя.

Информация

Gemini имеет единственное поле systemInstruction, и кэшированный системный контент считается неизменяемым. Это означает, что cache_control внутри первого system/developer сообщения кэширует нормализованный системный промпт, но не сохраняет динамический хвост внутри того же сообщения. Если часть промпта должна оставаться динамической, перенесите её в последующее user сообщение.

Пример кэширования системного сообщения

json

{
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "Вы историк, изучающий падение Римской империи. Ниже приведена обширная справочная книга:"
        },
        {
          "type": "text",
          "text": "БОЛЬШОЙ ТЕКСТ ЗДЕСЬ",
          "cache_control": {
            "type": "ephemeral"
          }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Что послужило причиной краха?"
        }
      ]
    }
  ]
}

Этот паттерн работает, когда кэшируемый системный контент стабилен между запросами. Если нужна динамическая часть промпта — разместите её в последующем user сообщении.

Пример кэширования пользовательского сообщения

json

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "На основе текста книги ниже:"
        },
        {
          "type": "text",
          "text": "БОЛЬШОЙ ТЕКСТ ЗДЕСЬ",
          "cache_control": {
            "type": "ephemeral"
          }
        },
        {
          "type": "text",
          "text": "Перечислите всех основных персонажей, упомянутых в тексте выше."
        }
      ]
    }
  ]
}

Кеширование запросов ​

Provider Sticky Routing ​

Использование session_id для sticky-сессий ​

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

Поля объекта usage ​

OpenAI ​

Grok ​

Moonshot AI ​

Groq ​

Alibaba Qwen ​

Пример ​

Anthropic Claude ​

Минимальные требования по токенам ​

Параметры TTL ​

Автоматическое кэширование (рекомендуется для multi-turn) ​

Явные точки кэширования (fine-grained control) ​

DeepSeek ​

Google Gemini ​

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

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

Поддерживаемые модели и ограничения ​

Как работает кэширование Gemini в AITUNNEL ​

Как включить явное кэширование Gemini ​

Пример кэширования системного сообщения ​

Пример кэширования пользовательского сообщения ​

Кеширование запросов

Provider Sticky Routing

Использование `session_id` для sticky-сессий

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

Поля объекта usage

OpenAI

Grok

Moonshot AI

Groq

Alibaba Qwen

Пример

Anthropic Claude

Минимальные требования по токенам

Параметры TTL

Автоматическое кэширование (рекомендуется для multi-turn)

Явные точки кэширования (fine-grained control)

DeepSeek

Google Gemini

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

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

Поддерживаемые модели и ограничения

Как работает кэширование Gemini в AITUNNEL

Как включить явное кэширование Gemini

Пример кэширования системного сообщения

Пример кэширования пользовательского сообщения