캐시 진단

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

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



캐시 진단 작동 방식

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

이 비교는 캐시가 실제로 적중했는지 여부와 무관하게 요청 구조에 관한 것입니다. diagnostics 결과를 usage.cache_read_input_tokens와 결합하는 방법은 usage와 함께 진단 읽기를 참조하세요.

핑거프린트는 해시와 토큰 수 추정치만 포함하며(원시 프롬프트 내용은 절대 포함하지 않음), 제한된 시간 동안만 보관되고, 조직 및 워크스페이스 범위로 제한되며, 다른 목적으로 사용되지 않습니다.



기본 사용법

모든 턴에서 베타 헤더를 전송하세요. 첫 번째 턴에서는 비교할 이전 메시지 없이 옵트인하기 위해 "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-5",
    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-5",
    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-5",
    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을 기준으로 하는 판별 유니온입니다. 응답은 가장 이른 분기만 보고하므로 먼저 이를 수정하세요. 이후의 분기는 그 뒤에 숨겨져 있을 수 있습니다.



usage와 함께 진단 읽기

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 또는 Google Cloud에서는 사용할 수 없습니다.
• 제한된 보관: previous_message_id 조회를 위한 핑거프린트는 짧은 기간 후에 만료됩니다. 시간적으로 가까운 요청 간에 진단 비교를 실행하세요.
• 동일한 워크스페이스: 이전 요청은 동일한 조직 및 워크스페이스의 API 키로 이루어져야 합니다.
• 비교 범위: 유일한 변경이 메시지 목록 깊숙한 곳에 있는 매우 긴 대화의 경우, 응답이 정확한 위치 대신 unavailable일 수 있습니다.
• 최선 노력 방식: 진단은 요청을 차단하거나 실패시키지 않습니다. 진단 정보를 사용할 수 없는 경우 응답은 unavailable을 반환하거나, 비교가 아직 실행 중이었던 경우 cache_miss_reason: null을 반환합니다.



데이터 보관

캐시 진단은 ZDR 적격(qualified)입니다. Anthropic은 이 기능을 위해 프롬프트의 원시 텍스트나 Claude의 출력을 저장하지 않습니다.

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

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



참고 자료

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