Как настроить Prompt Caching в Claude API и проверить cache_read_input_tokens

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

Секрет храните в переменной окружения. Не помещайте его в браузерный JavaScript, статью, промпт или журнал. В рабочую систему переходите только после теста на копии данных.

Пошаговая настройка

1. Разделите запрос на стабильный префикс и переменный хвост. В префикс положите tools, системные правила и редко меняющийся документ именно в порядке, указанном документацией.
2. Добавьте cache_control типа ephemeral к последнему блоку, который должен войти в кеш. Не отмечайте случайный request_id перед документом.
3. Отправьте первый запрос и сохраните usage.cache_creation_input_tokens. Затем повторите запрос с тем же префиксом и новым вопросом.
4. Подтвердите usage.cache_read_input_tokens. Нулевая величина означает, что кеш не прочитан; проверьте порядок блоков, модель и изменение префикса.
5. Выполните негативный тест: переставьте два tool definition или измените начало документа. После этого верните исходный порядок.

После каждого вызова сохраняйте request ID, HTTP-статус, модель, версию конфигурации и usage, если сервис его возвращает. Полный чувствительный ввод в обычный лог не копируйте. Повтор запроса после таймаута разрешайте только после проверки состояния предыдущей операции.

Готовый шаблон

Скопируйте основу и замените значения в квадратных скобках:

SYSTEM BLOCK [cache_control: ephemeral]
Ты отвечаешь только по политике ниже. Для каждого факта возвращай section_id.
POLICY_VERSION: 2026-09-12
[СТАБИЛЬНЫЙ ДОКУМЕНТ]

USER BLOCK
case_id=[ID]
question=[ВОПРОС]
Не найдено в политике -> answer=null.

Шаблон намеренно требует явного null или missing вместо догадки. Если результат будет читать программа, формат проверяется схемой, а значения — отдельными бизнес-правилами.

Реалистичный пример

Первый вызов создаёт кеш для политики возврата, второй меняет только вопрос. Ожидается рост cache_read_input_tokens во втором usage. Если вместе с вопросом меняется POLICY_VERSION в начале, совпадающий префикс может сократиться.

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

Как измерить качество

Создайте таблицу с колонками case_id, expected, actual, source, status, error_type. Идентификаторы, суммы, даты и единицы сравнивайте посимвольно. Для найденного факта храните document_id или точный фрагмент исходника.

Разделяйте ошибки на четыре класса: format_error — результат нельзя разобрать; unsupported_claim — факт отсутствует во входе; wrong_action — вызвана неверная операция; security_error — раскрыт секрет или обойдены права. Каждый класс требует своего исправления. Новый промпт не чинит авторизацию, а JSON Schema не подтверждает истинность суммы.

Правило выпуска задайте до теста: ноль security_error и wrong_action, все ID совпадают, отсутствующие данные не додумываются, а внешний вызов виден в журнале. Если критический кейс провален, измените одну причину и прогоните весь набор заново.

Контроль в рабочем приложении

Разделите сетевой вызов и использование результата. Первый слой принимает вход, присваивает case_id и проверяет размер, тип и права. Второй вызывает API с таймаутом. Третий разбирает ответ и применяет схему. Четвёртый сверяет бизнес-ограничения. Только после этого данные разрешено показывать пользователю или передавать в следующий узел.

Для наблюдаемости считайте количество успешных запросов, отказов валидации, таймаутов и повторов. Не смешивайте их в один процент «успеха». Отдельно отслеживайте долю ответов, отправленных на ручную проверку. Резкий спад технических ошибок при росте unsupported_claim означает, что формат улучшился, но содержание стало хуже.