Одна строка в начале промпта обнуляет кеш Claude API: как найти утечку

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

Почему кеш ломается и сколько это стоит?

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

Типичная ошибка выглядит так:

system = f"Current time: {datetime.now()}.\n{POLICY}\n{KNOWLEDGE_BASE}"

Время меняется на каждом вызове. Префикс расходится на четвёртом слове. Весь промпт, все 2 000 токенов политик и базы знаний, каждый раз идёт по полной цене. Хотя содержание не менялось ни разу.

По замерам на support-агенте с системным блоком около 1 200 токенов и четырьмя вопросами подряд результат такой:

• Время перед статикой: ноль попаданий в кеш из примерно 1 180 токенов промпта.
• Время после статики: 1 152 токена из примерно 1 180 пришли из кеша.

Для агента с промптом в 1 200 токенов и 10 000 вызовов в день разница в расходах кратная.

Какие утечки не видны глазами?

Строку datetime.now() в начале промпта разработчик заметит сам. Но есть случаи, которые без инструмента не найти:

• Схемы инструментов. У Anthropic кеш покрывает tools, system, messages именно в этом порядке. Схемы инструментов лежат в самом начале префикса, до системного промпта. Если они собираются из словаря с плавающим порядком ключей, кеш ломается в первой позиции, и в коде промпта этого не видно.
• База знаний из неупорядоченного набора. Содержимое одно и то же, но порядок элементов между процессами разный.
• Префикс совпал, а кеша нет. Сборка правильная, но cache_read_tokens равен нулю. Значит, истёк TTL (время жизни кеша) или провайдер не кеширует на уровне маршрутизации.
• Шаблон, который рендерится по-разному под нагрузкой. Условный блок попадает в промпт раз в сто вызовов и сдвигает весь префикс.

Общее у всех четырёх: промпт большой, изменение маленькое, глазами не найти.

Как попробовать?

1. Установите prefixcash: pip install prefixcash. Нужен Python 3.11 или новее.
2. Добавьте логирование. Пять строк поверх любого OpenAI-совместимого SDK: после каждого вызова записывайте в JSONL-файл поля usage (как отдал провайдер) и messages. С LiteLLM (библиотека-обёртка для работы с разными провайдерами через единый интерфейс) хватит трёх строк: litellm.callbacks = [PrefixCashCallback(file="metrics.jsonl")].
3. Запустите диагностику: prefixcash diagnose --file calls.jsonl --session live-broken. Инструмент покажет процент кешируемого префикса, длину общего префикса в словах и назовёт виновника, например dynamic_time.
4. Для пользователей Claude Code лог уже на диске. Достаточно двух команд: python -m examples.import_claude_code --out cc.jsonl и prefixcash report --file cc.jsonl. Адаптер переносит только поля usage, тексты промптов не читаются.

Минимум для диагностики: два вызова в одной сессии. Не нужны тысячи запросов и день накопления.

Какие паттерны распознаёт инструмент?

prefixcash умеет находить: iso_datetime, datetime, date, time, uuid, hex_token, number, email, url_query, placeholder (переменные вида {var}).

Плюс два универсальных детектора:

• high_entropy, ловит сгенерированные строки по энтропии Шеннона (мера непредсказуемости символов).
• content_change, любое расхождение, не подошедшее ни под один шаблон.

Виновник будет назван и позиция показана, даже если конкретный случай никто не предусматривал.

Что показал бенчмарк на живых вызовах?

Пять сценариев с живыми вызовами к DeepSeek, по две сборки на каждый. Важная деталь: на коротком промпте кеш у DeepSeek не включается (порог примерно от 1 024 токенов), никакой фикс не даёт ничего, и инструмент честно пишет NO GAIN. Это отрицательный контроль: если бы там стояло красивое число, остальным результатам нельзя было бы верить.

Две оговорки от автора инструмента: base $ в отчёте, это контрфактическая цена по прайсу pay-as-you-go, а не возврат на карту. И запись в кеш у Anthropic стоит дороже обычного токена (1.25x для пятиминутного TTL, 2x для часового), prefixcash этого пока не моделирует и завышает экономию примерно на 2%.

Сравнение с российскими аналогами

В России два основных провайдера больших языковых моделей через API: YandexGPT и GigaChat. Ни один из них на момент публикации не предлагает явного механизма кеширования промптов, аналогичного тому, что есть у Anthropic, OpenAI и DeepSeek. Это значит, что проблема кеш-утечек для пользователей российских API пока не актуальна, но и экономить на повторяющихся промптах через кеш не получится. Если вы работаете с Claude API или DeepSeek из России через прокси или VPN, инструмент prefixcash применим в полной мере.

Что делать с этим прямо сейчас, по ролям

Автору на Дзене, который использует Claude API для генерации или редактирования текстов: проверьте, не вставляет ли ваш скрипт дату, время или идентификатор сессии в начало системного промпта. Если да, перенесите эту строку в конец. Одно изменение, и кеш заработает.

Разработчику или маркетологу, который строит чат-ботов или support-агентов на Claude API: установите prefixcash и запустите diagnose на реальных логах. Даже если вам кажется, что промпт собран правильно, плавающий порядок ключей в схемах инструментов или неупорядоченный набор в базе знаний могут ломать кеш незаметно.

Предпринимателю в РФ, который платит за API через посредника: запросите у разработчика отчёт prefixcash по вашему боевому трафику. Это бесплатный способ понять, не переплачиваете ли вы за каждый вызов.

Частые вопросы

prefixcash работает только с Claude API?

Нет. Инструмент работает с любым провайдером, у которого есть префиксный кеш и поле usage в ответах. В публикации показаны живые замеры на DeepSeek. Для OpenAI, где кеш включается автоматически, инструмент тоже применим: он анализирует стандартные поля из ответа API.

Нужно ли отправлять свои данные куда-то?

Нет. prefixcash не делает сетевых запросов. Он считает по полям usage, которые уже лежат в вашем локальном логе. Единственное место, где читается файл, это модуль импорта, его код открыт и занимает 70 строк.

Сколько вызовов нужно накопить для диагностики?

Минимум два вызова в одной сессии. Команда diagnose сравнивает соседние вызовы, поэтому хватит одного живого диалога из двух реплик. Тысячи запросов и день накопления не нужны.