작성자 주석: Claude 프롬프트 캐시 적중률이 갑자기 0으로 떨어졌거나 청구서가 계속 줄지 않는다면, diagnostics 세 단계로 프리픽스가 갈라지는 위치를 찾고 usage를 함께 봐서 캐시가 실제로 적중했는지 판단할 수 있어요. 이 글에서는 APIYI 중계 서비스를 이용할 때 어떻게 자체 점검하는지도 설명해요. (혹시 이 문제를 겪고 있다면, 글을 다 읽은 뒤 이 글을 여러분의 Agent에게 보내서 점검하게 해보세요.)
캐시가 적중하지 않는 건 신비한 일이 아니에요. API가 프리픽스가 어느 지점에서 갈라지는지 알려주거든요. 직전 응답의 id를 다시 넘겨주기만 하면, 처음으로 일치하지 않는 지점이 model, system, tools, messages 중 어디인지 바로 확인할 수 있어요.
이건 기능 출시 해설 글이 아니에요. Claude 프롬프트 캐시를 이미 쓰고 있는데 적중률이 갑자기 0이 됐거나 청구서가 계속 높은 개발자를 위한 글이에요. 모든 점검 단계마다 무엇이 보이는지 명확하게 적어둘게요.
핵심 가치: 이 글을 읽고 나면 세 번의 요청 안에 캐시가 무효화된 원인을 찾아낼 수 있어요. diagnostics와 usage가 각각 무엇을 알려주는지 구분할 수 있고, 중계 서비스를 쓸 때 어떤 두 필드를 서로 비교해야 하는지도 알게 돼요.
Claude 캐시 진단 diagnostics 핵심 요점
먼저 한 문장으로 무엇인지 정리해볼게요: 직전 응답의 id를 넘기면 API가 두 요청을 비교해서, 첫 번째 분기점이 model, system, tools, messages 중 어디에서 생겼는지 짚어줍니다. 예전에는 캐시가 조용히 깨졌을 때 usage.cache_read_input_tokens가 0이 된 것만 보일 뿐, 어느 구간이 바뀐 건지는 알 수 없었어요.
| 항목 | 설명 | 얻을 수 있는 것 |
|---|---|---|
| 스위치 | 요청 본문 최상위에 diagnostics 객체가 있어야 지문을 저장 |
비즈니스 로직은 그대로 두고 필드 하나만 추가하면 돼요 |
| 비교 방식 | previous_message_id에 직전 응답 id를 전달 |
첫 번째 분기 구간을 바로 찾아줘요 |
| 결과 필드 | cache_miss_reason이 여섯 가지 유형 중 하나를 알려줘요 |
유형마다 수정할 위치가 명확해요 |
| 함께 볼 지표 | usage.cache_read_input_tokens와 같이 봐야 해요 |
「분기 없음」을 「적용 안 됨」으로 오판하지 않게 해줘요 |
| 사용 범위 | 공식 Claude API에서만 제공 | 다른 경로로 호출한다면 usage 자체 점검으로 대체해야 해요 |
Claude 캐시 진단 타임라인
이 기능은 2026년 5월에 베타 형태로 출시됐고, 그때는 anthropic-beta: cache-diagnosis-2026-04-07 헤더를 붙여야 했어요. 9월에 규칙이 한 차례 더 엄격해졌는데, diagnostics 객체를 명시적으로 담은 요청만 지문을 저장하고 헤더만 붙인 요청은 기록되지 않았어요.
9월 23일에는 정식 버전으로 전환되면서 cache-diagnosis-2026-04-07이 필요 없어졌고, 예전 헤더를 붙인 요청도 평소처럼 동작해요. 이제 POST /v1/messages 응답에는 항상 diagnostics 필드가 나오고, 활성화하지 않았을 때 값은 null이에요. 그러니까 이 필드가 null이라고 해서 인터페이스에 문제가 생긴 건 아니에요.
지문에는 해시와 토큰 수 추정치만 저장되고 원본 프롬프트 내용은 저장되지 않아요. response id 기준으로 인덱싱되고, 적용 범위는 이 조직과 이 workspace로 한정되며, 보존 기간도 짧은 편이에요.
3단계로 diagnostics로 Claude 캐시 적중률 진단하기
아래 세 단계는 공식 필드 설명을 기준으로 정리했어요. APIYI를 통해 호출한다면 Messages 네이티브 인터페이스의 base_url에 https://api.apiyi.com/v1을 넣고, 요청 경로는 /v1/messages예요. 다만 뒤쪽 실측 부분에서 API 중계 서비스 환경에서 diagnostics가 실제로 어떻게 돌아오는지 설명할 테니 함께 봐두세요.
1단계: 요청 최상위에 diagnostics 객체 추가하기
diagnostics가 유일한 스위치예요. 이걸 넣지 않은 요청은 지문을 저장하지 않기 때문에 나중에 비교할 대상 자체가 없어요. 첫 라운드에는 비교할 대상이 없으니 previous_message_id에 null을 넣어요. ‘이번 라운드부터 기록을 시작한다’는 뜻이에요.
- 요청 헤더에는 일반 버전 번호를 그대로 유지하세요:
anthropic-version: 2023-06-01 - 정식 버전 이후에는 더 이상 넣을 필요가 없어요:
anthropic-beta: cache-diagnosis-2026-04-07 - 요청 본문 최상위에 이렇게 추가하세요:
"diagnostics": {"previous_message_id": null} - 캐시가 필요한 system 블록은 평소처럼 브레이크포인트를 걸어주세요:
"cache_control": {"type": "ephemeral"} - 이때 보이는 것: 응답의
diagnostics는null이고,cache_read_input_tokens는 보통 0이며cache_creation_input_tokens는 0보다 커요
첫 라운드에서 null이 나온다고 실패한 건 아니에요. 이 라운드는 캐시를 쓰는 단계라 애초에 비교할 이전 라운드가 없거든요. 트러블슈팅할 필요가 없어요.
2단계: 이후 매 라운드마다 이전 라운드 응답의 id 전달하기
두 번째 라운드부터는 이전 라운드 응답의 id를 previous_message_id에 넣어요. 가장 흔한 실수는 첫 라운드에만 diagnostics를 넣고 그다음부터 빠뜨리는 거예요. 그러면 다음 라운드가 가리키는 요청이 기록되어 있지 않아서 previous_message_not_found가 돌아와요.
- 두 번째 라운드 요청 본문:
"diagnostics": {"previous_message_id": "<첫 라운드 응답의 id>"} - 세 번째 라운드 요청 본문:
"diagnostics": {"previous_message_id": "<두 번째 라운드 응답의 id>"} - 여러 라운드를 반복하는 규칙: 첫 라운드는
null, 두 번째는r1.id, 세 번째는r2.id, 이런 식으로 이어가요 - 스트리밍 호출에서는 결과가
message_start이벤트에 담겨 나오고, id 역시 라운드마다 계속 이어서 전달해요 - 이때 보이는 것: 인접한 두 라운드의 간격이 충분히 짧고 같은 workspace 안에 있으면 응답에 비교 결과가 나타나기 시작해요
3단계: cache_miss_reason 읽고 원인별로 고치기
diagnostics 값은 세 가지예요. 읽기 전에 먼저 구분해 두세요.
null: 요청에diagnostics가 없거나,previous_message_id가null이거나, 비교는 끝났는데 불일치가 발견되지 않은 경우{"cache_miss_reason": null}: 응답이 너무 빨리 시작돼서 비교가 아직 진행 중인 경우예요. 이번 라운드에서는 결론을 내리지 않고 다음 라운드를 봐요cache_miss_reason이 객체인 경우: 이미 결론이 나온 상태로, 안에 분기 유형과 세부 정보가 들어 있어요- 이때 보이는 것: 유형을 확인했으면 다음 섹션의 대조표대로 수정하세요. 가장 먼저 발생한 분기부터 고치는 게 중요해요. 첫 번째 불일치 지점만 보고하기 때문에 뒤쪽 문제는 그 뒤에 가려져 있을 수 있거든요
🚀 빠른 시작: 내 캐시 접두사가 제대로 기록되고 적중하는지 먼저 확인해 보고 싶다면, APIYI apiyi.com에서 같은 Key로 Claude 여러 모델을 번갈아 두 라운드씩 호출해 비교해 보세요. usage 안의 캐시 쓰기와 읽기 숫자가 서로 맞아떨어지는지 보는 게 핵심이에요.
cache_miss_reason 여섯 가지 유형과 수정 위치
cache_miss_reason을 받았다면, 아래 표를 보고 어디를 고쳐야 할지 대응시키면 돼요:
| 유형 | 의미 | 수정할 곳 |
|---|---|---|
model_changed |
이전 턴과 모델이 달라요. 라우팅, A/B 테스트, 폴백(fallback) 등으로 모델이 바뀐 경우죠. 캐시는 모델 단위로 격리돼요 | 같은 캐시 대화 구간에서는 모델을 고정하세요 |
system_changed |
system이 바뀌었어요. 가장 흔한 건 타임스탬프나 요청 ID처럼 매번 달라지는 값을 넣는 거예요 | system은 바이트 단위로 항상 똑같은 상수로 만들고, 동적 데이터는 중단점(breakpoint) 이후 첫 번째 user 메시지로 옮기세요 |
tools_changed |
도구가 추가·삭제되거나 순서가 바뀌었거나, input_schema 직렬화 결과가 불안정한 경우예요 |
매 턴 같은 도구 목록을 보내고, 순서는 고정하고, 직렬화할 때는 키 기준으로 정렬하세요 |
messages_changed |
끝에 덧붙인 게 아니라 이전 메시지가 수정·재배치·삭제된 경우예요 | 히스토리는 뒤에 추가만 하고, assistant 내용과 도구 결과는 원래 그대로 다시 전달하세요 |
previous_message_not_found |
해당 지문(fingerprint)을 찾을 수 없는 경우인데, 요청이 바뀌었다는 뜻은 아니에요 | 매 턴 diagnostics를 함께 보내고, workspace를 넘나들지 말고, 간격을 너무 길게 두지 마세요 |
unavailable |
이번 턴에 진단 결과를 얻지 못한 경우예요. tool_choice, thinking, context_management, output_config, output_format 또는 beta header 집합이 일치하지 않거나, 대화가 너무 길 때도 그럴 수 있어요 |
하나의 캐시 대화 생명주기 전체에서 이 파라미터들을 변함없이 유지하세요 |
네 가지 *_changed 유형에는 cache_missed_input_tokens도 함께 붙어요. 분기점 이후에 캐시 가능한 입력 토큰이 대략 얼마나 사라졌는지를 나타내죠. 이 값은 바이트 길이를 환산한 것이라서 규모를 가늠하는 용도일 뿐, 청구 금액 숫자는 아니에요. 간혹 usage.input_tokens보다 클 때도 있어요.
diagnostics만 보면 오판해요: usage와 함께 Claude 캐시 적중 판단하기
diagnostics는 “내 요청이 바뀌었나”를 답하고, usage.cache_read_input_tokens는 “캐시가 적중했나”를 답해요. 두 질문은 서로 다르기 때문에 하나만 보면 잘못된 결론에 도달하기 쉬워요.
| diagnostics 결과 | 캐시 읽기 토큰 | 결론 | 대응 |
|---|---|---|---|
null |
높음 | 접두사가 안정적, 캐시 적중 | 따로 처리할 것 없음 |
null |
낮음 또는 0 | 요청은 그대로인데 캐시가 만료됨 | 요청 간격을 줄이거나 1시간 TTL로 변경 |
*_changed |
낮음 | 요청이 바뀌어 적중 실패 | 앞 절의 대조표대로 수정 |
*_changed |
높음 | 변화가 뒤쪽에서 발생, 앞쪽 중단점은 여전히 적중 | 고칠 가치는 있지만 영향은 작음 |
다시 한 번 강조할게요: null은 “효과 없음”이 아니에요, 오히려 그게 가장 좋은 결과일 수 있어요. 이 표가 적용되지 않는 경우도 몇 가지 있어요. 첫 번째 라운드, cache_miss_reason이 null인 경우(비교가 아직 진행 중), 그리고 previous_message_not_found와 unavailable이에요. 이런 경우에는 유효한 비교 자체가 만들어지지 않았어요.
어느 라운드가 어느 칸에 속하는지 아직 감이 안 온다면, APIYI apiyi.com에서 같은 요청을 두 라운드 연속으로 보내고 라운드마다 캐시 읽기/쓰기 수치를 기록한 다음, 위 매트릭스와 하나씩 대조해 보세요.
Claude 캐시 적중률이 낮은 흔한 원인: 세 가지 필수 조건
적중률이 낮은 경우는 대개 요청이 바뀌어서가 아니라, 캐시가 처음부터 기록되지 않았기 때문이에요. 아래 세 조건 중 하나라도 빠지면 캐시는 적용되지 않아요:
cache_control을 반드시 명시적으로 지정해야 해요: 구체적인 콘텐츠 블록에 붙여서 명시적 중단점으로 쓸 수도 있고, 요청 최상위에cache_control하나를 두면 시스템이 마지막 캐시 가능 블록에 자동으로 중단점을 찍어줘요. content가 순수 문자열이라 마커를 붙일 콘텐츠 블록이 없다면 절대 캐시되지 않아요.- 최소 캐시 가능 길이를 충족해야 해요: Claude API에서 Sonnet 5.5와 Opus 5.5는 모두 512 토큰이에요. 프리픽스가 충분히 길지 않으면 캐시는 조용히 무시되고 에러도 나지 않아요.
- 프리픽스가 바이트 단위로 동일해야 해요: 히스토리는 추가만 하고, system과 tools는 안정적으로 유지해야 해요. 공백, JSON 필드 순서, 타임스탬프 중 어느 하나라도 바뀌면 새로운 프리픽스로 취급돼요.
APIYI의 캐시 문서에는 두 가지 하드 리밋도 적혀 있어요. 요청 한 번에 cache_control 중단점은 최대 4개까지이고, 각 중단점은 최근 20개 콘텐츠 블록까지만 거슬러 올라가요. 긴 멀티턴 대화에서 마지막 메시지에만 마킹하면 전체 히스토리를 커버할 수 없어요.
TTL도 자주 놓치는 부분이에요. 기본값은 5분이고 적중할 때마다 갱신되지만, 타이머는 응답이 끝난 시점이 아니라 쓰기 또는 읽기 요청이 시작된 시점부터 계산돼요. 스트리밍 응답이 4분 동안 출력됐다면 다음 요청은 대략 1분 안에 보내야 해요. 더 긴 윈도우가 필요하면 cache_control에 "ttl": "1h"를 적으면 돼요.
Claude 캐시 적중률이 0으로 떨어졌을 때의 비용 계산
먼저 가격부터 정리할게요. 단위는 달러/백만 토큰이고, 데이터 시점은 2026-10-25이며 콘솔의 실시간 가격을 기준으로 해요:
| 모델 | 입력 | 출력 | 캐시 읽기 | 5분 쓰기 | 1시간 쓰기 |
|---|---|---|---|---|---|
| Claude Sonnet 5.5 | $2 | $10 | $0.10 | $2.50 | $4 |
| Claude Opus 5.5 | $4 | $20 | $0.20 | $5 | $8 |
| Claude Haiku 5.5 (10만 토큰 이내) | $0.1 | $0.5 | $0.01 | $0.125 | $0.20 |
| Claude Haiku 5.5 (10만 토큰 초과) | $0.50 | $2.50 | $0.05 | $0.625 | $1 |
배율은 따로 봐야 해요. APIYI 캐시 가이드에서 제시하는 일반적인 기준은 적중 0.1×, 5분 쓰기 1.25×, 1시간 쓰기 2×예요. Sonnet 5.5는 10월 7일 공식 조정에 맞춰 캐시 읽기가 $0.20에서 $0.10으로 내려가 기본 입력가의 0.05×가 됐고, 쓰기 가격은 그대로예요.
이번 조정은 전체 라인업 인하가 아니에요. Sonnet 5의 캐시 읽기는 여전히 $0.20이죠. 그러니 0.1×를 가지고 Sonnet 5.5를 계산하면 안 되고, 구체적인 모델과 가격은 플랫폼의 모델 목록을 기준으로 삼아야 해요.
손익분기점은 플랫폼의 일반적인 0.1× 기준으로 계산해요. 5분 TTL은 두 번만 재사용하면 본전을 뽑고(1.25 + 0.1 = 1.35, 캐시를 안 쓸 때의 2.0보다 낮음), 1시간 TTL은 세 번 재사용해야 해요(2 + 0.2 = 2.2, 3.0보다 낮음).
계산 예시를 하나 더 볼까요. Sonnet 5.5, 고정 프리픽스 3만 토큰, 하루 200회 요청, 전부 5분 TTL 안에 들어오는 상황이에요:
- 전부 적중: 200 × 3만 × $0.10/백만 = $0.60, 여기에 쓰기 1회 $0.075를 더하면 약 $0.675/일
- 전부 미적중: 200 × 3만 × $2/백만 = $12/일
두 경우의 하루 청구서 차이는 약 17.8배예요. 이건 단가 차이가 아니에요. 단가는 $2 대 $0.10으로 20배 차이죠. 1시간 TTL로 바꾸면 쓰기 1회가 $0.12이고 적중 가격은 그대로예요. 요청 간격이 5분을 자주 넘긴다면, 이렇게 더 내는 쓰기 비용과 프리픽스를 반복해서 다시 만드는 비용 중 어느 쪽이 더 낮은지 한번 비교해 보세요.
APIYI를 통해 사용할 때 Claude 캐시 적중률을 점검하는 방법
먼저 실측 결과부터 말씀드릴게요. 2026-10-26에 APIYI에서 Claude Sonnet 5.5로 두 라운드를 돌렸어요. 첫 번째 라운드는 캐시 쓰기 2523, 읽기 0이었고, 두 번째 라운드에서 응답을 그대로 다시 보내자 캐시 읽기 2523, 쓰기 0으로 토큰 수가 정확히 맞아떨어졌어요. Claude Opus 5.5도 긴 프리픽스를 쓰면 동일하게 쓰기와 적중이 이뤄졌어요.
그런데 응답에는 diagnostics 필드가 없었어요. 비스트리밍 호출에도 없었고, 스트리밍 호출의 message_start에도 없었어요. beta 헤더를 붙여 다시 보내 보고, system을 일부러 수정해 실제 불일치 상황(읽기 0, 쓰기 2526)까지 만들어 봤지만 응답에는 여전히 이 필드가 없었어요. 모든 요청은 200을 반환했고 오류도 없었어요. 중계 계층의 업스트림 채널이 반드시 공식 Claude API인 것은 아니기 때문에, 중계 환경에서는 주로 usage 안의 두 필드를 서로 비교하는 방식에 의존하게 돼요.
| 자체 점검 현상 | 설명 |
|---|---|
이번 라운드 cache_read_input_tokens가 이전 라운드 cache_creation_input_tokens와 정확히 일치 |
프리픽스 전체 적중 |
| 이번 라운드 읽기가 이전 라운드 쓰기보다 뚜렷하게 작음 | 앞쪽 일부 구간만 적중, 중간에 내용이 바뀜 |
| 쓰기가 계속 0 | 마커를 안 붙였거나, 길이가 부족하거나, OpenAI 호환 형식을 사용 |
| 두 번째 라운드에서 다시 쓰기가 발생하고 읽기는 0 | 프리픽스가 바뀜, 타임스탬프·UUID·직렬화 순서 확인 |
또 하나 특히 주의할 점이 있어요. 캐시는 네이티브 /v1/messages에서만 동작해요. OpenAI 호환 형식인 /v1/chat/completions로 Claude를 호출하면 파라미터를 어떻게 전달하든 캐시 과금 혜택을 받을 수 없어요.
💡 점검 팁: APIYI(apiyi.com)는
cache_control을 그대로 업스트림에 전달하고, 응답의 두 캐시 필드도 원본 그대로 반환해요. 그래서 코드에서 중계 계층을 위해 따로 맞춰줄 필요가 없어요. ‘이번 라운드 읽기 = 이전 라운드 쓰기’를 로그 알림으로 걸어두면 대부분의 수동 점검을 대신할 수 있어요.
Claude 캐시 진단 diagnostics의 한계
diagnostics가 모든 문제를 해결해 주지는 않아요. 사용하기 전에 그 경계를 먼저 알아두세요:
- 공식 Claude API에서만 제공되고, Amazon Bedrock이나 Google Cloud에서 호스팅하는 Claude에는 없어요
- 지문(fingerprint)은 단기간만 보관되기 때문에, 연속된 여러 라운드에 걸쳐 짧은 간격으로 요청을 보내야 해요
- 두 요청은 반드시 같은 조직과 같은 workspace에 속해야 하고, 응답 헤더
anthropic-workspace-id로 확인할 수 있어요 - 긴 대화에서는 변화가 메시지 목록 아주 깊은 위치에 숨어 있으면
unavailable만 돌아올 수 있어요 - best-effort 메커니즘이라서, 결과를 못 받아도 요청이 막히거나 실패하지는 않아요
자주 묻는 질문 FAQ
Q1: 왜 diagnostics가 계속 null인가요?
세 가지 경우로 나뉘어요. `diagnostics` 객체를 안 붙였거나, 지금이 첫 라운드라서 `previous_message_id`가 `null`이거나, 비교가 완료됐는데 차이가 없는 경우예요. 캐시 수치와 함께 판단해야 하는데, 수치가 높으면 정상이라는 뜻이고 0이면 대부분 캐시가 만료된 거예요. 중계 서비스를 쓰고 있다면 이 필드가 아예 반환되지 않을 수 있으니, 그럴 때는 usage로 자체 점검하세요.
Q2: previous_message_not_found가 나오면 요청이 바뀐 건가요?
아니에요. 그냥 대응하는 지문을 찾지 못했다는 뜻일 뿐이에요. 흔한 원인은 세 가지예요. 이전 라운드에 `diagnostics`를 안 붙였거나, 이전 라운드가 다른 workspace에서 왔거나, 간격이 너무 길었던 경우죠. 매 라운드마다 `diagnostics`를 붙이고 간격을 줄이면 해결돼요.
Q3: 진단에 추가 요금이 붙나요?
공식 문서에는 ‘진단 비용’을 별도 항목으로 명시하지 않았고, 일반 Messages 요청과 함께 과금돼요. 문서에 추가 요금이 없다고 명확히 적혀 있지도 않으니, 과금은 청구서와 콘솔을 기준으로 확인하세요.
Q4: 중계 서비스를 써도 이 진단을 쓸 수 있나요?
APIYI에서 실측해 본 결과 `diagnostics` 필드는 받지 못했지만, 캐시 쓰기와 히트는 정상이었어요. ‘이번 라운드의 읽기 값이 이전 라운드의 쓰기 값과 정확히 같은가’로 판단할 수 있고, 연동 방법은 APIYI apiyi.com의 캐시 과금 문서를 참고하세요.
Q5: cache_control을 썼는데 왜 한 번도 캐시에 안 들어가나요?
먼저 세 가지를 확인하세요. content가 순수 문자열인지, 프리픽스가 512 tokens(Sonnet 5.5와 Opus 5.5)에 도달했는지, OpenAI 호환 형식으로 보내고 있지는 않은지요. 이 중 하나라도 충족되지 않으면 캐시는 조용히 건너뛰어져요.
Q6: 여러 문제가 동시에 나타나면 뭘 먼저 고쳐야 하나요?
`cache_miss_reason`이 알려주는 것부터 먼저 고치세요. 가장 이른 분기점만 알려주기 때문에, 그걸 고치고 다시 한 라운드 돌려야 뒤에 가려져 있던 문제가 드러나요. APIYI apiyi.com에서 같은 요청을 반복 재생하면 하나씩 빠르게 걸러낼 수 있어요.
Claude 캐시 진단 핵심 요점 Key Takeaways
- diagnostics가 뭔가요: 직전 응답의 id를 넘겨서 프리픽스가 처음 갈라지는 구간을 찾아내는 기능이에요
- 어떻게 켜나요: 최상위에
diagnostics를 두고, 첫 번째 턴에는null을, 그 이후 매 턴마다 반드시 전달해야 해요 null의 의미: 첫 턴이거나 분기가 없을 때도null이 나오기 때문에, 이것만 보고 장애 신호로 판단하면 안 돼요- 어떻게 판단하나요: diagnostics와
cache_read_input_tokens를 함께 봐야 결론을 내릴 수 있어요 - 필수 조건: 명시적으로 마킹하기, 512 토큰 이상 채우기, 프리픽스가 바이트 단위로 동일하기
- 비용 차이: 3만 토큰 프리픽스로 하루 200회 호출하면 하루 청구 금액이 약 17.8배까지 벌어져요
- 중계 서비스 자체 점검: APIYI apiyi.com에서 “이번 턴의 읽기가 직전 턴의 쓰기와 같은지” 확인해 보세요
요약
Claude 캐시 적중률 점검은 결국 세 가지로 정리돼요.
- 분기 지점 찾기: 매 턴
diagnostics를 붙이고cache_miss_reason을 읽어서, 가장 먼저 보고된 지점부터 고치세요 - 교차 판단: diagnostics와 usage를 함께 봐야 해요.
null이라고 해서 캐시가 적용되지 않은 건 아니에요 - 필수 조건 지키기: 마킹을 제대로 하고, 길이를 채우고, 히스토리는 덧붙이기만 하고, system과 tools는 안정적으로 유지하세요
호출 경로에서 diagnostics를 받을 수 없다면, usage의 두 필드로 자체 점검 체계를 만들면 돼요. 먼저 APIYI apiyi.com에서 두 번의 요청으로 캐시 읽기·쓰기 수치를 검증한 뒤 프로덕션 환경에 올리는 걸 권장해요.
📚 참고 자료
- Claude 공식 문서: Cache diagnostics: 진단 필드, 6가지 유형 및 판단 행렬
- 링크:
platform.claude.com -
설명: 본문의 diagnostics 필드, 타임라인, 제한은 모두 이 문서를 기준으로 합니다
-
Claude 공식 문서: Prompt caching: 캐싱 규칙, TTL, 최소 길이 및 가격
- 링크:
platform.claude.com -
설명: 최소 캐시 가능 길이와 공식 가격표의 출처
-
APIYI 모델 목록: Claude 각 모델의 입력, 출력, 캐시 읽기 가격
- 링크:
docs.apiyi.com/models -
설명: 가격 데이터는 2026-10-25 기준으로 업데이트됨
-
APIYI Claude Prompt Caching 캐시 과금 가이드: 배율, 손익분기점 및 자체 점검 판단 기준
- 링크:
docs.apiyi.com/api-capabilities/claude-prompt-caching - 설명: 중계 서비스 환경에서의 문제 진단 근거
작성자: APIYI 기술팀
기술 교류: APIYI 웹사이트 홈페이지에서 문의해 주세요. 더 많은 자료는 docs.apiyi.com 문서 센터에서 확인할 수 있습니다
