OpenAI Prompt Cache Diagnostics стал GA: что нельзя убирать на уровне gateway

Отладка промахов prompt cache в OpenAI API всегда была неприятным занятием. Длинный системный промпт, включённое 24-часовое окно кеширования — а usage.input_tokens_details.cached_tokens возвращает ноль. Никакого намёка на то, что изменилось. Просто некешированные токены и счёт выше ожидаемого.

8 сентября 2026 года OpenAI выпустил Prompt Cache Diagnostics в general availability для Responses API. Функция добавляет структурированное поле prompt_cache_diagnostics в ответы, объясняя конкретно, почему prefix не был переиспользован. Для команд, направляющих запросы к GPT-5.6 или GPT-6 Astra через gateway или router, важны два момента: как выглядит API, и что нельзя с ним делать на proxy-уровне.

Как работает диагностический интерфейс

Механизм намеренно сделан узким. Вы передаёте prompt_cache_options.comparison_response_id с id предыдущего response, prefix которого текущий запрос должен был переиспользовать. OpenAI сравнивает два запроса и заполняет prompt_cache_diagnostics, если обнаруживает промах.

second = client.responses.create(
    model="gpt-6-astra",
    instructions=policy,
    input="Reply with exactly OK.",
    tools=[{"type": "function", "name": "get_date"}],
    prompt_cache_options={"comparison_response_id": first.id},
)

diagnostics = second.prompt_cache_diagnostics
if diagnostics is not None and diagnostics.type == "cache_miss":
    print(diagnostics.reason)                       # например, "tools_changed"
    print(diagnostics.comparison_reusable_tokens)   # токены, которые могли попасть в кеш
    print(diagnostics.cache_missed_tokens)           # токены, которые фактически промахнулись

Поле reason — это ключевая новая операционная информация. В документации приводится пример tools_changed: срабатывает, когда определения function tools или их порядок изменяются между запросами. В руководстве по prompt caching всегда указывалось, что определения инструментов входят в отрендеренный prefix — стоит изменить порядок или добавить инструмент посередине сессии, и весь prefix после этой точки инвалидируется. Чего не было до сих пор — способа подтвердить, что именно это и произошло.

Diagnostics доступна для GPT-5.6 и более новых моделей через Responses API. Минимальная длина кешируемого prefix для GPT-5.6 — 1024 токена. comparison_response_id должен принадлежать той же организации. Передача этого поля только запрашивает диагностику и не меняет поведение кеша для текущего запроса.

Влияние на gateway и router

Здесь командам, использующим proxy-слой, нужно проверить свои настройки. Многие AI gateway — включая middleware, нормализующий тела запросов перед отправкой в OpenAI — могут удалять неизвестные или нестандартные поля. Если gateway убирает prompt_cache_options до того, как запрос доходит до API, prompt_cache_diagnostics никогда не появится в ответе. Диагностический сигнал молча исчезает: запрос успешен, кеш промахивается, причина по-прежнему неизвестна.

Та же проблема касается обработки списка инструментов. Gateway-слои, которые сортируют или дедуплицируют определения tools перед передачей, — на первый взгляд безобидная нормализация — будут инвалидировать cache prefix в каждом запросе, где канонический порядок отличается от upstream-порядка. С появлением diagnostics этот паттерн теперь можно обнаружить: reason: "tools_changed" будет появляться в последовательных запросах, даже если код приложения список инструментов не трогал. Если вы видите такой паттерн, трансформация происходит на уровне routing, а не в приложении.

Практическая проверка: посмотрите, присутствует ли prompt_cache_options в теле запроса, который gateway реально отправляет в OpenAI. Если поля нет, добавьте его в passthrough-список. Если определения инструментов переупорядочиваются логикой нормализации, сохраняйте порядок вставки.

Взгляд в разрезе провайдеров

У Anthropic нет эквивалентного диагностического интерфейса. Когда запрос к Sonnet или Fable промахивается мимо кеша, usage.cache_read_input_tokens равно нулю — это весь сигнал. Нет структурированных кодов причин, нет сравнения на уровне токенов с базовым запросом. Для команд, направляющих трафик на модели OpenAI и Anthropic по разным маршрутам, это реальный разрыв в observability. Промахи кеша на пути OpenAI теперь можно разбирать точечно; на пути Anthropic всё ещё приходится рассуждать по разнице в счётчиках токенов до и после.

TTL кеша у двух провайдеров тоже различается. Модели Claude по умолчанию кешируют на 5 минут (расширяется до часа через cache_control: {"type": "ephemeral"}), модели OpenAI в большинстве случаев — от 5 до 10 минут, с возможностью 24-часового расширенного окна для организаций без ZDR. Gateway, маршрутизирующий между провайдерами, должен учитывать, какая модель кеширования применяется к каждому пути, и соответственно настраивать downstream-мониторинг. Diagnostics значительно упрощают инструментирование OpenAI-ветки.

Что меняется в операционном мониторинге

До этого релиза типичный подход — отслеживать соотношение input_token_count к cached_tokens во времени и поднимать алерт при падении ниже порога. Это сигнал на уровне популяции: полезен для оповещений, но не для root cause. С prompt_cache_diagnostics можно прикреплять структурированные причины промахов к отдельным запросам и агрегировать их: сколько промахов в день приходится на tools_changed, сколько на другие причины, меняется ли это распределение после деплоя.

Diagnostics также сочетается с Prompt Caching Dashboard, который OpenAI выпустил в августе. Dashboard показывает агрегированные hit rate и количество cache reads на write на уровне организации и проекта. Diagnostics позволяет привязать отклонения в этих цифрах к конкретным паттернам запросов.

Что стоит проверить в своей инфраструктуре

Для routing-слоя появление Prompt Cache Diagnostics — скорее повод для аудита, чем срочное изменение. Есть несколько конкретных вещей, которые стоит проверить. Во-первых, передаёт ли ваш gateway prompt_cache_options прозрачно или игнорирует его. Во-вторых, сохраняется ли порядок определений инструментов на всём пути от приложения до OpenAI API. В-третьих, если вы маршрутизируете multi-turn диалоги, может ли запрос нести id предыдущего response для запуска диагностического сравнения.

Последний пункт особенно важен для agent-сценариев с понятием сессии. Cache hit rate в длинных сессиях сильно влияет на стоимость, а деградацию часто вызывают изменения в списке инструментов или смена модели — именно то, о чём поле reason теперь умеет рассказывать.