Claude의 프롬프트 캐싱은 메시지에 대해 수행된 연산 작업을 저장하여 후속 요청에서 재사용할 수 있도록 동작합니다. 이를 통해 캐시된 콘텐츠를 사용하는 요청은 더 저렴하고 더 빠르게 실행됩니다.
이 과정은 단순한 패턴을 따릅니다: 초기 요청은 캐시에 기록하고, 후속 요청은 캐시에서 읽어올 수 있습니다. 캐시는 5분 동안 유지되므로, 동일한 콘텐츠를 반복적으로 전송하는 경우에만 이 기능이 유용합니다. 하지만 실제 애플리케이션에서는 이런 일이 매우 자주 발생합니다.
캐시 중단점(Cache Breakpoints)
메시지에 대해 수행된 작업이 자동으로 캐시되는 것은 아닙니다. 블록에 'cache breakpoint(캐시 중단점)'를 수동으로 추가해야 합니다. 중단점 이전의 모든 작업은 캐시되며, 중단점까지 포함한 콘텐츠가 동일한 경우에만 후속 요청에서 캐시가 사용됩니다.
캐시 중단점을 추가해야 할 때는, 텍스트 블록을 작성할 때 축약형 대신 장황형(longhand) 형식을 사용해야 합니다. 차이점은 다음과 같습니다:
# 축약형 - 캐시 중단점을 추가할 수 없음
user_message = {
"role": "user",
"content": "Hi there!"
}
# 장형 - 캐시 중단점에 필요함
user_message = {
"role": "user",
"content": [
{
"type": "text",
"text": "Hi there!",
"cache_control": {
"type": "ephemeral"
}
}
]
}캐시 중단점의 작동 방식
캐시 중단점은 여러 메시지에 걸쳐 있을 수 있으며, assistant 메시지도 캐시할 수 있습니다. 중단점을 배치하면 그 지점까지의 모든 내용이 캐시됩니다. 캐시를 사용하려면 콘텐츠가 동일해야 한다는 점을 기억하세요!
후속 요청에서 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"}
}
]캐시 순서(Cache Ordering)
내부적으로, 도구, 시스템 프롬프트, 메시지는 Claude에 전달될 때 특정 순서로 결합됩니다. 이는 캐시 중단점의 작동 방식에 영향을 미칩니다.
총 4개까지 캐시 중단점을 추가할 수 있습니다. 마지막 도구에 중단점을 배치하면 그 도구까지의 모든 내용이 캐시되지만, 시스템 프롬프트와 메시지는 캐시되지 않습니다. 이를 통해 애플리케이션에서 변경되는 내용에 따라 캐시되는 항목을 세밀하게 제어할 수 있습니다.
최소 콘텐츠 길이
캐싱에는 최소 길이가 있으며, 이는 모델에 따라 다릅니다. 이 과정에서 사용하는 모델인 Claude Haiku 4.5의 경우, 캐시되려면 콘텐츠가 최소 4,096 토큰 이상이어야 합니다. 이는 개별 블록이 아니라, 캐시하려는 모든 메시지와 블록의 합계입니다.
"안녕하세요!"와 같은 메시지는 캐시되기에는 너무 짧지만, 실제로 긴 프롬프트는 최소치에 도달합니다. 최소치 미만의 콘텐츠는 캐싱 없이 단순히 처리되며, 오류가 반환되지 않습니다. 이를 확인하려면 응답의 사용량(usage)을 살펴보세요: cache_creation_input_tokens와 cache_read_input_tokens가 모두 0이 됩니다.
효과적인 프롬프트 캐싱의 핵심은 요청에서 일관되게 유지되는 부분—보통 시스템 프롬프트와 도구 정의—을 식별하고, 캐시 적중률을 극대화하면서 재처리를 최소화하도록 전략적으로 중단점을 배치하는 것입니다.