캐시 메커니즘, 가격 등급, TTL 지속 시간, 최소 토큰 임계값은 Anthropic이 플랫폼을 업데이트하면서 바뀝니다. 제3자 가이드의 특정 숫자에 의존하지 마세요. 항상 공식 프롬프트 캐싱 문서와 모델 & 가격 페이지에서 현재 값을 확인하세요.
프롬프트 캐싱 경제학
Claude API를 호출할 때마다 당신은 보내는 모든 입력 토큰에 대해 비용을 치릅니다 — 시스템 프롬프트, 도구 정의, 그리고 주입하는 모든 컨텍스트를 포함해서요. 같은 큰 접두부로 여러 번 호출하고 있다면, 당신은 매번 그 접두부를 처음부터 처리하는 데 비용을 치르고 있는 것입니다.
프롬프트 캐싱이 그것을 바꿉니다. 당신은 프롬프트의 안정적인 부분을 캐싱 가능하다고 표시합니다. 첫 호출이 그것을 처리하고 저장합니다. 캐시에 적중하는 이후의 호출들은 그 처리를 건너뛰고 — 그 토큰에 대해 정상 요율의 일부만 지불합니다.
이 절감은 겉치레가 아닙니다. 크고 안정적인 시스템 프롬프트나 무거운 컨텍스트를 가진 애플리케이션의 경우, 캐싱은 어떤 기능의 경제성을 "출시하기엔 너무 비싸다"에서 "사실상 공짜로 돌아간다"로 바꿀 수 있습니다.
멘탈 모델: 안정적인 접두부, 휘발성 접미부
모든 API 호출을 두 부분으로 생각하세요:
안정적인 접두부 — 호출 전반에 걸쳐 바뀌지 않는 내용. 캐싱이 적용되는 곳입니다. 예시:
- 시스템 프롬프트
- 도구 정의
- 매 호출마다 주입하는 큰 참조 문서나 코드베이스
- 긴 퓨샷 예시 블록
휘발성 접미부 — 호출마다 바뀌는 내용. 캐싱이 적용되지 않는 곳입니다. 예시:
- 현재 사용자 메시지
- 요청마다 주입하는 실시간 데이터
- 매 턴마다 늘어나는 대화 기록
규칙은 간단합니다: 안정적인 내용이 먼저 오고 바뀌는 내용이 마지막에 오도록 프롬프트를 구조화하라. 캐시 분기점은 위치 기반입니다 — 표시된 분기점 이전의 모든 것은 캐싱 대상이고, 이후의 모든 것은 아닙니다.
정적 내용보다 동적 내용을 앞에 두면, 접두부가 매 요청마다 바뀌므로 캐시가 깨집니다.
비용 모델이 작동하는 방식
프롬프트 캐싱은 입력 토큰의 가격을 세 갈래로 나눕니다:
| 토큰 유형 | 언제 발생하는가 | 정상 입력 대비 비용 |
|---|---|---|
| 캐시 쓰기 | 첫 호출, 또는 캐시 만료 후 | 정상 입력보다 높음 |
| 캐시 읽기 | 캐시에 적중하는 이후 호출 | 정상 입력보다 훨씬 낮음 |
| 일반 입력 | 마지막 캐시 분기점 이후의 토큰 | 정상 요율 |
정확한 배율은 공식 가격 페이지에 있으며 변동합니다 — 직접 확인하세요. 바뀌지 않는 것은 구조입니다: 쓰기는 정상보다 비싸고, 읽기는 훨씬 쌉니다. 손익 분기점 — 쓰기 오버헤드를 회수할 만큼 캐싱된 호출을 충분히 했을 때 — 은 상당한 안정적 내용을 가진 어떤 프롬프트에서든 빠르게 옵니다.
지연 시간도 같은 패턴을 따릅니다. 캐시 읽기는 캐싱된 부분의 전체 처리를 건너뛰며, 이는 큰 접두부를 가진 호출에서 첫 토큰까지의 시간을 의미 있게 줄입니다.
프롬프트 캐싱이 도움이 되는 경우
캐싱은 두 조건이 모두 참일 때 값을 합니다:
- 상당한 안정적 접두부가 있다(그 아래로는 캐싱을 쓸 수 없는 최소 토큰 임계값이 있습니다 — 모델별 정확한 숫자는 현재 문서를 확인하세요).
- 그 접두부가 가끔보다는 자주 캐시에 적중할 만큼 충분히 재사용된다.
캐싱이 자연스럽게 들어맞는 시나리오:
- 문서 Q&A — 같은 큰 문서가 여러 사용자 질문에 대해 주입된다.
- 코딩 어시스턴트 — 큰 코드베이스나 파일 트리가 매 요청에 포함된다.
- 에이전트 루프 — 같은 시스템 프롬프트와 도구 정의가 다단계 워크플로의 매 단계마다 보내진다.
- 긴 지시를 가진 대화형 에이전트 — 호출마다 절대 바뀌지 않는 상세한 페르소나, 규칙 집합, 지식 베이스.
- 배치 처리 — 같은 템플릿에 대해 많은 입력이 실행된다.
프롬프트 캐싱이 도움이 되지 않는 경우
캐싱은 다음과 같을 때 유용하지 않습니다:
- 프롬프트가 짧다(최소 캐싱 가능 토큰 임계값 미만).
- 접두부가 매 호출마다 바뀐다 — 타임스탬프, 사용자별 컨텍스트, 또는 어떤 개인화를 "안정적인" 부분에 주입하면 캐시가 무효화됩니다.
- 사이에 긴 간격을 두고 드물게 호출한다. 캐싱된 내용은 TTL(API가 지원하는 한계 안에서 설정할 수 있는 지속 시간) 이후 만료됩니다. 트래픽이 드문드문하다면, 당신은 읽기는 거의 없이 대부분 쓰기 비용만 치르게 됩니다.
- 접두부가 호출당 동적 내용에 비해 작다. 절감은 캐싱되는 것의 크기에 비례해 커집니다.
캐시 친화적으로 프롬프트 구조화하기
유일한 구조적 요구 사항은 순서입니다: 안정적인 내용이 휘발성 내용보다 먼저 와야 한다.
실전에서는:
[System prompt — instructions, persona, rules]
[Tool definitions — if static]
[Large injected documents or context — if the same across calls]
--------- cache breakpoint here ---------
[Dynamic per-call content — user message, retrieved chunks specific to this request]
캐시에 포함하려는 마지막 블록에 cache_control 필드를 두어 분기점을 표시합니다. 그 표시 이전의 모든 것은 캐싱 대상이고, 이후의 모든 것은 일반 입력입니다.
단일 요청에 최대 네 개의 명시적 분기점을 둘 수 있습니다. 이는 프롬프트의 여러 부분이 서로 다른 빈도로 바뀔 때 유용합니다 — 예를 들어 도구 정의는 거의 바뀌지 않지만 대화 기록은 매 턴마다 바뀝니다. 각 구역이 자체 분기점을 가질 수 있습니다.
캐시 무효화 규칙
캐시는 순서에 민감합니다. 캐싱된 블록이나, 프롬프트에서 그보다 앞에 오는 어떤 블록이든 변경되면, 그 분기점과 이후의 모든 분기점에서 캐시가 무효화됩니다.
도구 정의의 변경은 모든 캐시를 무효화합니다. 시스템 프롬프트의 변경은 시스템과 메시지 캐시를 무효화합니다. 대화 중간의 변경은 메시지 캐시에만 영향을 줍니다.
실질적 함의: 요청마다 바뀌는 무언가를 주입하고 있다면, 그것이 마지막 캐시 분기점 이후에 있도록 반드시 확실히 하세요. 그 이전이나 내부가 아니라.
사전 예열과 모니터링
사용자 트래픽이 도착하기 전에 max_tokens: 0으로 요청을 보내 캐시를 미리 예열할 수 있습니다 — 이는 출력을 생성하지 않고 캐시를 씁니다. 배치 작업이나, 비수기 시간에 쓰기 비용을 앞당겨 치르는 데 유용합니다.
API 응답의 usage 필드는 캐시에서 읽힌 토큰 수(cache_read_input_tokens), 캐시에 쓰인 토큰 수(cache_creation_input_tokens), 일반 입력으로 청구된 토큰 수를 알려줍니다. 이것들을 모니터링해 캐싱이 실제로 적중하는지 확인하고 실현 중인 절감을 측정하세요.
캐싱 아키텍처에 전념하기 전에 비용 계산기로 예상 절감을 모델링하세요.
결론
프롬프트 캐싱은 미세 최적화가 아닙니다. 같은 큰 접두부를 반복해서 보내는 어떤 애플리케이션에서든, 그것은 구조적인 경제적 결정입니다. 그것을 생각하는 모델은 단순합니다: 안정적인 내용이 먼저, 휘발성 내용이 마지막, 분기점은 경계에 둡니다.
API에 맞춰 무언가를 만들고 있는데 아직 캐싱을 살펴보지 않았다면, 현재 프롬프트에서 크고 안정적인 구역을 확인하세요. 그것들이 존재한다면, 캐싱을 켜는 것은 보통 노력이 적게 들고 절감은 진짜입니다.