로드 중
로드 중

Claude의 프롬프트 캐싱은 메시지에 대해 수행한 연산 작업을 저장해두어 후속 요청에서 재사용할 수 있도록 하는 방식으로 작동합니다. 이를 통해 캐시된 콘텐츠를 사용하는 요청은 더 저렴하고 더 빠르게 실행됩니다.

Claude가 "Please summarize this" 프롬프트에 대한 작업 결과를 캐시에 기록한 다음, 후속 요청에서 이를 읽어들입니다.

이 과정은 간단한 패턴을 따릅니다. 초기 요청은 캐시에 기록하고, 후속 요청은 캐시에서 읽을 수 있습니다. 캐시는 5분간 유지되므로, 동일한 콘텐츠를 반복적으로 전송하는 경우에만 이 기능이 유용하지만, 실제 애플리케이션에서는 이런 상황이 매우 빈번하게 발생합니다.

캐시 중단점(Cache Breakpoints)

메시지에 대해 수행된 작업은 자동으로 캐시되지 않습니다. 블록에 '캐시 중단점(cache breakpoint)'을 수동으로 추가해야 합니다. 중단점 이전의 모든 작업이 캐시되며, 중단점을 포함한 그 이전까지의 콘텐츠가 동일한 경우에만 후속 요청에서 캐시가 사용됩니다.

긴 프롬프트를 담은 사용자 메시지 텍스트 블록과, "cache_control" 타입 "ephemeral"로 표시된 캐시 중단점.

캐시 중단점을 추가해야 할 때는 텍스트 블록을 작성할 때 짧은 형식(shorthand) 대신 긴 형식(longhand)을 사용해야 합니다. 그 차이는 다음과 같습니다:

python
# 약식 - 캐시 중단점 추가 불가
user_message = {
  "role": "user",
  "content": "Hi there!"
}

# 전체 표기 - 캐시 중단점에 필요
user_message = {
  "role": "user", 
  "content": [
    {
      "type": "text",
      "text": "Hi there!",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

캐시 중단점의 작동 방식

캐시 중단점은 여러 메시지에 걸쳐 적용되며, assistant 메시지도 캐시할 수 있습니다. 중단점을 배치하면 그 지점까지의 모든 내용이 캐시됩니다. 캐시를 사용하려면 콘텐츠가 동일해야 한다는 점을 기억하세요!

네 개의 텍스트 블록 각각에 대해 Claude에서 수행한 작업. 첫 번째 블록 뒤에 점선으로 표시된 중단점이 있고 Cache 박스는 비어 있습니다.

후속 요청에서 Claude는 재처리하는 대신 이전에 처리된 작업을 캐시에서 읽어옵니다:

후속 요청의 세 블록에 대해 Claude가 캐시된 작업을 읽어옵니다. 마지막 블록 "Focus the summary on"에 중단점이 있습니다.

중단점 위치

텍스트 블록에만 국한되지 않습니다! 시스템 프롬프트와 도구 정의에도 캐시 중단점을 추가할 수 있습니다. 이들은 요청 간에 거의 변경되지 않기 때문에 실제로 가장 흔한 캐싱 기회입니다.

python
# 캐시 중단점이 있는 도구 정의
tools = [
  add_duration_to_datetime_schema,
  get_current_datetime_schema,
  {
    "name": "set_reminder",
    "description": "Sets a reminder...",
    "input_schema": { ... },
    "cache_control": {"type": "ephemeral"}
  }
]

# 캐시 중단점이 있는 시스템 프롬프트
system = [
  {
    "type": "text",
    "text": "You are a senior software...",
    "cache_control": {"type": "ephemeral"}
  }
]

캐시 순서(Cache Ordering)

내부적으로 도구, 시스템 프롬프트, 메시지는 Claude에 전달될 때 그 특정 순서로 결합됩니다. 이는 캐시 중단점의 작동 방식에 영향을 미칩니다.

두 요청 모두 캐시 중단점이 시스템 프롬프트와 메시지보다 앞선 Tool 3에 위치합니다. 요청 2의 assistant 메시지는 변경되었습니다.

총 4개까지 캐시 중단점을 추가할 수 있습니다. 마지막 도구에 중단점을 배치하면 해당 도구까지의 모든 것이 캐시되지만, 시스템 프롬프트와 메시지는 캐시되지 않습니다. 이를 통해 애플리케이션에서 변경되는 내용에 따라 무엇을 캐시할지 세밀하게 제어할 수 있습니다.

최소 콘텐츠 길이

캐싱에는 최소 길이가 있으며, 이는 모델에 따라 다릅니다. 이 과정에서 사용하는 모델인 Claude Haiku 4.5의 경우, 콘텐츠가 캐시되려면 최소 4,096 토큰 이상이어야 합니다. 이는 캐시하려는 모든 메시지와 블록의 합계이며, 개별 블록을 의미하는 것이 아닙니다.

"Hi there!"와 같은 메시지는 캐시되기에 너무 짧지만, 실제로 긴 프롬프트는 최소치에 도달합니다. 최소치 미만의 콘텐츠는 캐싱 없이 그냥 처리되며, 오류가 반환되지 않습니다. 이를 확인하려면 응답의 사용량(usage)을 살펴보세요. cache_creation_input_tokens와 cache_read_input_tokens가 모두 0이 됩니다.

효과적인 프롬프트 캐싱의 핵심은 요청에서 일관되게 유지되는 부분 - 대개 시스템 프롬프트와 도구 정의 - 을 파악하고, 캐시 히트를 극대화하면서 재처리를 최소화할 수 있도록 전략적으로 중단점을 배치하는 것입니다.