캐시 진단

프롬프트 캐싱은 지연 시간과 비용을 크게 줄여주지만, 프롬프트의 시작 부분이 최근 요청과 바이트 단위로 동일할 때만 효과가 있습니다. 도구 순서 변경, 시스템 프롬프트에 삽입된 타임스탬프, 또는 이전 메시지 편집은 캐시를 조용히 무효화할 수 있습니다. 캐시 진단이 없으면 유일한 신호는 usage.cache_read_input_tokens가 0으로 떨어지는 것뿐이며, 무엇이 변경되었는지에 대한 표시는 없습니다.

캐시 진단은 이러한 간극을 메웁니다. 이전 응답의 id를 전달하면 API가 두 요청을 비교하여 어디에서 달라졌는지(모델, 시스템 프롬프트, 도구 또는 메시지 기록) 알려주므로 추측하는 대신 근본 원인을 해결할 수 있습니다.

캐시 진단 작동 방식

베타 헤더가 있으면 API는 응답 id를 키로 하여 각 요청의 경량 "fingerprint"(지문)를 저장합니다. 다음 요청에서 해당 id를 diagnostics.previous_message_id로 포함하세요. API는 새 요청에 대한 지문을 다시 생성하고 저장된 지문과 비교한 다음, 첫 번째 분기 지점을 설명하는 diagnostics 객체를 응답에 첨부합니다.

이 비교는 캐시가 실제로 적중했는지 여부와 무관하게 요청 구조에 관한 것입니다. 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: 이전 응답 id를 참조
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: 이전 응답 ID를 참조하여 스트리밍
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를 전달합니다.

응답 형식

응답 Message의 diagnostics 필드는 네 가지 가능한 상태를 가집니다.

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은 type에 대한 구별된 유니온입니다. 응답은 가장 이른 분기점만 보고하므로 먼저 이를 수정하세요. 이후의 분기점은 그 뒤에 숨겨져 있을 수 있습니다.

사용량과 함께 진단 읽기

diagnostics는 "내 요청이 변경되었는가?"에 답하고 usage.cache_read_input_tokens는 "캐시가 적중했는가?"에 답합니다. 이 둘을 결합하면 어디를 살펴봐야 하는지 알 수 있습니다.

이 매트릭스는 실제 previous_message_id를 전달한 턴에 적용됩니다. 첫 번째 턴(previous_message_id: null)에서는 diagnostics가 항상 null이고 캐시가 읽히는 것이 아니라 쓰이고 있기 때문에 cache_read_input_tokens는 일반적으로 0입니다. 문제 해결이 필요하지 않습니다. 또한 이 매트릭스는 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 적격(qualified)입니다. Anthropic은 이 기능을 위해 프롬프트의 원시 텍스트나 Claude의 출력을 저장하지 않습니다.

각 요청에 대해 저장되는 지문은 암호화 해시와 토큰 수 추정치로만 구성되며, 응답 id를 키로 하고 조직 및 워크스페이스로 범위가 지정됩니다. 지문은 짧은 기간 후에 만료되며 다른 용도로는 사용되지 않습니다.

모든 기능에 대한 ZDR 적격성은 API 및 데이터 보관을 참조하세요.

참고 항목

• 프롬프트 캐싱
• 토큰 계산
• 베타 헤더