Кэширование запросов

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

В примере ниже $TEXT_MODEL — переменная окружения с идентификатором модели из GET /api/v1/models. Идентификаторы не зашивают в код: состав каталога меняется. Разбор — в разделе Модели и цены.

Как это работает

Кэшируются не отдельные фрагменты, а префикс — начало запроса, вплоть до точки, помеченной явно. Всё, что идёт после точки, в кэш не попадает.

{
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "<длинный справочник, одинаковый на каждый запрос>",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    },
    { "role": "user", "content": "<вопрос, который меняется от запроса к запросу>" }
  ]
}

cache_control: {"type": "ephemeral"} ставится на блок контента, а не на сообщение целиком — блок должен быть в массиве content. Единственный поддерживаемый тип сейчас — ephemeral.

cURL

curl -s https://speshu.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$TEXT_MODEL"'",
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "Ты — ассистент поддержки. Отвечай по правилам: ...",
            "cache_control": {"type": "ephemeral"}
          }
        ]
      },
      {"role": "user", "content": "Где найти настройки уведомлений?"}
    ]
  }' | jq '.usage.prompt_tokens_details, .usage.cost'

Первый запрос кэш наполняет, но платит по полной ставке. Экономия появляется со второго — при условии, что префикс совпал.

Где видно, что сработало

Единственный достоверный источник — поле usage.prompt_tokens_details.cached_read_tokens в ответе:

"usage": {
  "prompt_tokens": 12000,
  "prompt_tokens_details": {
    "text_tokens": 2000,
    "cached_read_tokens": 10000
  },
  "cost": {
    "input_cost": 0.0412,
    "output_cost": 0.0031,
    "total_cost": 0.0443
  }
}

cached_read_tokens — сколько входных токенов прочитано из кэша. prompt_tokens при этом включает их: не складывайте.

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

Ставки и минимумы

Размер скидки, минимальный кэшируемый объём и время жизни кэша задаёт каждый провайдер по-своему, и эти значения меняются. Таблицы множителей нет: она устареет быстрее, чем её успеют сверить.

Авторитетные числа по конкретному запросу — в самом ответе:

Python

usage = response["usage"]
details = usage.get("prompt_tokens_details", {})

prompt = usage["prompt_tokens"]
cached = details.get("cached_read_tokens", 0)
fresh = prompt - cached

print(f"всего входа: {prompt}, из кэша: {cached} ({cached / prompt:.0%}), списано: {usage['cost']['total_cost']} ₽")

Считайте экономию как отношение, а не как вычитание из чеков: cached / prompt на двух соседних запросах покажет, работает кэш или нет.

Проектирование стабильного префикса

Чтобы кэш срабатывал, материал в начале запроса должен быть побайтово одинаков от запроса к запросу. Практические правила: Кэшируйте самое тяжёлое и самое стабильное. Справочник, правила, описание домена, few-shot примеры. Переменное — в хвост.

Python

# правильно: стабильное в начале, переменное в конце
messages = [
    {
        "role": "system",
        "content": [{"type": "text", "text": STABLE_GUIDE, "cache_control": {"type": "ephemeral"}}],
    },
    *turns,          # история диалога
    {"role": "user", "content": question},
]

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

Что ломает кэш

Действие	Почему ломает
Изменение системного промпта	Новый префикс целиком
Изменение списка `tools`	Инструменты входят в кэшируемый префикс
Добавление сообщения в начало	Сдвигает весь префикс
Смена модели	Кэш привязан к модели
Перестановка или переформулировка блоков	Побайтовое несовпадение
Переменные данные внутри кэшируемого блока	Тот же сдвиг префикса

Самая частая ошибка — вставка переменной в начало кэшируемого блока, например «Сегодня , отвечай…». Кэш перестаёт срабатывать с первого запроса, и вы платите полную ставку, не получая никакой экономии и никакого сообщения об ошибке. Переносите дату и идентификаторы за пределы блока с cache_control.

Разделение по арендаторам

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

Параметр	Зачем
`prompt_cache_key`	Ключ кэша для этого запроса. Одинаковый ключ при неизменном префиксе — попадание в один кэш
`prompt_cache_isolation_key`	Граница изоляции: материал с разными значениями не смешивается в один кэш

{
  "prompt_cache_isolation_key": "tenant-4821",
  "prompt_cache_key": "tenant-4821:knowledge-base:v7",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "<справочник конкретного арендатора>",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    },
    { "role": "user", "content": "Вопрос" }
  ]
}

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

Отладка

cached_read_tokens всегда 0

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

Кэш срабатывает, но экономии нет

Сравните cost двух запросов с разным cached_read_tokens. Если разница близка к нулю, провайдер либо не даёт скидки на этой модели, либо вы смотрите на общую стоимость вместе с выходными токенами, которые сопоставимы по величине. Считайте по входной части.

Кэш срабатывает у одного арендатора и не у другого

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

Что дальше

Учёт средств

Как читать usage и cost по каждому запросу

Модели и цены

Ставки за вход и выход

Токены рассуждений

Вторая статья расходов в том же объекте usage

Лимиты

Тарифные квоты поверх кэша

Начало работы

Возможности моделей

Генерация медиа

Фреймворки

Базы данных

Агенты и редакторы

No-code и автоматизация

Как это работает

Где видно, что сработало

Ставки и минимумы

Проектирование стабильного префикса

Что ломает кэш

Разделение по арендаторам

Отладка

Что дальше

Учёт средств

Модели и цены

Токены рассуждений

Лимиты

​Как это работает

​Где видно, что сработало

​Ставки и минимумы

​Проектирование стабильного префикса

​Что ломает кэш

​Разделение по арендаторам

​Отладка

​Что дальше

Учёт средств

Модели и цены

Токены рассуждений

Лимиты

Как это работает

Где видно, что сработало

Ставки и минимумы

Проектирование стабильного префикса

Что ломает кэш

Разделение по арендаторам

Отладка

Что дальше