프롬프트 캐싱 규칙

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

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

캐시 중단점(Cache Breakpoints)

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

캐시 중단점을 추가해야 할 때는 축약형 대신 텍스트 블록을 작성하는 장문형을 사용해야 합니다. 차이점은 다음과 같습니다:

# 축약형 - 캐시 중단점을 추가할 수 없음
user_message = {
  "role": "user",
  "content": "Hi there!"
}

# 전체 형식 - 캐시 중단점에 필요함
user_message = {
  "role": "user", 
  "content": [
    {
      "type": "text",
      "text": "",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

캐시 중단점의 작동 방식

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

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

중단점 위치

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

# 캐시 중단점이 있는 도구 정의
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"}
  }
]

캐시 순서

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

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

최소 콘텐츠 길이

콘텐츠는 캐시되기 위해 최소 1024 토큰 이상이어야 합니다(캐시하려는 모든 메시지/블록의 합계). 단순한 "Hi there!" 메시지는 이 기준을 충족하지 못하지만, 해당 텍스트를 500번 복제하면 캐시할 수 있는 충분한 토큰을 확보하게 됩니다.

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