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

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

Преимущества

Поддержка провайдерами

Использование с Claude

Для Anthropic Claude требуется явное указание точек кеширования через cache_control:

{
  "model": "anthropic/claude-sonnet-5",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "Вы — эксперт по технической поддержке компании XYZ. Вот наша база знаний: [длинный текст базы знаний]...",
          "cache_control": {
            "type": "ephemeral"
          }
        }
      ]
    },
    {
      "role": "user",
      "content": "Как сбросить пароль?"
    }
  ]
}

TTL задаётся полем ttl внутри cache_control. Отдельный заголовок anthropic-beta: extended-cache-ttl-2025-04-11 не нужен: часовой кеш включается только полем:

{
  "type": "text",
  "text": "[длинный текст]",
  "cache_control": { "type": "ephemeral", "ttl": "1h" }
}

Нативный эндпоинт Anthropic

Кроме OpenAI-совместимого /v1/chat/completions, usellm принимает запросы в нативном формате Anthropic Messages API (POST /v1/messages).

cache_control поддерживается во всех местах, где его допускает Anthropic:

Кешируемый префикс собирается в порядке tools → system → messages: точка кеширования покрывает всё, что стоит выше неё. Изменение инструментов инвалидирует и системный промпт, и историю сообщений.

{
  "model": "anthropic/claude-sonnet-5",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_docs",
      "input_schema": { "type": "object", "properties": {} },
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "system": [
    { "type": "text", "text": "[инструкции]", "cache_control": { "type": "ephemeral" } }
  ],
  "messages": [
    { "role": "user", "content": "Проверь регламент" },
    {
      "role": "assistant",
      "content": [{ "type": "tool_use", "id": "toolu_1", "name": "get_docs", "input": {} }]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_1",
          "content": "[длинный результат]",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    }
  ]
}

Мониторинг кеша

Для OpenAI-совместимого пути информация об использовании кеша возвращается в usage:

{
  "usage": {
    "prompt_tokens": 1500,
    "prompt_tokens_details": {
      "cached_tokens": 1400,
      "cache_write_tokens": 0
    },
    "completion_tokens": 100,
    "total_tokens": 1600,
    "cost": 2.50
  }
}

prompt_tokens - весь вход целиком; cached_tokens и cache_write_tokens лишь расшифровывают, какая его часть прочитана из кеша и какая в него записана.

Нативный эндпоинт /v1/messages отдаёт счётчики в формате Anthropic:

{
  "usage": {
    "input_tokens": 15,
    "output_tokens": 100,
    "cache_creation_input_tokens": 17179,
    "cache_read_input_tokens": 0
  }
}

Здесь input_tokens - только та часть входа, которая не попала в кеш. Полный вход считается как input_tokens + cache_read_input_tokens + cache_creation_input_tokens. На первом запросе токены префикса попадают в cache_creation_input_tokens, на последующих - в cache_read_input_tokens.

Пример экономии

Без кеширования

С кешированием (90% hit rate)

Реальный сценарий

Для техподдержки с 500 запросами в день и 15,000-токенным промптом базы знаний:

• Без кеша: ~6,500 ₽/день
• С кешем (90%): ~650 ₽/день
• Месячная экономия: ~194,000 ₽

Рекомендации

1. Поддерживайте постоянную структуру промптов
2. Используйте cache_control для больших текстов с Claude
3. Группируйте похожие запросы, чтобы чаще попадать в кеш

Ограничения

• Минимальный размер промпта обычно 1000+ токенов
• Не все модели поддерживают кеширование
• TTL варьируется: 5 минут (Claude), неограниченно в пределах сессии (OpenAI)