К содержимому
Блог

Prompt caching в LLM API: как проверить кэш

Prompt caching в LLM API: как проверить кэш

Prompt caching имеет смысл только на повторяемой части запроса. Сначала выделите инструкции, справочный текст или другой стабильный блок. Затем отправьте несколько одинаковых по структуре запросов и сравните usage. Предположение по одному ответу не даёт результата.

Коротко

  • Проверьте поддержку нужного протокола на карточке модели.

  • Для Messages API пометьте стабильный блок cache_control.

  • Сравните счётчики usage на повторяемом сценарии.

  • Посчитайте порог окупаемости: запись кэша стоит денег, чтение дешевле входа.

Подготовьте стабильную часть запроса

Положите в начало сообщения то, что не меняется между вызовами: системные инструкции, правила формата или справочный текст. Пользовательский вопрос оставьте отдельным полем. Если менять стабильный блок на каждом запросе, сравнение не покажет полезной картины.

Relay передаёт учёт кэша в usage. Решение о кэшировании принимает модель, поэтому сначала выберите её через каталог и проверьте формат запроса в документации Messages API.

Пример для Messages API

bash
curl "https://relay-llm.ru/v1/messages" \
  -H "x-api-key: $RELAY_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "max_tokens": 512,
    "system": [
      {
        "type": "text",
        "text": "STATIC_INSTRUCTIONS",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [{"role": "user", "content": "QUESTION"}]
  }'

Замените MODEL_ID, STATIC_INSTRUCTIONS и QUESTION своими значениями до запуска. Ключ остаётся в переменной окружения. Полную схему и примеры response usage см. в документации кэширования.

Какие поля измерять

В Anthropic-формате ответ может содержать cache_read_input_tokens и cache_creation_input_tokens. В OpenAI-compatible формате следите за prompt_tokens_details.cached_tokens и cache_write_tokens, если они пришли в usage. Сохраняйте эти поля рядом с request_id, иначе спустя время нельзя будет сравнить измерения.

Не делайте вывод по первой паре запросов. Проверьте несколько одинаковых входов, затем одну версию с изменённым стабильным блоком. Разница покажет, не сломали ли вы повторяемость структуры.

Сколько запросов нужно, чтобы кэш окупился

Запрос оплачивается по частям: вход без кэша, запись в кэш, чтение из кэша и выход. Запись имеет отдельную ставку, чтение у большинства моделей дешевле входа. Выразим обе ставки в долях ставки входа: w для записи, r для чтения. Префикс из T токенов без кэша стоит N × T за N запросов внутри жизни записи (в единицах ставки входа). С кэшем: T × (c + (N − 1) × r), где c цена первого запроса, который записывает префикс. Кэш выгоден, когда выполняется условие:

text
N > (c − r) / (1 − r)

Чему равно c, зависит от протокола. В формате OpenAI записанные токены вычитаются из входа, значит c равно w. Для моделей Claude в протоколе Anthropic документация кэширования Relay описывает по-другому: записанный токен приходит и во входе, и в записи и оплачивается по обеим ставкам, значит c равно 1 плюс w.

Посмотрите, что это значит на условных числах: r равно 0,1, w равно 1,3. В первом случае порог равен (1,3 − 0,1) / 0,9, то есть около 1,3: кэш окупается со второго запроса. Во втором порог (2,3 − 0,1) / 0,9, около 2,4: выгода начинается с третьего. Настоящие ставки вашей модели читайте в карточке, она ниже. Проверьте вывод на двух запросах: в деталях запроса в журнале строки «Вход», «Запись кэша на 5 минут» и «Чтение кэша» покажут, сколько токенов пошло по какой ставке.

Каталог моделей

На каких нагрузках кэш даёт выгоду

Выигрыш пропорционален доле повторяющегося префикса во всём входе. Поэтому кэшируют то, что велико и неизменно:

  • длинный системный промпт с правилами формата и тона;

  • описания инструментов агента, которые почти не меняются между шагами;

  • справочный текст: документацию продукта, схему базы, регламент;

  • историю диалога до последней реплики, которая уже не изменится.

Условий три: префикс идентичен до символа, он длиннее минимума модели, запросы идут чаще, чем живёт запись.

Когда без кэша лучше

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

Грабли: что ломает кэш молча

Факты об устройстве кэша ниже взяты из документации Anthropic на 14 октября 2026, ссылка в конце статьи. Другие вендоры могут отличаться, сверяйтесь с карточкой модели.

  • Точек cache_control не больше четырёх на запрос. Ставьте их по иерархии: конец инструкций, конец схем инструментов, конец справочного текста.

  • Кэш строится по порядку: инструменты, системный промпт, сообщения. Правка на любом уровне сбрасывает его и всё, что идёт после. Менять описание инструмента посреди работы значит платить за запись всего заново.

  • Минимальная длина кэшируемого префикса зависит от модели Claude и составляет 512, 1024, 2048 или 4096 токенов. Короче префикс просто не кэшируется: оба счётчика кэша в usage остаются нулевыми.

  • По умолчанию запись живёт пять минут и продлевается при каждом чтении. Пауза длиннее пяти минут означает новую запись. У Anthropic есть вариант хранения на час; как он оплачивается у вашей модели, видно по строке «Запись кэша на час» в деталях запроса.

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

Свяжите кэш с контролем расходов

Цены чтения и записи кэша публикуются вместе с моделью, но числовые значения берите из текущей карточки или GET /v1/models. Документация моделей API описывает поля цены и единицы расчёта.

Если Messages API не подходит модели или клиенту, используйте её совместимый маршрут. Не переносите cache_control в другой формат без проверки его документации.

Гарантирует ли cache_control кэш для каждого вызова?

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

Нужно ли хранить ключ в коде примера?

Нет. Передавайте ключ через переменную RELAY_API_KEY в окружении серверного процесса и не кладите его ни в репозиторий, ни в клиентский JavaScript. Если ключ всё же попал в коммит или на скриншот, отзовите его в кабинете и выпустите новый.

Сколько точек cache_control можно поставить в запросе?

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

С какого запроса кэш начинает окупаться?

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

Источники

Готовы подключиться?Войдите в консоль, пополните баланс и создайте API-ключ.