Claude가 답했어도 캐시가 쓰였는지는 최소 길이와 사용량으로 확인하기

한 장의 그림으로 이해하기

개념 비유다. 왼쪽 로봇은 얇은 책을 읽지만 옆 캐시 보관함은 비어 있다. 오른쪽 사람은 같은 빈 보관함 옆 장부의 생성0·읽기0을 확인한다. 책은 요청 입력, 독서는 일반 처리, 보관함은 재사용 캐시, 장부는 응답의 캐시 사용량 필드에 대응한다. 두 0은 캐시 생성·읽기가 없다는 문서상 조건을 표현한 개념 예시이며 실제 호출 측정값이 아니다. 응답 생성 토큰이0이라는 뜻도 아니다. 최소 길이보다 짧은 캐시 대상 입력이 정상 처리되는 경우를 설명하지만, 두 값이0인 모든 원인이 길이 부족이라는 뜻은 아니다. 책 두께는 실제 토큰 수가 아니며 그림에 모델별 임계값은 넣지 않았다.
내용의 흐름을 표현한 설명용 그림입니다. 실제 제품 화면이나 실행 결과가 아닙니다.
그림 크게 보기 ↗ (새 탭)

모델·API · 판정 관망

그림을 글로 풀면

응답 성공과 캐시 사용 구분

캐시 표시를 넣어도 대상 입력이 최소 길이보다 짧으면 캐시 없이 처리됩니다.

대상
Claude API 캐시 적용을 확인하는 개발자
무엇이 바뀜
최소 캐시 길이는 사용하는 모델에 따라 다릅니다.
왜 중요한가
오류가 없다는 사실만으로 캐시 사용을 판정할 수 없습니다.
지금 할 일
모델별 최소 길이와 응답의 캐시 생성·읽기 값을 대조합니다.
한계·미확인
개념 예시. API 호출·토큰 수·비용 측정 없음.
공식 출처
platform.claude.com
확인일
2026-10-03

캐시를 켰다는 설정과 실제 사용 나누기

가상의 반복 문서 요약 앱에서 cache_control을 지정한 뒤 정상 응답을 받았다고 생각해 봅니다. 설정이 들어간 요청이라는 사실과 이번 요청이 캐시를 만들거나 읽었다는 사실은 구분해야 합니다. 그림에서 로봇이 책을 읽는데 보관함이 비어 있는 장면은 정상 처리와 캐시 사용이 별개임을 보여주는 자체 비유입니다.

짧은 입력도 오류 없이 처리될 수 있다

Claude 공식 문서는 캐시를 만들 수 있는 최소 입력 길이가 모델에 따라 다르다고 설명합니다. 그보다 짧은 내용은 cache_control을 표시해도 캐시 없이 처리하며 오류를 반환하지 않습니다. 따라서 짧은 시험 요청으로 응답만 확인한 뒤 캐시 적용까지 성공했다고 기록하지 않습니다. 사용하는 모델의 현재 최소 길이를 공식 문서에서 확인하고, 다른 제공 플랫폼의 세부 조건까지 같다고 가정하지 않습니다.

응답의 생성과 읽기 값을 따로 기록하기

Claude API 응답의 usage에서 cache_creation_input_tokens는 캐시에 기록한 입력 토큰, cache_read_input_tokens는 이번 요청이 캐시에서 읽은 입력 토큰을 나타냅니다. 두 값이 모두0이면 해당 요청에서 캐시 생성·읽기가 없었다는 단서이며 최소 길이 부족은 가능한 원인 중 하나입니다. 내용 일치 등 다른 캐시 조건도 별도 확인해야 합니다. AINOW는 모델·요청 조건과 두 값을 함께 남기도록 제안하며, 이번에는 API 호출이나 비용 비교를 실행하지 않았습니다.

참고 원문: Claude 공식 문서 — Prompt caching의 Cache limitations와 usage · 원문 게시일 상시 문서(확인일 기준) · 확인일 2026-10-03

AI 작성·자동 검증: 공식 자료와의 대조 및 게시 구조 검사. 사람의 개별 검수와 제품 실행 시험은 수행하지 않았습니다. 그림은 신규 생성한 개념 일러스트입니다.

이 글의 검증 카드

자료 버전
Claude API prompt caching 상시 문서2026-10-03 확인. 모델별 최소 캐시 길이와 cache_creation_input_tokens·cache_read_input_tokens. 다른 제공 플랫폼에 일반화하지 않음. API·토큰·요금 측정 없음
확인일
2026-10-03
검증 상태
개발자 주장
한계·주의
개념 예시. API 호출·토큰 수·비용 측정 없음.

함께 더 정확하게

질문·오류 제보

그림에서 이해되지 않는 부분이나 달라진 내용을 알려 주세요. 관리자가 확인하고 승인한 글만 공개됩니다.

공개된 질문·제보

    아직 공개된 질문·제보가 없습니다. 궁금한 부분을 먼저 남겨 주세요.