Кэширование промптов

Если в запросах повторяется большой неизменный кусок (системная инструкция, определения инструментов, длинный контекст), его можно закэшировать. Повторные запросы с тем же префиксом читаются из кэша: дешевле и быстрее, чем считать его заново. Кэширование явное и включается маркерами в самом запросе. Отдельного флага или параметра включения нет: роутер передаёт маркеры провайдеру как есть. ## Как включить Отметьте кэшируемый блок маркером `cache_control` в формате Anthropic. Маркер работает на `/v1/chat/completions` и `/v1/messages`, в трёх местах: блоки `system`, определения `tools` и блоки `content` внутри сообщений. Поле `ttl` задаёт срок жизни кэша: `"5m"` (по умолчанию) или `"1h"`. ```bash frame="terminal" curl https://api.waibee.com/v1/messages \ -H "x-api-key: $WAIBEE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "anthropic/claude-sonnet-4.6", "max_tokens": 1024, "system": [ { "type": "text", "text": "<большая неизменная инструкция или база знаний>", "cache_control": { "type": "ephemeral", "ttl": "1h" } } ], "messages": [{ "role": "user", "content": "Кратко перескажи главное" }] }' ``` На `/v1/chat/completions` маркер ставится на блок `content`: ```bash frame="terminal" curl https://api.waibee.com/v1/chat/completions \ -H "Authorization: Bearer $WAIBEE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "anthropic/claude-sonnet-4.6", "messages": [{ "role": "user", "content": [ { "type": "text", "text": "<большой статичный контекст>", "cache_control": { "type": "ephemeral" } }, { "type": "text", "text": "Сделай TL;DR" } ] }] }' ``` ## Какие модели Явное кэширование поддерживают модели Claude (Anthropic). Проверить можно по каталогу: у модели в `GET /v1/models` в `pricing` есть строки `input_cache_read` и `input_cache_write`, то есть отдельные цены на чтение и запись кэша. Модели OpenAI кэшируют повторяющийся префикс автоматически, без маркеров, и результат виден только в `usage`. ## Поля usage Кэш-попадания видны в `usage`, поля зависят от эндпоинта. `/v1/messages`: ```json "usage": { "input_tokens": 13, "output_tokens": 4, "cache_creation_input_tokens": 8802, "cache_read_input_tokens": 0, "cache_creation": { "ephemeral_1h_input_tokens": 8802, "ephemeral_5m_input_tokens": 0 } } ``` `/v1/chat/completions`: ```json "usage": { "prompt_tokens": 8814, "completion_tokens": 4, "prompt_tokens_details": { "cached_tokens": 0, "cache_write_tokens": 8804 } } ``` Первый запрос записывает кэш (`cache_creation_input_tokens` или `cache_write_tokens` больше нуля). Следующий запрос с тем же префиксом читает из кэша (`cache_read_input_tokens` или `cached_tokens`). ## Что важно помнить - **Префикс должен совпадать байт в байт.** Кэшируется начало запроса до маркера; всё изменяющееся ставьте после него. - **Срок жизни.** Кэш живёт `5m` или `1h` с последнего обращения. По истечении или при изменении префикса он создаётся заново. - **Минимальный размер и число точек кэша** задаёт сам провайдер модели, не роутер: слишком короткий префикс не кэшируется, а число маркеров `cache_control` на запрос ограничено. - **Autorouting.** С моделью `waibee/auto` роутер удерживает одну и ту же модель на время жизни кэша, чтобы попадания были стабильными. Если для запроса с кэшированием не находится подходящей модели, запрос отклоняется с ошибкой `auto_routing_caching_unavailable` (`422`), см. [Autorouting](/router/autorouting/). Стоимость: чтение из кэша дешевле обычного ввода, а первый запрос, который создаёт кэш, немного дороже обычного ввода. Актуальные цены смотрите в каталоге и тарифах.

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

Как включить

Отметьте кэшируемый блок маркером cache_control в формате Anthropic. Маркер работает на /v1/chat/completions и /v1/messages, в трёх местах: блоки system, определения tools и блоки content внутри сообщений.

Поле ttl задаёт срок жизни кэша: "5m" (по умолчанию) или "1h".

curl https://api.waibee.com/v1/messages \
  -H "x-api-key: $WAIBEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.6",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "<большая неизменная инструкция или база знаний>",
        "cache_control": { "type": "ephemeral", "ttl": "1h" }
      }
    ],
    "messages": [{ "role": "user", "content": "Кратко перескажи главное" }]
  }'

На /v1/chat/completions маркер ставится на блок content:

curl https://api.waibee.com/v1/chat/completions \
  -H "Authorization: Bearer $WAIBEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.6",
    "messages": [{ "role": "user", "content": [
      { "type": "text", "text": "<большой статичный контекст>", "cache_control": { "type": "ephemeral" } },
      { "type": "text", "text": "Сделай TL;DR" }
    ] }]
  }'

Какие модели

Явное кэширование поддерживают модели Claude (Anthropic). Проверить можно по каталогу: у модели в GET /v1/models в pricing есть строки input_cache_read и input_cache_write, то есть отдельные цены на чтение и запись кэша. Модели OpenAI кэшируют повторяющийся префикс автоматически, без маркеров, и результат виден только в usage.

Поля usage

Кэш-попадания видны в usage, поля зависят от эндпоинта.

/v1/messages:

"usage": {
  "input_tokens": 13,
  "output_tokens": 4,
  "cache_creation_input_tokens": 8802,
  "cache_read_input_tokens": 0,
  "cache_creation": { "ephemeral_1h_input_tokens": 8802, "ephemeral_5m_input_tokens": 0 }
}

/v1/chat/completions:

"usage": {
  "prompt_tokens": 8814,
  "completion_tokens": 4,
  "prompt_tokens_details": { "cached_tokens": 0, "cache_write_tokens": 8804 }
}

Первый запрос записывает кэш (cache_creation_input_tokens или cache_write_tokens больше нуля). Следующий запрос с тем же префиксом читает из кэша (cache_read_input_tokens или cached_tokens).

Что важно помнить

Префикс должен совпадать байт в байт. Кэшируется начало запроса до маркера; всё изменяющееся ставьте после него.
Срок жизни. Кэш живёт 5m или 1h с последнего обращения. По истечении или при изменении префикса он создаётся заново.
Минимальный размер и число точек кэша задаёт сам провайдер модели, не роутер: слишком короткий префикс не кэшируется, а число маркеров cache_control на запрос ограничено.
Autorouting. С моделью waibee/auto роутер удерживает одну и ту же модель на время жизни кэша, чтобы попадания были стабильными. Если для запроса с кэшированием не находится подходящей модели, запрос отклоняется с ошибкой auto_routing_caching_unavailable (422), см. Autorouting.

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