Claude 프롬프트 캐싱을 프로덕션 API에 연결하기 전 최소 토큰과 수명을 확인해보세요

프롬프트 캐싱이 동작하는 최소 토큰 기준은 얼마인가요?

프롬프트 캐싱 문서에 따르면 모든 요청에 캐시가 만들어지는 건 아니에요. 모델 계열에 따라 캐시 가능한 최소 토큰 경계가 정해져 있어요.

Claude 3.5 Sonnet과 Claude 3 Opus는 프롬프트 시작 지점부터 캐시 브레이크포인트까지의 누적 토큰이 1,024 토큰 이상이어야 캐시가 동작해요. Claude 3.5 Haiku는 최소 기준이 2,048 토큰이에요. 이 기준보다 짧은 프롬프트에 캐시 설정을 넣으면 오류가 나지는 않지만, 캐시가 생성되지 않고 매번 일반 입력 요금이 그대로 청구돼요.

단순한 한두 문장의 시스템 프롬프트나 몇 줄짜리 질문에는 캐시를 붙여도 이점이 없어요. 수십 페이지 분량의 기술 명세서, 대규모 함수 도구(Tools) 정의 목록, 여러 턴이 누적된 대화 기록처럼 1,024 토큰을 안정적으로 넘는 컨텍스트가 있을 때 캐시 설정을 고려하세요.

캐시 쓰기와 읽기 요금은 어떻게 계산하나요?

모델 가격 정책 문서에서 안내하는 프롬프트 캐싱 비용 구조는 기본 입력 토큰 단가를 기준으로 계산돼요. 캐시가 생성될 때의 쓰기(Write) 비용과 캐시가 적중했을 때의 읽기(Read) 비용이 다르게 책정돼 있어요.

출처는 Anthropic 공식 가격 정책 문서이고 확인일은 2026-10-25예요.

기본 입력 토큰 대비 쓰기 비용이 25% 더 들기 때문에, 캐시 생성 후 5분 안에 적어도 2회 이상 읽기 요청이 발생해야 전체 비용에서 실질적인 절감 효과가 나타나요. 1회만 호출되고 5분이 지나 캐시가 사라지면 오히려 일반 호출보다 25% 비싼 요금을 내게 돼요.

요청 본문에서 캐시 브레이크포인트는 어떻게 지정하나요?

프롬프트 캐싱을 활성화하려면 요청 본문의 특정 블록에 cache_control 속성을 넣어야 해요. 현재 지원하는 타입은 {"type": "ephemeral"}이에요.

Python SDK 저장소의 예시를 보면 system 매개변수를 텍스트 문자열 대신 블록 목록으로 넘기면서 해당 블록 끝에 캐시 제어를 둘 수 있어요. 대규모 도구 정의가 있다면 tools 목록의 마지막 도구 항목에 캐시 제어를 지정해도 돼요. 한 요청 안에서 최대 4개의 캐시 브레이크포인트를 지정할 수 있어요.

주의할 점은 캐시가 프롬프트의 맨 앞부터 바이트 단위로 정확히 일치할 때만 적중한다는 사실이에요. 시스템 프롬프트 맨 앞에 현재 시각이나 매 요청 달라지는 난수(UUID)를 넣으면 캐시 키가 매번 바뀌어 이전 캐시를 전혀 쓰지 못해요. 고정된 배경 지식과 지침을 맨 앞에 두고, 자주 바뀌는 사용자 입력과 동적 값은 프롬프트 뒤쪽에 배치하세요.

프로덕션 환경에서 어떤 호출 패턴이 오히려 손해를 보나요?

서비스의 호출 패턴에 따라 캐싱 도입이 오히려 인프라 비용을 늘릴 수 있어요. 실제 코드를 수정하기 전에 우리 서비스의 트래픽 흐름을 점검해 보세요.

1. 요청 간격이 5분을 초과하는 간헐적 배치 작업: 10분에 한 번씩 돌아가는 스케줄러라면 매 실행마다 캐시가 만료돼 매번 125% 쓰기 요금만 청구돼요.
2. 사용자별로 시스템 프롬프트 내용이 달라지는 구조: 사용자 ID나 개인화 변수가 프롬프트 앞부분에 들어가면 공용 캐시가 만들어지지 않고 사용자마다 별도 캐시가 생겨 적중률이 떨어져요.
3. 1,024 토큰에 아슬아슬하게 걸치는 프롬프트: 입력 텍스트 길이에 따라 어떤 요청은 1,020 토큰이 되어 캐시 생성을 건너뛰고, 다음 요청은 1,030 토큰이 되어 쓰기 요금이 나가는 불규칙한 처리가 생겨요.
4. 모델 버전을 동적으로 바꾸는 라우팅: 캐시는 모델 ID별로 독립적으로 관리돼요. 같은 프롬프트라도 Sonnet과 Haiku 사이를 오가며 호출하면 캐시가 공유되지 않아요.

이 점검 항목은 서비스 아키텍처 결정을 돕기 위한 기술적 제안이에요. 트래픽 집중 시간대와 사용자 재방문 주기를 분석해 5분 이내 연속 호출이 발생하는 경로에만 선별적으로 적용하세요.

적용 전에 로그와 SDK에서 무엇부터 점검하나요?

코드에 캐시 설정을 넣은 뒤에는 API 응답의 usage 필드를 반드시 로그로 남겨 확인해야 해요. Anthropic API 응답에는 캐시 동작 상태를 보여 주는 세 가지 토큰 필드가 포함돼요.

첫째는 cache_creation_input_tokens예요. 이 숫자가 0보다 크다면 해당 요청에서 캐시가 새로 만들어졌음을 의미해요. 둘째는 cache_read_input_tokens예요. 이 숫자가 올라가야 실제로 90% 할인된 읽기 요금이 적용되고 있는 거예요. 셋째는 일반 input_tokens예요. 캐시되지 않은 나머지 뒷부분 입력 토큰 수가 여기에 기록돼요.

배포 초기에는 전체 입력 토큰 중 cache_read_input_tokens가 차지하는 비율(캐시 적중률)을 메트릭으로 수집하세요. 쓰기 토큰만 발생하고 읽기 토큰이 올라가지 않는 엔드포인트가 있다면 해당 위치의 cache_control 설정을 즉시 회수해야 해요. 공식 자료 확인일은 2026-10-25예요.