고급

캐시 메커니즘, 가격 계층, TTL 지속 시간, 최소 토큰 임계값은 Anthropic이 플랫폼을 업데이트함에 따라 변경됩니다. 서드파티 가이드의 특정 숫자에 의존하지 마세요. 항상 공식 프롬프트 캐싱 문서와 모델 및 가격 페이지에서 현재 값을 확인하세요.

프롬프트 캐싱 경제학

What you'll learn

순진한 API 호출이 왜 과다 지불하는지: 동일한 안정된 프리픽스가 매번 처음부터 처리됨
정신 모델 — 안정된 프리픽스, 휘발성 서픽스 — 그리고 캐싱을 가능하게 하는 하나의 순서 규칙
세 가지 방식의 입력 가격 분할 (캐시 쓰기, 캐시 읽기, 일반 입력)과 크로스오버가 언제 회수되는지
캐싱이 언제 밥값을 하고, 조용히 하지 않는 네 가지 시나리오
히트율이 90%인지 0%인지 결정하는 다섯 가지 캐시 무효화 규칙
캐시를 사전 워밍하는 방법과 절약이 실제임을 증명하기 위해 usage 필드를 읽는 방법

Claude API를 호출할 때마다, 보낸 모든 입력 토큰에 대해 지불합니다 — 시스템 프롬프트, 도구 정의, 주입하는 모든 컨텍스트 포함. 동일한 큰 프리픽스로 많은 호출을 하고 있다면, 매번 처음부터 그 프리픽스를 처리하는 데 지불하고 있는 것입니다.

프롬프트 캐싱이 이를 바꿉니다. 프롬프트의 안정된 부분을 캐시 가능한 것으로 표시합니다. 첫 번째 호출이 이를 처리하고 저장합니다. 캐시에 히트하는 후속 호출은 그 처리를 건너뛰고 — 해당 토큰에 대해 정상 요율의 일부를 지불합니다.

절약은 표면적이지 않습니다. 크고 안정된 시스템 프롬프트 또는 무거운 컨텍스트를 가진 애플리케이션의 경우, 캐싱은 기능의 경제성을 "출시하기에 너무 비싼"에서 "실행 비용이 기본적으로 무료"로 바꿀 수 있습니다.

정신 모델: 안정된 프리픽스, 휘발성 서픽스

모든 API 호출을 두 부분으로 생각하세요:

안정된 프리픽스 — 호출 전반에서 변경되지 않는 콘텐츠. 캐싱이 적용되는 곳. 예:

시스템 프롬프트
도구 정의
매 호출마다 주입하는 큰 참조 문서 또는 코드베이스
긴 few-shot 예시 블록

휘발성 서픽스 — 호출마다 변경되는 콘텐츠. 캐싱이 적용되지 않는 곳. 예:

현재 사용자 메시지
요청마다 주입하는 실시간 데이터
각 턴마다 증가하는 대화 기록

규칙은 간단합니다: 안정된 콘텐츠가 먼저 오고, 변경되는 콘텐츠가 마지막에 오도록 프롬프트를 구성하세요. 캐시 브레이크포인트는 위치 기반입니다 — 표시된 브레이크포인트 이전의 모든 것이 캐싱 대상이며, 이후의 모든 것은 아닙니다.

정적 콘텐츠 앞에 동적 콘텐츠를 두면, 매 요청마다 프리픽스가 변경되므로 캐시가 깨집니다.

비용 모델 작동 방식

프롬프트 캐싱은 입력 토큰 가격 책정에 세 가지 방식의 분할을 도입합니다:

토큰 유형	발생 시점	정상 입력 대비 비용
캐시 쓰기	첫 호출, 또는 캐시 만료 후	정상 입력보다 높음
캐시 읽기	캐시에 히트하는 후속 호출	정상 입력보다 훨씬 낮음
정상 입력	마지막 캐시 브레이크포인트 이후 토큰	정상 요율

정확한 배수는 공식 가격 페이지에 있으며 변동됩니다 — 직접 확인하세요. 변하지 않는 것은 구조입니다: 쓰기는 정상보다 비용이 더 들고, 읽기는 훨씬 적게 듭니다. 크로스오버 지점 — 쓰기 오버헤드를 회수하기에 충분한 캐시된 호출을 만든 지점 — 은 상당한 안정된 콘텐츠를 가진 어떤 프롬프트에서든 빠르게 옵니다.

지연 시간도 같은 패턴을 따릅니다. 캐시 읽기는 캐시된 부분의 전체 처리를 건너뛰며, 이는 큰 프리픽스를 가진 호출에서 첫 토큰까지의 시간을 의미 있게 줄입니다.

프롬프트 캐싱이 도움이 될 때

캐싱은 두 조건이 모두 참일 때 성과가 있습니다:

상당한 안정된 프리픽스가 있습니다 (캐싱이 사용 불가능한 최소 토큰 임계값이 있습니다 — 모델별 정확한 숫자는 현재 문서를 확인하세요).
해당 프리픽스가 캐시에 가끔 이상으로 히트할 만큼 자주 재사용됩니다.

캐싱이 자연스럽게 어울리는 시나리오:

문서 Q&A — 동일한 큰 문서가 많은 사용자 질문에 주입됨.
코딩 어시스턴트 — 매 요청에 큰 코드베이스 또는 파일 트리가 포함됨.
에이전트 루프 — 다단계 워크플로의 매 단계에 동일한 시스템 프롬프트와 도구 정의가 보내짐.
긴 지시가 있는 대화형 에이전트 — 호출 간에 절대 변하지 않는 상세한 페르소나, 규칙 세트, 지식 베이스.
배치 처리 — 동일한 템플릿에 대해 많은 입력이 실행됨.

프롬프트 캐싱이 도움이 되지 않을 때

캐싱은 다음의 경우 유용하지 않습니다:

프롬프트가 짧습니다 (최소 캐시 가능 토큰 임계값 미만).
프리픽스가 매 호출마다 변경됩니다 — 타임스탬프, 사용자별 컨텍스트, 또는 어떤 개인화든 "안정된" 부분에 주입하면 캐시가 무효화됩니다.
호출을 드물게 하고 그 사이에 긴 간격이 있습니다. 캐시된 콘텐츠는 TTL (API가 지원하는 한도 내에서 구성 가능한 지속 시간) 후에 만료됩니다. 트래픽이 희소하면, 대부분 읽기가 거의 없이 쓰기 비용을 지불하게 됩니다.
호출당 동적 콘텐츠에 비해 프리픽스가 작습니다. 절약은 캐시된 것의 크기에 따라 확장됩니다.

캐시 친화적인 프롬프트 구성하기

유일한 구조적 요구 사항은 순서입니다: 안정된 콘텐츠가 휘발성 콘텐츠보다 먼저 와야 합니다.

Guided walkthrough1 of 5

지시, 페르소나, 규칙 — 사용자 요청당 절대 변하지 않는 부분.

Cache-friendly prompt shape

[System prompt — instructions, persona, rules]
[Tool definitions — if static]
[Large injected documents or context — same across calls]
--------- cache breakpoint here ---------
[Dynamic per-call content — user message, retrieved chunks]

캐시에 포함하려는 마지막 블록에 cache_control 필드로 브레이크포인트를 표시합니다. 그 마커 이전의 모든 것이 캐싱 대상이며, 이후의 모든 것은 정상 입력입니다.

단일 요청에 최대 네 개의 명시적 브레이크포인트를 배치할 수 있습니다. 이는 프롬프트의 다른 부분이 다른 빈도로 변경될 때 유용합니다 — 예를 들어, 도구 정의는 드물게 변경되고, 대화 기록은 매 턴 변경됩니다. 각 섹션에 자체 브레이크포인트가 있을 수 있습니다.

캐시 무효화 규칙

캐시는 순서에 민감합니다. 캐시된 블록에 대한 어떤 변경, 또는 프롬프트에서 그 앞에 오는 블록에 대한 어떤 변경도 그 브레이크포인트와 이후 모든 브레이크포인트에서 캐시를 무효화합니다.

Watch out

도구 정의 변경은 모든 캐시를 무효화합니다 — 도구 목록을 최대한 안정적으로 취급하세요.
시스템 프롬프트 변경은 시스템과 메시지 캐시를 무효화합니다.
대화 중간 변경은 메시지 캐시에만 영향을 미칩니다.
'안정된' 섹션에 타임스탬프, 사용자 ID, 또는 요청별 개인화를 주입하면 조용히 히트율을 죽입니다 — 그 콘텐츠는 마지막 브레이크포인트 이후에 속합니다.
공백, 구두점, 순서가 바이트 단위로 중요합니다 — '작은' 편집도 여전히 무효화합니다.

실제적 함의: 요청마다 변경되는 것을 주입하고 있다면, 그것이 마지막 캐시 브레이크포인트 이후에 존재하고, 그 앞이나 그 안에 있지 않도록 절대적으로 확실히 하세요.

사전 워밍과 모니터링

max_tokens: 0으로 요청을 보내면 사용자 트래픽이 도착하기 전에 캐시를 사전 워밍할 수 있습니다 — 이것은 출력을 생성하지 않고 캐시를 씁니다. 배치 작업이나 비수기 시간에 쓰기 비용을 미리 부담하는 데 유용합니다.

API 응답의 usage 필드는 캐시에서 읽은 토큰 수 (cache_read_input_tokens), 캐시에 쓴 토큰 수 (cache_creation_input_tokens), 정상 입력으로 청구된 토큰 수를 알려줍니다. 이를 모니터링하여 캐싱이 실제로 히트하는지 확인하고 실현하는 절약을 측정하세요.

Read the usage field to prove caching is working

# From any Claude API response, inspect response.usage:
{
"usage": {
  "input_tokens": 42,                    # billed at normal rate
  "cache_creation_input_tokens": 0,      # tokens written on this call
  "cache_read_input_tokens": 8912,       # tokens served from cache (cheap)
  "output_tokens": 384
}
}
# Healthy state after warm-up: cache_read >> cache_creation, run over run.
# If cache_creation stays high, something upstream of your breakpoint is changing.

캐싱 아키텍처에 커밋하기 전에 예상 절약을 모델링하려면 비용 계산기를 사용하세요.

결론

프롬프트 캐싱은 마이크로 최적화가 아닙니다. 동일한 큰 프리픽스를 반복적으로 보내는 어떤 애플리케이션에도, 이는 구조적인 경제적 결정입니다. 이를 생각하는 모델은 간단합니다: 안정된 콘텐츠가 먼저, 휘발성 콘텐츠가 마지막, 경계에 브레이크포인트를 두세요.

API에 대해 빌드하고 있고 아직 캐싱을 보지 않았다면, 큰 안정된 섹션이 있는지 현재 프롬프트를 확인하세요. 있다면, 캐싱 활성화는 보통 낮은 노력이고 절약은 실제입니다.

Check yourself

0/5

캐싱이 작동하려면 요청의 어디에 캐시 브레이크포인트가 있어야 합니까?
정상 입력 토큰보다 비용이 더 높은 것은?
모든 요청 상단에 현재 타임스탬프를 주입합니다 '모델이 시간을 알도록.' 캐싱에 무슨 일이 일어납니까?
프로덕션에서 캐싱이 실제로 돈을 절약하고 있음을 어떻게 증명합니까?
도구 정의에서 단어 하나를 변경합니다. 무엇이 무효화됩니까?

Key takeaways

캐싱은 입력 가격을 세 가지 방식으로 분할합니다: 캐시 쓰기 (프리미엄), 캐시 읽기 (저렴), 정상 입력 (정상) — 회수는 프리픽스 크기 × 재사용 빈도에 따라 확장됩니다.
하나의 규칙이 캐시 친화적 프롬프트를 만듭니다: 안정된 콘텐츠는 브레이크포인트 이전, 휘발성 콘텐츠는 이후 — 이를 뒤집으면 매 요청마다 캐시가 죽습니다.
최대 네 개의 브레이크포인트를 배치할 수 있어 도구, 시스템 프롬프트, 문서, 기록이 각각 자체 빈도로 캐시됩니다.
캐시된 블록 — 또는 프롬프트에서 더 앞의 어떤 블록 — 에 대한 어떤 변경도 그 브레이크포인트와 이후 모든 것을 무효화합니다.
usage 필드에서 cache_read_input_tokens 대 cache_creation_input_tokens로 절약을 증명하고, 배치 작업을 위해 max_tokens: 0으로 사전 워밍하세요.
프리픽스가 짧거나, 트래픽이 희소하거나 (캐시된 콘텐츠가 만료됨), 호출당 동적 콘텐츠에 비해 프리픽스가 작을 때 캐싱을 건너뛰세요.

정신 모델: 안정된 프리픽스, 휘발성 서픽스​

비용 모델 작동 방식​

프롬프트 캐싱이 도움이 될 때​

프롬프트 캐싱이 도움이 되지 않을 때​

캐시 친화적인 프롬프트 구성하기​