프롬프트 캐싱 (Prompt Caching)

긴 프롬프트나 반복 작업에서 같은 앞부분을 매번 처음부터 처리하면 시간과 비용이 크게 늘어나요. 프롬프트 캐싱은 이런 반복적인 앞부분을 재사용해서 처리 시간과 비용을 줄여주는 기능이에요. 특히 예시가 많은 프롬프트나 멀티턴 대화에서 효과가 커요.

출처: https://platform.claude.com/docs/en/build-with-claude/prompt-caching

캐싱을 켜는 두 가지 방법

프롬프트 캐싱에는 자동 캐싱과 명시적 캐시 브레이크포인트 두 가지가 있어요.

자동 캐싱 — 요청 최상위에 cache_control 필드 하나만 추가하면, 시스템이 마지막 캐시 가능한 블록에 캐시 브레이크포인트를 자동으로 적용하고 대화가 길어질수록 그 지점을 앞으로 옮겨요. 메시지 히스토리가 계속 늘어나는 멀티턴 대화에 가장 적합해요.
명시적 캐시 브레이크포인트 — 개별 콘텐츠 블록에 cache_control을 직접 붙여서, 정확히 어디까지 캐시할지를 세밀하게 통제해요.

가장 간단한 시작 방법은 자동 캐싱이에요. 요청의 최상위에 cache_control: {"type": "ephemeral"}을 넣으면 돼요.

{
  "model": "claude-opus-5",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": "You are an AI assistant tasked with analyzing literary works.",
  "messages": [
    {
      "role": "user",
      "content": "Analyze the major themes in Pride and Prejudice."
    }
  ]
}

자동 캐싱을 쓰면 시스템이 마지막 캐시 가능한 블록까지의 모든 콘텐츠를 캐시해요. 이후 같은 앞부분을 가진 요청이 오면 캐시된 콘텐츠를 자동으로 재사용해요.

동작 원리

프롬프트 캐싱이 켜진 요청은 이렇게 동작해요.

시스템이 최근 요청에서 캐시 브레이크포인트까지의 프롬프트 앞부분이 이미 캐시됐는지 확인해요.
캐시가 있으면 캐시된 버전을 써서 처리 시간과 비용을 줄여요.
캐시가 없으면 전체 프롬프트를 처리하고, 응답이 시작될 때 그 앞부분을 캐시해요.

캐시의 기본 수명은 5분이에요. 캐시된 콘텐츠를 사용할 때마다 추가 비용 없이 캐시가 갱신돼요. 이 수명은 응답이 끝난 시점이 아니라, 캐시 항목을 쓰거나 읽는 요청이 시작된 시점부터 세요. 그래서 응답 생성에 시간이 오래 걸리면 그만큼 여유 시간이 줄어요.

캐시는 프롬프트 전체를 대상으로 해요. tools, system, messages(이 순서)가 cache_control로 지정된 블록까지 포함한 전체를 참조하니까 기억해 두세요.

주의할 점

캐시는 조직 간에는 공유되지 않아요. 같은 프롬프트를 쓰더라도 다른 조직끼리는 절대 캐시를 공유하지 않아요.
캐시 히트가 나려면 캐시 지점까지의 프롬프트 조각이 텍스트와 이미지를 포함해 100% 동일해야 해요.
캐시된 앞부분은 여전히 컨텍스트 윈도우를 차지해요. 프롬프트 캐싱은 그 토큰에 얼마를 지불하는지를 바꾸는 거지, 차지 여부를 바꾸는 게 아니에요.

5분이 너무 짧다면 1시간짜리 캐시 수명도 추가 비용으로 제공돼요. 자세한 가격은 공식 문서의 가격 표를 참고하세요.

더 알아보기

캐시가 언제 무효화되는지는 «What invalidates the cache» 섹션을 봐요.
생각(thinking) 블록과 캐시의 조합은 «Thinking» 문서를 봐요.
요청 전에 토큰 수를 미리 세고 싶다면 «토큰 카운팅» 문서를 봐요.