Как проверить prompt caching в OpenRouter и не потерять cache hit

Этот сценарий полезен разработчику backend, владельцу чат-бота или команде автоматизации, которой нужен наблюдаемый результат. Ключевой принцип: проверять не только текст модели, но и метаданные маршрутизации, структуру ответа, учет токенов и негативный путь. HTTP 200 означает, что транспорт сработал; он не доказывает, что модель соблюла бизнес-формат.

Подтвержденные факты

• Большинство поддерживаемых провайдеров включает кэш автоматически, некоторым нужен cache_control.
• OpenRouter применяет provider sticky routing после кэшируемого запроса.
• Липкая сессия истекает после 10 минут бездействия; успешный запрос сбрасывает таймер.
• cache hit отражается в usage.prompt_tokens_details.cached_tokens.

Параметры OpenRouter задаются на двух разных уровнях. model, messages, response_format относятся к запросу генерации. Объект provider управляет выбором upstream-endpoint. Плагины маршрутизаторов передаются в plugins. Не переносите поле из одного уровня в другой: JSON останется синтаксически корректным, но настройка может не дать ожидаемого эффекта.

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

1. Сформулируйте проверяемый результат. Для запроса «как включить prompt caching OpenRouter» не принимайте субъективное «вроде работает»: заранее запишите ожидаемый формат и признаки ошибки.
2. Создайте отдельный API-ключ для тестового приложения и передавайте его через переменную окружения OPENROUTER_API_KEY. Не вставляйте секрет в клиентский JavaScript, мобильный APK, скриншот или репозиторий.
3. Соберите минимальный запрос из примера ниже. Он изолирует именно механизм статьи; дополнительные фреймворки, ретраи и бизнес-логику добавляйте после первого успешного ответа.
4. Отправьте запрос на https://openrouter.ai/api/v1/chat/completions. При ошибке сначала сохраните HTTP-код, тело ответа и request id, а уже затем решайте, допустим ли повтор.
5. Сравните результат с контрольным ожиданием: На первом запросе возможна запись кэша; на повторном с тем же стабильным префиксом cached_tokens должен стать больше нуля, если пороги и endpoint поддерживают кэш.
6. Прогоните положительный и отрицательный тест. Отрицательный тест должен доказать, что приложение не принимает невалидный формат, запрещенную модель или ослабленную политику после fallback.
7. Только после этого добавьте таймаут, ограниченный retry с jitter, метрики и безопасное логирование. Повторяйте лишь идемпотентные операции или используйте собственный ключ идемпотентности.

Минимальный рабочий пример

{"model":"<CACHE_CAPABLE_MODEL>","session_id":"kb-agent-v1","messages":[{"role":"system","content":"<LONG_STABLE_INSTRUCTION_AND_KNOWLEDGE_BASE>"},{"role":"user","content":"Составь ответ клиенту по пункту 4.2"}]}

Значения в угловых скобках — не реальные идентификаторы. Их нужно заменить slug из актуальной страницы модели OpenRouter. Такой шаблон безопаснее статьи с быстро устаревающим списком моделей или провайдеров. Токен доступа в пример намеренно не включен.

Готовый тестовый промпт

Задача: проверь конфигурацию «как включить prompt caching OpenRouter».
Верни только результат в указанном формате, без вступления.
Если входных данных недостаточно, верни явную ошибку INPUT_MISSING и перечисли недостающие поля.
Не придумывай факты и не изменяй ограничения запроса.

Промпт нужен для проверки дисциплины ответа, но он не заменяет параметры API. Например, просьба «верни JSON» не дает тех же гарантий, что response_format; фраза «не сохраняй данные» не заменяет ZDR-фильтр; просьба «выбери быструю модель» не заменяет настройки маршрутизации. Управляющие ограничения следует задавать структурированными полями запроса, а затем повторно проверять в приложении.

Контрольный вход и ожидаемый результат

Контрольный вход уже встроен в пример. Не меняйте одновременно prompt, модель и маршрутизацию: иначе невозможно понять причину различий. Сначала выполните запрос пять раз с одной конфигурацией, сохраните HTTP-код, id, model, finish_reason, usage и длительность. Затем измените ровно один параметр и повторите серию.

Ожидаемый результат: На первом запросе возможна запись кэша; на повторном с тем же стабильным префиксом cached_tokens должен стать больше нуля, если пороги и endpoint поддерживают кэш.

Если текст формально правильный, но отсутствует model или usage, не подменяйте их нулями без отдельного статуса. Различайте «ноль», «поле не поддерживается» и «финальное событие не было прочитано». Для JSON-ответов применяйте декодер и схему. Для обычного текста проверяйте длину, обязательные маркеры и отсутствие служебных фрагментов.

Критерии приемки

• session_id одинаков для цепочки
• статический префикс байт-в-байт совпадает
• cached_tokens сохранен
• cache_write_tokens анализируется где доступен
• сравнивается фактическая стоимость