AI / LLM

Prompt caching: чтение запроса и usage

Суть Читай реальные тела запросов Anthropic SDK и блоки usage, предсказывай, где встаёт cache breakpoint и попадёт ли он, и выбирай фикс наибольшего рычага.

Высота — путь к senior

НольJuniorMiddleSenior

Ты на senior-высоте — в орбите

◷ 14 min

Тело запроса решает, что кэшируется; блок usage говорит, сработало ли. Читай оба, предсказывай поведение и выбирай фикс, который сеньор делает первым — до того, как трогать TTL.

Цель

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

Сниппет 1 — куда встаёт breakpoint?

system = [
    {"type": "text", "text": SYSTEM_PROMPT},          # ~2k токенов, стабильно
    {"type": "text", "text": BIG_POLICY_DOC,           # ~28k токенов, стабильно
     "cache_control": {"type": "ephemeral"}},
]
messages = [
    {"role": "user", "content": f"As of {now()}: {question}"},
]

Викторина

Breakpoint поставлен корректно на последнем стабильном блоке, но кэш ни разу не попадает. Почему?

Сниппет 2 — блок usage

{
  "usage": {
    "input_tokens": 41,
    "cache_creation_input_tokens": 30218,
    "cache_read_input_tokens": 0,
    "output_tokens": 215
  }
}

Викторина

Этот блок usage повторяется на каждом запросе в устойчивом высокочастотном трафике. О чём он говорит?

Сниппет 3 — TTL и порядок tools

client.messages.create(
    model="claude-sonnet-4-6",
    tools=serialize_tools(registry.values()),   # dict → list, порядок не гарантирован
    system=[{"type": "text", "text": SYSTEM,
             "cache_control": {"type": "ephemeral", "ttl": "1h"}}],
    messages=[{"role": "user", "content": q}],
)

Викторина

1-часовой TTL выставлен и системный промпт стабилен, но hit rate скачет от деплоя к деплою. Какой фикс с наибольшим рычагом?

Сниппет 4 — арифметика точки окупаемости

# Sonnet 4.6: базовый вход $3.00/MTok, запись в кэш (5м) $3.75/MTok, чтение из кэша $0.30/MTok
# стабильный префикс на 20k токенов, перечитан N раз внутри окна TTL
write_cost = 20_000/1e6 * 3.75          # одна запись
read_cost  = 20_000/1e6 * 0.30 * N      # N чтений
uncached   = 20_000/1e6 * 3.00 * (N+1)  # те же N+1 запросов, без кэша

Викторина

При такой цене после скольких чтений кэширование префикса на 20k становится дешевле, чем не кэшировать вовсе?

Итог

Любой вопрос о кэше читается в теле запроса и блоке usage. Breakpoint кэширует весь префикс вплоть до своего блока включительно, поэтому он принадлежит последнему стабильному блоку — но стабильный breakpoint бесполезен, если блоки перед ним (сначала tools, затем system) не побайтно идентичны, отчего недетерминированный порядок tools и ре-сериализованные пробелы — топовые отравители. Поля usage — единственная правда: высокий cache_creation при cache_read около нуля на устойчивом трафике — отравленный префикс, а не успех. А арифметика окупаемости жестока в пользу кэша — перечитываемый префикс бьёт полную ставку уже после одного чтения, так что реальная работа — держать префикс стабильным, а не тюнить TTL.

Продолжить восхождение ↑Prompt caching: измерь экономию