Claude Sonnet 4.6 / Opus 4.6 기준
공식 Anthropic Docs 검증
Claude API 프롬프트 캐싱, 직접 재봤더니 비용 90% 차이
Claude API를 쓰다 보면 같은 시스템 프롬프트를 수천 번 반복 전송하게 됩니다. 캐싱을 켜지 않은 채 RAG 봇을 한 달 돌리면 얼마가 나올까요? 직접 계산해봤더니 결과가 꽤 놀라웠습니다.
캐싱이 실제로 어떻게 작동하는가
Claude API 프롬프트 캐싱은 반복되는 프롬프트 앞부분을 서버에 저장해두고, 다음 요청 때 다시 계산하지 않고 그대로 꺼내 쓰는 구조입니다. 공식 문서에는 이 동작을 “prefix caching”이라 부르며, 요청마다 동일한 토큰을 처음부터 재처리하지 않는다고 명시돼 있습니다.
(출처: Anthropic 공식 문서, docs.anthropic.com/prompt-caching)
캐시 활성화 방법은 두 가지입니다. 멀티턴 대화에서는 요청 최상단에 cache_control 필드 하나만 추가하는 자동 캐싱(Automatic Caching)이 편하고, 시스템 프롬프트·툴 정의·문서 블록처럼 갱신 주기가 다른 콘텐츠를 따로 캐시하고 싶을 때는 블록마다 직접 마커를 찍는 명시적 캐시 브레이크포인트(Explicit Cache Breakpoints)를 씁니다. 두 방식은 동시에 사용할 수 있고, 한 요청에 최대 4개의 브레이크포인트를 찍을 수 있습니다.
캐시가 적중하면 응답 오브젝트의 usage.cache_read_input_tokens 값이 0보다 커집니다. 이 필드가 계속 0이라면 캐시가 전혀 작동하지 않고 있다는 신호입니다.
5분 TTL, 생각보다 오래 살아있는 이유
💡 공식 발표문과 실제 사용 흐름을 같이 놓고 보니 이런 차이가 보였습니다 — “5분 TTL”이라고 해서 캐시가 5분 후 무조건 만료된다고 생각하면, 실제 운영 시 동작이 완전히 다르게 느껴질 수 있습니다.
공식 문서에는 이렇게 나옵니다: “The cache is refreshed for no additional cost each time the cached content is used.” 즉, 캐시 히트가 발생할 때마다 TTL이 무료로 5분 리셋됩니다. 실제 흐름을 직접 따라가면 아래와 같습니다.
| 요청 시각 | 이벤트 | 캐시 상태 |
|---|---|---|
| t = 0분 | 첫 요청 — 캐시 Write | 만료까지 5분 |
| t = 2분 | 캐시 Hit → TTL 리셋 | 만료까지 5분 (재시작) |
| t = 6분 | 캐시 Hit → TTL 리셋 | 만료까지 5분 (재시작) |
| t = 11분 (5분 공백) | 요청 없음 | 캐시 만료 |
트래픽이 꾸준한 서비스라면 캐시가 사실상 무기한 유지됩니다. 반대로 요청 간격이 5분을 넘는 비동기 파이프라인이나 야간 배치 작업에서는 매번 캐시 Write 비용이 새로 발생합니다. 이런 워크로드에는 1시간 TTL 옵션이 있습니다.
1시간 TTL은 cache_control에 {"type":"ephemeral","ttl":3600}을 추가하면 활성화됩니다. Write 비용이 기본 입력 토큰 가격의 2배(기본 5분 TTL은 1.25배)로 올라가지만, 히트 비용은 동일하게 0.1배입니다. 요청 간격이 5~60분 사이인 에이전트 워크플로우나 사용자 채팅 세션에 적합합니다.
(출처: Anthropic 공식 문서, docs.anthropic.com/prompt-caching)
모델별 최소 토큰 기준 — 이 수치 아래면 캐시 자체가 안 됩니다
💡 캐시가 작동하지 않아도 API는 오류를 반환하지 않습니다. 요청이 성공적으로 처리되지만, cache_read/write 수치가 조용히 0으로 나오는 게 전부입니다.
캐싱을 활성화했더라도 콘텐츠 길이가 모델별 최소 토큰 수를 넘지 못하면 캐시는 생성되지 않습니다. Anthropic 공식 문서에 명시된 기준은 아래와 같습니다.
(출처: Anthropic Docs — Cache limitations)
| 모델 | 최소 토큰 | 약 글자 수(한국어) |
|---|---|---|
| Claude Opus 4.6 / 4.5 | 4,096 | 약 3,000자 이상 |
| Claude Sonnet 4.6 | 2,048 | 약 1,500자 이상 |
| Claude Sonnet 4.5 / 4 / 3.7, Opus 4.1 / 4 | 1,024 | 약 750자 이상 |
| Claude Haiku 4.5 | 4,096 | 약 3,000자 이상 |
| Claude Haiku 3.5 / 3 | 2,048 | 약 1,500자 이상 |
Haiku 4.5가 Sonnet 4.5보다 최소 기준이 4배나 높다는 점이 의외입니다. 가장 저렴한 모델이지만 캐싱 진입장벽은 오히려 더 높습니다. 시스템 프롬프트가 짧은 프로토타입 수준이라면 Haiku 4.5 캐싱은 사실상 작동하지 않을 수 있습니다.
비용 직접 계산 — 월 $4,045 차이가 나는 구조
RAG 기반 고객지원 봇을 예시로 잡겠습니다. 제품 매뉴얼 50,000토큰을 시스템 프롬프트로 넣고, 하루 1,000건 쿼리, 모델은 Claude Sonnet 4.5(입력 $3/MTok) 기준입니다. 공식 가격 테이블을 그대로 대입해 계산했습니다.
(출처: Anthropic 공식 가격 테이블)
캐싱 미적용 시
요청당 비용 = (50,000 + 500) tokens × $3 / 1,000,000 = $0.1515
일일 비용 = 1,000 × $0.1515 = $151.50
월 비용 = 30 × $151.50 = $4,545
캐싱 적용 시
첫 번째 요청(캐시 Write) = 50,000 × $3.75/MTok + 500 × $3/MTok = $0.1875 + $0.0015 = $0.189
이후 999건(캐시 Read) = 50,000 × $0.30/MTok + 500 × $3/MTok = $0.015 + $0.0015 = $0.0165 × 999 = $16.48
일일 비용 합계 = $0.189 + $16.48 = $16.67
월 비용 = 30 × $16.67 = $500
월 절감액: $4,045 (절감율 89%)
손익분기는 단 2번째 요청에서 이미 넘어섭니다. 계산식으로 표현하면: 90N = 115, N ≈ 1.28 — 즉 2회 이상 동일 prefix를 재사용하면 캐싱이 무조건 이득입니다.
여기서 한 가지 더 — 캐시 히트 토큰은 API 속도 제한(Rate Limit) 카운트에서도 제외됩니다. 대용량 컨텍스트를 반복 전송하면서 토큰 한도에 걸리던 워크로드라면, 비용 절감과 동시에 처리량도 늘어납니다.
(출처: Anthropic 공식 문서 — “cache hits are not deducted against your rate limit”)
캐시가 조용히 죽는 7가지 상황
캐싱 세팅을 완료했는데도 히트율이 0에 가까울 때, 대부분 아래 원인 중 하나입니다. 특히 1번과 4번은 오류 메시지조차 없어서 뒤늦게 발견하는 경우가 많습니다.
최소 토큰 미달 — 요청 성공이라도 캐시는 없음
cache_creation_input_tokens와 cache_read_input_tokens가 둘 다 0이면 이 케이스입니다. 에러 없이 그냥 정가를 냅니다.
Tool 정의 수정 — 전체 캐시 무효화
툴 이름·파라미터를 단 하나라도 바꾸면 tools → system → messages 전체가 초기화됩니다. 툴 정의는 배포 시점 이외에 건드리지 않도록 관리하는 게 좋습니다.
이미지 추가·제거 — system + messages 캐시 삭제
프롬프트 어디에든 이미지가 추가되거나 빠지면 시스템·메시지 캐시가 날아갑니다. 이미지 존재 여부를 일관되게 유지해야 합니다.
변하는 블록에 브레이크포인트를 찍은 경우
타임스탬프나 유저 메시지처럼 매 요청마다 바뀌는 블록 끝에 cache_control을 붙이면, 매번 캐시 Write만 발생하고 Read는 0입니다. 브레이크포인트는 마지막으로 변하지 않는 블록 끝에 찍어야 합니다.
병렬 첫 요청 — 캐시 공유 불가
첫 번째 응답이 시작되기 전까지 캐시 엔트리가 생성되지 않습니다. 동시에 복수 요청을 보내면 각자 별도 캐시를 만들어 비용을 이중으로 냅니다. 첫 응답 시작 후 후속 요청을 보내야 합니다.
20블록 룩백 초과 — 오래된 캐시를 못 찾음
시스템이 브레이크포인트에서 뒤로 20블록까지만 기존 캐시를 탐색합니다. 대화가 길어져 21블록 이상 앞에 있는 캐시 엔트리는 무시됩니다. 대화가 길어지면 명시적 브레이크포인트를 20블록 간격으로 추가해야 합니다.
Swift/Go JSON 키 순서 무작위화
일부 언어(Swift, Go)는 JSON 직렬화 시 키 순서를 랜덤하게 바꿉니다. 프롬프트 내용이 같아도 해시값이 달라져 캐시 미스가 반복됩니다. tool_use 블록의 키 순서를 명시적으로 고정해야 합니다.
2026년 2월 이후 달라진 워크스페이스 격리 정책
💡 이 변경 사항은 다른 블로그 글에서 거의 다루지 않습니다. 하지만 조직 내 여러 워크스페이스를 운영 중이라면, 2025년까지와는 캐시 공유 범위가 완전히 달라졌습니다.
2026년 2월 5일부터 Claude API의 캐시 격리 단위가 조직(Organization) 레벨에서 워크스페이스(Workspace) 레벨로 변경됐습니다. 같은 조직 내 다른 워크스페이스 간에는 더 이상 캐시가 공유되지 않습니다.
(출처: Anthropic 공식 문서 — Cache storage and sharing)
예를 들어 개발(dev)·스테이징(staging)·프로덕션(prod) 워크스페이스를 분리 운영하는 경우, 세 환경 모두에서 초기 캐시 Write 비용이 각각 발생합니다. 이전에는 동일 조직이라면 같은 캐시를 공유할 수 있었지만, 지금은 워크스페이스 경계를 넘으면 별개의 캐시입니다.
단, 이 변경 사항은 Claude API와 Azure AI Foundry에만 적용되며, Amazon Bedrock와 Google Vertex AI는 기존 조직 수준 격리를 유지합니다. 플랫폼별로 캐시 공유 범위가 다르다는 점, 멀티클라우드 전략을 쓰는 팀이라면 반드시 체크해야 합니다.
또한 공식 문서는 ZDR(Zero Data Retention) 계약이 체결된 경우 캐시 데이터(KV 표현값·해시값)는 메모리에만 보관되며 응답 반환 이후 별도 저장하지 않는다고 명시합니다. 의료·금융 규정 환경에서도 ZDR 계약 조건 하에 프롬프트 캐싱을 활용할 수 있다는 점은 알려진 것보다 명확한 공식 입장입니다.
실전 적용 — 어떤 순서로 세팅해야 하는가
단계별로 따라가면 됩니다. 처음부터 복잡한 다중 브레이크포인트 전략을 짤 필요는 없습니다.
STEP 1. 멀티턴 대화라면 자동 캐싱부터 시작
요청 최상단에 cache_control: {"type":"ephemeral"}만 추가합니다. 브레이크포인트 위치 관리를 시스템이 자동으로 처리합니다.
STEP 2. 시스템 프롬프트가 크다면 명시적 브레이크포인트 추가
시스템 프롬프트의 마지막 정적 블록에 cache_control을 찍습니다. 툴 정의가 있다면 툴 배열 마지막 항목에도 추가해 tools 레벨 캐시를 분리합니다.
STEP 3. 응답 필드에서 캐시 히트율 확인
매 응답의 usage.cache_read_input_tokens를 로깅합니다. 이 수치가 0이면 캐싱이 작동하지 않는 것입니다.
STEP 4. 요청 간격이 5분 이상이면 1시간 TTL 전환 검토
배치 작업이나 사용자 응답 대기 시간이 긴 에이전트는 cache_control에 ttl: 3600을 추가합니다. Write 비용은 2배지만, 히트가 발생하면 Read 비용은 동일하게 0.1배입니다.
STEP 5. 대화가 20블록 이상 길어지면 중간 브레이크포인트 추가
롤백 윈도우가 20블록으로 제한되므로, 긴 대화 기록을 캐싱하려면 20블록 간격으로 명시적 브레이크포인트를 추가합니다. 최대 4개까지 사용할 수 있습니다.
📌 Thinking 블록(Extended Thinking) 사용자라면 주의: Thinking 블록에는 직접 cache_control을 붙일 수 없습니다. 다만 Tool 결과를 전달하는 후속 요청에서는 자동으로 캐싱됩니다. non-tool-result 유저 메시지가 추가되면 이전 Thinking 블록 전체가 컨텍스트에서 제거되므로, 캐시도 함께 무효화됩니다.
자주 나오는 질문 5가지
Q1. 캐싱을 쓰면 응답 품질이나 내용이 달라지나요?
전혀 달라지지 않습니다. 캐싱은 내부 연산을 재사용하는 것뿐이고, 생성된 응답 내용은 캐싱 여부와 무관합니다. Anthropic 공식 문서에 “Output Token Generation has no effect from caching”이라고 명확히 나와 있습니다.
Q2. 스트리밍(Streaming) 응답에서도 캐싱이 작동하나요?
작동합니다. 스트리밍 모드에서는 cache 관련 수치가 응답 완료 후가 아닌 message_start 이벤트에 포함됩니다. 로직 처리 시 이 차이를 반영해야 합니다.
Q3. 다른 사용자의 캐시와 섞일 수 있나요?
조직(Organization)이 다르면 절대로 공유되지 않습니다. 2026년 2월 5일 이후에는 같은 조직 내에서도 워크스페이스가 다르면 캐시가 분리됩니다. 단, 같은 워크스페이스 내에서는 동일 prefix를 쓰는 API 키끼리 캐시를 공유합니다.
Q4. 이미지(비전)를 쓰는 요청에서도 캐싱이 되나요?
이미지 블록 자체도 캐싱 대상에 포함됩니다. 단, 요청 어디에서든 이미지가 추가되거나 빠지면 그 시점부터 system·messages 캐시가 무효화됩니다. 이미지 구성을 일관되게 유지하는 게 핵심입니다.
Q5. AWS Bedrock나 Google Vertex AI에서도 같은 방식으로 쓰나요?
개념은 동일하지만 구문이 일부 다릅니다. AWS Bedrock는 cache_control 대신 cachePoint를 씁니다. 1시간 TTL 옵션은 아직 공식 API에서만 완전히 지원되며, Bedrock·Vertex에는 제한적으로 제공됩니다. 자동 캐싱(Automatic Caching) 기능은 현재 Claude API와 Azure AI Foundry(preview)에서만 사용할 수 있습니다.
마치며
프롬프트 캐싱은 Claude API를 실 서비스에 붙이는 순간부터 바로 적용해야 하는 기능입니다. 2회 이상 동일 prefix가 반복되는 구조라면 무조건 이득이고, 캐시 히트 토큰은 Rate Limit 카운트에서도 빠지기 때문에 처리량도 함께 늘어납니다.
막상 써보면 가장 흔한 함정이 두 개입니다. 첫째는 변하는 블록 끝에 브레이크포인트를 찍어두고 “왜 캐시 히트가 없지?”를 며칠 동안 찾는 경우, 둘째는 시스템 프롬프트 길이가 최소 토큰 기준에 미달하는데 에러가 없으니 그냥 지나치는 경우입니다. 응답마다 cache_read_input_tokens를 로깅하는 습관 하나만 있어도 두 문제 모두 즉시 잡힙니다.
2026년 2월부터 워크스페이스 격리가 적용된 점, Haiku 4.5의 최소 토큰이 4,096으로 Sonnet보다 훨씬 높다는 점은 다른 곳에서 거의 다루지 않는 부분이라 별도로 체크해두면 좋습니다.
본 포스팅 참고 자료
본 포스팅은 2026년 4월 13일 기준 Anthropic 공식 문서 및 공개 자료를 바탕으로 작성됐습니다. Claude API의 서비스 정책·가격·UI·기능은 Anthropic의 업데이트에 따라 언제든 변경될 수 있습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있으므로, 최신 정보는 반드시 공식 문서(docs.anthropic.com)에서 확인하시기 바랍니다.
댓글 남기기