Разработчики обнаружили, что кэширование промптов в Claude может работать со скрытыми ошибками: система взимает плату по премиальным тарифам, возвращая при этом ноль кэшированных токенов. Недельный анализ логов обработчика WhatsApp показал полное отсутствие чтений из кэша, однако API выставлял счета за использование функции кэширования — что в данном случае снизило расходы с 1890 до 406 долларов в месяц.

Почему это важно

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

Как проявляется этот баг

API принимает флаг cache-control и префикс, а затем сообщает, сколько токенов было прочитано из кэша. В наблюдаемом случае каждый запрос возвращал значение «количество прочитанных из кэша токенов», равное нулю. Вызов проходил успешно, исключение не выбрасывалось, но в счетах отражалась стоимость премиального кэширования. Сбой незаметен, если вы явно не ведете логирование количества чтений.

Распространенные причины поломки кэша

  • Префикс слишком короткий — каждая модель Claude определяет минимальную длину токенов для кэшируемого префикса. Для Haiku 4.5 требуется минимум 4096 токенов; для Sonnet 4.6 — всего 1024. Отправка более короткого префикса соответствует формату запроса, но сервис игнорирует инструкцию кэширования.
  • Смещение изменчивого байта — кэширование требует точного побайтового совпадения. Добавление динамического элемента, такого как временная метка, new Date() или email пользователя в начало системного промпта, меняет последовательность байтов, из-за чего каждый запрос обрабатывается как новая, не кэшированная запись.
  • Изменение порядка списка инструментов — инструменты добавляются в начало промпта. Если массив инструментов строится на основе ключей объекта, порядок итерации может меняться от вызова к вызову, что смещает структуру байтов и ломает кэш.

Решения, которые можно применить уже сегодня

  • Проверяйте длину префикса — перед отправкой запроса оценивайте количество токенов в префиксе на соответствие минимуму модели. Если префикс слишком короткий, отклоняйте запрос или дополняйте его (padding).
  • Логируйте чтение кэша при каждом вызове — записывайте значение поля «cache read tokens». Серия нулей — явный признак того, что кэш не используется.
  • Зафиксируйте начальные байты промпта — не допускайте попадания динамических данных в кэшируемый сегмент. Если вам необходимо включить информацию о пользователе, размещайте её после кэшируемого префикса.
  • Синхронизируйте идентификаторы моделей — убедитесь, что ID модели, используемый при маршрутизации, совпадает с ID, хранящимся в вашей таблице кэша; несовпадение ID препятствует поиску в кэше.

Аспект стоимости

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

Контраргумент

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

На что обратить внимание в дальнейшем

  • Дашборды метрик — добавьте индикатор количества прочитанных токенов кэша наряду с объемом запросов.
  • Стабильность порядка инструментов — если вы полагаетесь на динамически генерируемые списки инструментов, рассмотрите возможность их детерминированной сортировки перед встраиванием в промпт.

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