Диагностика кэша

Кэширование подсказок значительно снижает задержку и стоимость, но только если начало вашей подсказки побайтово идентично недавнему запросу. Переупорядоченный инструмент, временная метка, подставленная в вашу системную подсказку, или правка в более раннем сообщении могут незаметно инвалидировать кэш. Без диагностики кэша единственным сигналом является падение usage.cache_read_input_tokens до нуля — без какого-либо указания на то, что изменилось.

Диагностика кэша закрывает этот пробел. Передайте id вашего предыдущего ответа, и API сравнит два запроса и сообщит вам, где они разошлись (модель, системная подсказка, инструменты или история сообщений), чтобы вы могли устранить первопричину, а не гадать.

Как работает диагностика кэша

Когда бета-заголовок присутствует, API сохраняет облегчённый отпечаток (fingerprint) каждого запроса, привязанный к id ответа. В следующем запросе включите этот id как diagnostics.previous_message_id. API заново строит отпечаток для нового запроса, сравнивает его с сохранённым и прикрепляет к ответу объект diagnostics, описывающий первую точку расхождения.

Сравнение касается структуры запроса и не зависит от того, сработал ли кэш на самом деле. См. раздел Чтение диагностики вместе с usage, чтобы узнать, как объединить результат diagnostics с usage.cache_read_input_tokens.

Отпечатки содержат только хэши и оценки количества токенов (никогда — сырое содержимое подсказки), хранятся ограниченное время, привязаны к вашей организации и рабочему пространству и не используются ни для каких других целей.

Базовое использование

Отправляйте бета-заголовок на каждом ходе. На первом ходе передайте "previous_message_id": null, чтобы включить функцию без предыдущего сообщения для сравнения. На последующих ходах передавайте id из предыдущего ответа.

client = anthropic.Anthropic()

SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>"

# Ход 1: включаем функцию, передав previous_message_id=None
r1 = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=SYSTEM,
    messages=[{"role": "user", "content": "Summarize section 1."}],
    diagnostics={"previous_message_id": None},
    betas=["cache-diagnosis-2026-04-07"],
)

# Ход 2: ссылаемся на идентификатор предыдущего ответа
r2 = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=SYSTEM,
    messages=[
        {"role": "user", "content": "Summarize section 1."},
        {"role": "assistant", "content": r1.content},
        {"role": "user", "content": "Now summarize section 2."},
    ],
    diagnostics={"previous_message_id": r1.id},
    betas=["cache-diagnosis-2026-04-07"],
)

diagnostics = r2.diagnostics
if diagnostics is None:
    print("No divergence detected.")
elif diagnostics.cache_miss_reason is None:
    print("Comparison still pending.")
else:
    print(f"cache_miss_reason: {diagnostics.cache_miss_reason.type}")

Потоковая передача

В ответах с потоковой передачей diagnostics появляется в событии message_start.

# Ход 2: потоковая передача со ссылкой на идентификатор предыдущего ответа
with client.beta.messages.stream(
    model="claude-opus-4-8",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=SYSTEM,
    messages=[
        {"role": "user", "content": "Summarize section 1."},
        {"role": "assistant", "content": r1.content},
        {"role": "user", "content": "Now summarize section 2."},
    ],
    diagnostics={"previous_message_id": r1.id},
    betas=["cache-diagnosis-2026-04-07"],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    print()
    r2 = stream.get_final_message()

diagnostics = r2.diagnostics
if diagnostics is None:
    print("No divergence detected.")
elif diagnostics.cache_miss_reason is None:
    print("Comparison still pending.")
else:
    print(f"cache_miss_reason: {diagnostics.cache_miss_reason.type}")

Событие message_start содержит полное поле diagnostics; возможные значения см. в разделе Формат ответа.

Передача диагностики через цикл разговора

В многоходовом разговоре переносите последний id ответа вперёд как previous_message_id на каждом ходе. Первая итерация передаёт null, чтобы включить функцию; каждая последующая итерация передаёт id из предыдущего ответа.

Формат ответа

Поле diagnostics в ответе Message имеет четыре возможных состояния:

Когда cache_miss_reason не равен null, он выглядит так:

{
  "id": "msg_01Xyz...",
  "type": "message",
  "role": "assistant",
  "content": [{ "type": "text", "text": "..." }],
  "usage": {
    "input_tokens": 42,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 41850,
    "output_tokens": 210
  },
  "diagnostics": {
    "cache_miss_reason": {
      "type": "system_changed",
      "cache_missed_input_tokens": 41850
    }
  }
}

Типы причин промаха кэша

cache_miss_reason — это размеченное объединение (discriminated union) по полю type. В ответе сообщается только о самом раннем расхождении, поэтому сначала исправьте его; более поздние могут быть скрыты за ним.

Чтение диагностики вместе с usage

diagnostics отвечает на вопрос «изменился ли мой запрос?», тогда как usage.cache_read_input_tokens отвечает на вопрос «сработал ли кэш?». Их сочетание подсказывает, где искать.

Эта матрица применяется к ходам, где вы передали реальный previous_message_id. На первом ходе (previous_message_id: null) diagnostics всегда равен null, а cache_read_input_tokens обычно равен нулю, потому что кэш записывается, а не читается; устранение неполадок не требуется. Матрица также не применяется, когда cache_miss_reason равен null (сравнение ещё выполняется; проверьте на следующем ходе) или когда его type равен previous_message_not_found или unavailable (сравнение не было произведено).

Ограничения

• Бета: Имена полей и семантика могут измениться до общедоступного выпуска.
• Только Claude API: Недоступно в Amazon Bedrock или Vertex AI.
• Ограниченное хранение: Отпечатки для поиска по previous_message_id истекают через короткий период. Выполняйте диагностические сравнения между близко расположенными по времени запросами.
• То же рабочее пространство: Предыдущий запрос должен был быть сделан с ключом API из той же организации и рабочего пространства.
• Горизонт сравнения: Для очень длинных разговоров, где единственное изменение находится глубоко в списке сообщений, ответ может быть unavailable вместо точного местоположения.
• По мере возможности: Диагностика никогда не блокирует и не приводит к сбою вашего запроса. Если диагностическая информация недоступна, ответ возвращает unavailable или cache_miss_reason: null, когда сравнение ещё выполнялось.

Хранение данных

Диагностика кэша соответствует требованиям ZDR (квалифицирована). Anthropic не хранит сырой текст ваших подсказок или выводов Claude для этой функции.

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

О соответствии требованиям ZDR для всех функций см. API и хранение данных.

См. также

• Кэширование подсказок
• Подсчёт токенов
• Бета-заголовки