Prompt caching

Anthropic-модели (Claude) поддерживают кеширование частей промпта на стороне провайдера. Это даёт значительную экономию, когда вы много раз отправляете один и тот же длинный системный промпт или контекст с разными user-сообщениями.

Когда это работает

• Длинный системный промпт (≥1024 токена) — описание роли ассистента, гайдлайны, документация.
• Большой контекст в начале — RAG-сниппеты, долгая история диалога.
• Повторные вызовы в течение 5 минут — Anthropic кешит на ~5-минутный TTL.

Если у вас короткий промпт или вы дёргаете API раз в час — кеширование не сэкономит ничего.

Как включить

Передайте cache_control в content-блоке сообщения:

curl -s https://api.hubris.pw/v1/chat/completions \
  -H "Authorization: Bearer sk-gw-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-haiku-4.5",
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "Очень длинная инструкция на 5000 токенов...",
            "cache_control": {"type": "ephemeral"}
          }
        ]
      },
      {
        "role": "user",
        "content": "Ваш вопрос"
      }
    ]
  }'

Маркер cache_control: { type: "ephemeral" } ставится на content-блок, который вы хотите закешировать. Часто это весь системный промпт или большой документ в начале первого user-сообщения.

Биллинг

В ответе usage появятся дополнительные поля от Anthropic:

{
  "usage": {
    "prompt_tokens": 5050,
    "completion_tokens": 100,
    "prompt_tokens_details": {
      "cached_tokens": 5000
    }
  }
}

cached_tokens — то, что было прочитано из кеша. У Anthropic стоимость cache-read обычно в 10× дешевле обычных prompt-токенов; cache-write — в 1.25× дороже.

Важная оговорка по биллингу Hubris. Сейчас (на 2026-05) Hubris списывает фиксированную цену по prompt_tokens без отдельной формулы для cache-read. Это значит — даже если у вас 90% prompt-токенов прочитаны из кеша и стоили провайдеру copейки, мы возьмём с вас полную ставку каталога. Когда это будет переделано на правильную формулу (prompt_tokens × full + cached_tokens × cache_read_discount), цена в каталоге может измениться. Следите за Changelog.

Если вам важна экономия от кеширования и текущий биллинг не подходит — пишите в support@hubris.pw, обсудим.

Что закешировать

Эффективные кандидаты:

• System prompt с гайдлайнами и примерами (5–20k токенов) — основная экономия.
• RAG-контекст — если шлёте те же документы много раз в течение 5 минут.
• Длинный one-shot пример — для классификаторов или агентов.

Не имеет смысла кешировать:

• Каждое user-сообщение (они уникальны).
• Маленькие промпты (< 1024 токена).
• Запросы реже раза в 5 минут (cache TTL истечёт).

Что дальше

• POST /v1/chat/completions — полная схема.
• Каталог моделей — какие Anthropic-модели доступны.
• Цены — про токенный биллинг.