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

Быстрое кэширование легко потерять. Команда может иметь системное приглашение на 40 000 токенов, схему инструмента, блок политик, карту репозитория или память агента, которые должны быть повторно использованы, а затем случайно поместить метку времени, идентификатор запроса, имя пользователя, фрагмент извлечения или случайный порядок инструментов в верхней части приглашения. Провайдер видит другой префикс, кэш отсутствует, задержка растет, а счет выглядит запутанным.

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

В этой статье описывается эталонная архитектура. Это не исследование конкретного клиента и не претендует на сравнительные результаты. Приведенные ниже факты взяты из документации поставщиков и результатов общественных исследований; Рекомендации по проектированию представляют собой руководство по эксплуатации на уровне шлюза.

Режим отказа: сборка подсказки для взлома кеша

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

К распространенным взломщикам кэша относятся:

<ул>

Метаданные каждого запроса вверху: метки времени, идентификаторы трассировки, идентификаторы сеансов, идентификаторы развертывания или созданные метки запросов.

Данные, относящиеся к пользователю в префиксе: имена, атрибуты учетной записи, разрешения или личные настройки, размещаемые перед повторно используемыми блоками политик или инструментов.

Нестабильная сериализация инструментов: схемы инструментов создаются в недетерминированном порядке с изменяющимися пробелами или сгенерированными идентификаторами.

Фрагменты извлечения слишком ранние: контекст RAG вставлен перед стабильными системными инструкциями или контекстом общего репозитория.

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

Шлюз не может волшебным образом сделать кэшируемым нестабильный префикс, но он может обеспечить выполнение контракта быстрой сборки и сделать видимыми промахи в кэше.

Факты о поставщиках для разработки

Детали имеют значение, поскольку шлюз должен нормализовать поведение, не делая вид, что поставщики идентичны.

<ул>

OpenAI: OpenAI задокументировала кэширование подсказок для самого длинного ранее вычисленного префикса подсказки. Он начинается с 1024 токенов, увеличивается с шагом в 128 токенов и отображает количество кэшированных токенов в полях использования. OpenAI также утверждает, что кэш подсказок обычно очищается через 5–10 минут бездействия и всегда удаляется в течение одного часа после последнего использования кеша.

Антропный: Кэширование антропных запросов можно запросить с помощью cache_control. В его документации описывается сопоставление кэша с компонентами подсказок, такими как инструменты, системное содержимое и сообщения, вплоть до блока, отмеченного контролем кэша. Anthropic документирует эфемерный кэш, включая 5-минутную продолжительность и 1-часовой вариант за дополнительную плату.

Gemini. Кэширование контекста Google Gemini предоставляет сведения о количестве попавших в кеш токенов через метаданные об использовании, такие как total_cached_tokens, а в его документации указано минимальное количество входных токенов по моделям.

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

Сигнал исследования. Общественное исследование показало, могут ли архитектуры типа шлюза создавать уязвимости оперативного кэширования, которые обходят предположения об изоляции кэша на уровне поставщика. Это не доказывает уязвимость конкретного шлюза, но поддерживает консервативную схему изоляции клиентов.

Рекомендация: реализуйте управление кэшем как функцию шлюза с явными политиками, а не как случайный побочный эффект повторяющихся запросов.

Контракт на оперативную сборку для трех регионов

Самое важное проектное решение — разделить стабильный и изменчивый контент до того, как запрос достигнет адаптера поставщика.

Регион 1: стабильный префикс

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

<ул>

основные системные инструкции;

блоки безопасности и политики;

схемы инструментов;

статическая документация по продукту;

карты репозиториев для агентов кодирования;

инструкции фиксированного формата вывода.

Этот регион должен быть детерминированным. Шлюз должен построить его на основе версионных шаблонов, канонизированного JSON и стабильных правил упорядочивания. Если включен реестр инструментов, отсортируйте инструменты по стабильному идентификатору инструмента. Если включены схемы JSON, сериализуйте их с детерминированным порядком ключей и без создания меток времени.

Регион 2: полустабильный контекст клиента или рабочей области

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

<ул>

переопределение политики для конкретного клиента;

белые списки инструментов на уровне рабочей области;

терминология, специфичная для клиента;

соглашения по программированию в команде;

долговечный контекст проекта.

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

Регион 3: изменчивый суффикс

Изменчивый суффикс — это часть каждого запроса:

<ул>

сообщение пользователя;

получены фрагменты по этому запросу;

текущая временная метка, если это действительно необходимо;

идентификатор запроса и метаданные трассировки, если они вообще включены в запрос;

краткосрочные разговоры;

результаты инструмента выполнения.

Большинство ошибок в кэше, вызванных дизайном приложения, происходят из-за того, что данные изменчивого суффикса случайно помещаются в префикс. Разработчик на стороне шлюза должен усложнить эту задачу.

Шаблон реализации: сборщики стабильных префиксов

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

{
  "template_id": "code-agent-v3",
  "tenant_id": "tenant_123",
  "route": "длинный контекст кодирования",
  "stable_prefix": {
    "system_policy_version": "2026-08-01",
    "toolset_version": "tools-v12",
    "repo_context_version": "repo-map-8491"
  },
  "semi_stable_context": {
    "workspace_policy_version": "workspace-44-v6"
  },
  "летучий_суффикс": {
    "user_message": "Объясните, почему этот тест не удался...",
    "retrival_context_ids": ["chunk_7", "chunk_19"],
    "trace_id": "not_inserted_into_prompt"
  }

Затем шлюз обрабатывает запрос конкретного поставщика. Это дает шлюзу возможность применять правила:

<ул>

отклонять временные метки в полях стабильного префикса;

канонизировать схемы инструментов;

хешировать каждый регион отдельно;

прикреплять элементы управления кэшем там, где их поддерживает поставщик;

сохранить семантику подсказок при последующем перемещении изменчивого материала;

записать шаблон и префикс отпечатков пальцев для диагностики.

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

Уровень адаптера поставщика: нормализовать использование кэша, не скрывая различий

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

Создайте нормализованный реестр кэша с такими полями, как:

{
  "request_id": "req_abc",
  "tenant_id": "tenant_123",
  "app_id": "код-агент",
  "route": "длинный контекст кодирования",
  "провайдер": "имя_провайдера",
  "модель": "model_id",
  "template_id": "code-agent-v3",
  "stable_prefix_hash": "sha256:...",
  "semi_stable_hash": "sha256:...",
  «input_tokens_total»: 58200,
  «input_tokens_uncached»: 8200,
  "cache_write_tokens": 50000,
  «cache_read_tokens»: 0,
  «выходные_токены»: 1300,
  "cache_ttl_class": "ephemeral_5m",
  "provider_cache_fields": {
    "raw_field_names": "stored_or_redacted_provider_usage"
  }

Адаптер распределяет использование поставщика по нормализованным категориям:

<ул>

Некэшированные входные токены: токены, обработанные без скидки на чтение кэша или учета чтения кэша.

Токены записи в кэш: токены, которые создавали или обновляли запись кэша на стороне поставщика, когда поставщик сообщает об этом различии.

Токены чтения из кеша: токены, обслуживаемые из кеша или учитываемые как кэшированные метаданными об использовании поставщика.

Токены вывода: генерируемые токены, которые должны оставаться отдельными от экономики кэша подсказок.

Опция TTL: выбранный класс продолжительности кэша, для которого поставщик предоставляет выбор.

Рекомендация. Сохраняйте необработанные сведения об использовании поставщика в отредактированной форме с версионированием схемы вместе с нормализованными полями. Нормализация полезна для информационных панелей; необработанные поля необходимы для сверки при изменении семантики поставщика.

Наблюдаемость за кэшем: информационные панели, объясняющие промахи

Полезная панель мониторинга кэша позволяет не только отображать общее количество кэшированных токенов. Это должно помочь командам ответить на вопрос: «Какая рабочая нагрузка нарушает префикс и что изменилось?»

Отслеживать показатели кэша по:

<ул>

арендатор;

рабочее пространство или приложение;

модельный маршрут;

поставщик и модель;

подсказка версии шаблона;

стабильный хеш префикса;

полустабильный хеш контекста;

Ключ API или учетная запись службы, если это необходимо;

временной интервал, особенно потому, что TTL кэша для многих рабочих нагрузок недостаточен.

К полезным производным показателям относятся:

<ул>

Скорость чтения кэша: количество кэшированных входных токенов, разделенное на общее количество входных токенов, подходящих для кэширования.

Обмен префиксов: количество различных стабильных хешей префиксов на версию шаблона в час.

Дрейф шаблона: изменения в кэше после выпуска шаблона.

Затраты на холодный старт: затраты на запись в кэш или некэшированные входные данные для первого запроса в пакете.

Сравнение маршрутов: коэффициент совпадения между маршрутами поставщика для одной и той же логической рабочей нагрузки.

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

Политика изоляции арендаторов: не проектируйте повторное использование между арендаторами

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

Консервативная политика включает в себя:

<ул>

Маршрутизация с учетом клиента: маршрутизирует кэшируемый трафик с использованием границ клиента, рабочей области и приложения.

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

Отдельные префиксные отпечатки пальцев: вычисляйте отпечатки пальцев с областью клиента, включенной в реестр шлюзов, даже если отображаемый текст идентичен.

Элементы управления на уровне организации позволяют администраторам отключать функции кэширования поставщика для конфиденциальных рабочих нагрузок.

Изоляция поставщика не является функцией продукта, которую можно перепродавать. рассматривайте изоляцию кэша поставщика как базовую защиту, а не как разрешение на создание пула кэша между клиентами.

Прогноз: по мере того, как агенты с длинным контекстом становятся все более распространенными, поведение кэша станет частью проверок безопасности, а не только проверок затрат. Шлюзами, которые подтвердят политику кэширования на уровне клиента, будет легче управлять.

Атрибуция выставления счетов: отдельные операции чтения, записи и обычные токены в кэше

Быстрое кэширование может затруднить понимание счетов, если все входные токены отображаются как одно число. В книге платежей должно быть сохранено как минимум пять категорий:

<ол>

некэшированные входные токены;

кешировать токены записи;

токены чтения кэша;

токены вывода;

плата за TTL или управление кэшем в зависимости от поставщика.

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

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

Контрольный список проверки кэша

Прежде чем включать принудительное кэширование, запустите шаблоны подсказок с помощью контрольного списка проверки:

<ул>

Стабильные системные инструкции появляются раньше нестабильного пользовательского ввода.

Схемы инструментов сортируются по стабильному идентификатору или имени.

JSON сериализуется детерминированно.

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

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

Фрагменты RAG размещаются после повторно используемых разделов политики и инструментов, если нет умышленной причины этого не делать.

Шаблоны подсказок имеют явные версии.

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

Элементы управления кешем поставщика используются только через код адаптера, а не через разрозненную логику приложения.

Журнал необработанных запросов отключен по умолчанию или защищен строгими правилами хранения и доступа.

План внедрения

1. Прежде чем менять подсказки, обратите внимание

Начните со сбора полей использования поставщика и нормализованных показателей кэша для существующего трафика. Вычислите отпечатки префикса для первых N токенов или для регионов подсказок, определенных шлюзом. Цель — найти объемные маршруты с длинным контекстом и высокой сменой префиксов.

2. Классифицировать рабочие нагрузки

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

3. Представляем сборщики стабильных префиксов

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

4. Канарский один маршрут

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

5. Вводить постепенно

После канарейки превратите предупреждения о ворсинках в проверки политик. Например, сначала предупреждайте о нестабильном порядке инструментов, а затем отклоняйте новые версии шаблонов, которые включают изменчивые метаданные в стабильном префиксе.

Компромиссы

<ул>

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

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

Наблюдаемость и конфиденциальное ведение журнала: быстрые различия помогают отлаживать промахи, но хэши и отредактированные диагностические данные являются более безопасными вариантами по умолчанию.

Изоляция арендатора или максимальное повторное использование: широкое повторное использование может выглядеть привлекательно, но поведение на уровне арендатора безопаснее и его легче объяснить.

Более длительное хранение по сравнению с затратами и сложностью политики. Более длинные варианты TTL могут помочь сеансам агентов, но могут привести к другим соображениям по ценообразованию и контролю данных.

Практическое заключение

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

Первый полезный шаг — это не переписывание. Добавьте возможность наблюдения за кэшем к самым длинным запросам, определите отток префиксов и проверьте шаблоны, вызывающие наибольшее количество промахов. Как только вы сможете объяснить поведение кэша, вы сможете его безопасно оптимизировать.

Связанное чтение

• встраивайте категории с поддержкой кэша в книгу счетов
• объединить метрики кэша с безопасным наблюдением LLM
• сохранять контекст получения в пределах области клиента в рабочих нагрузках RAG