프롬프트 캐싱은 Claude에게 동일한 콘텐츠를 반복적으로 전송할 때 요청을 더 저렴하고 더 빠르게 만들어주는 강력한 최적화 기능입니다. 최초 요청은 캐시에 쓰기를 수행하며, 후속 요청은 캐시에서 읽어올 수 있습니다. 캐시는 5분 동안 유지되며, 많은 애플리케이션이 동일한 도구 스키마, 시스템 프롬프트 또는 메시지 기록을 반복적으로 전송하기 때문에 매우 유용합니다.

프롬프트 캐싱의 작동 방식
캐싱을 위해 콘텐츠를 표시하면, Claude는 이를 한 번 처리하고 결과를 저장합니다. 정확히 동일한 콘텐츠를 포함하는 후속 요청은 처리 단계를 건너뛰고 캐시에서 직접 읽어올 수 있습니다. 이는 캐시된 콘텐츠가 동일할 경우에만 작동합니다. 단 한 글자만 변경되어도 캐시가 무효화됩니다.
하나의 요청에서 여러 캐시 중단점(cache breakpoint)을 설정할 수 있습니다. 캐싱 순서는 다음과 같습니다:
- 도구 스키마
- 시스템 프롬프트
- 메시지 기록
도구 스키마 캐싱 설정하기
도구 스키마를 캐시하려면 목록의 마지막 도구에 cache_control 필드를 추가해야 합니다. 원래의 도구 스키마를 수정하지 않고 이를 올바르게 수행하는 방법은 다음과 같습니다:
if tools:
tools_clone = tools.copy()
last_tool = tools_clone[-1].copy()
last_tool["cache_control"] = {"type": "ephemeral"}
tools_clone[-1] = last_tool
params["tools"] = tools_clone이 방식은 캐시 제어 필드를 추가하기 전에 도구 목록과 마지막 도구 스키마 모두의 사본을 생성합니다. 이렇게 하면 나중에 도구의 순서를 변경할 때 문제가 발생할 수 있는, 원래의 도구 정의를 실수로 수정하는 것을 방지할 수 있습니다.
시스템 프롬프트 캐싱
시스템 프롬프트의 경우, system 매개변수를 캐시 제어 필드가 포함된 텍스트 블록을 가진 목록 형태로 구성해야 합니다:
if system:
params["system"] = [
{
"type": "text",
"text": system,
"cache_control": {"type": "ephemeral"}
}
]캐시 동작 이해하기
캐시 가능한 콘텐츠로 첫 번째 요청을 할 때, usage 필드에서 cache_creation_input_tokens를 확인할 수 있습니다. 이는 Claude가 캐시에 기록한 토큰 수를 나타냅니다. 동일한 콘텐츠로 후속 요청을 할 때는 대신 cache_read_input_tokens를 확인할 수 있습니다.
동일한 요청에 캐시된 콘텐츠와 새로운 콘텐츠가 모두 포함되어 있는 경우, 캐시 읽기와 캐시 쓰기가 모두 발생하는 것을 볼 수 있습니다. 예를 들어, 동일한 도구 스키마를 유지하면서 시스템 프롬프트를 변경하는 경우, 도구는 캐시에서 읽어오고 새로운 시스템 프롬프트는 캐시에 씁니다. 도구만으로 최소 길이에 도달했을 때만 이러한 부분적인 읽기가 발생합니다. 해당 지점까지의 콘텐츠가 최소 길이 미만인 캐시 중단점은 아무것도 기록하지 않기 때문입니다.
캐시 무효화
캐시는 변경 사항에 매우 민감합니다. 도구 스키마 설명, 시스템 프롬프트 또는 캐시된 모든 콘텐츠에서 단 한 글자만 수정해도 해당 캐시 항목이 무효화됩니다. 이런 일이 발생하면 Claude는 이를 완전히 새로운 콘텐츠로 취급하고 새로운 캐시 항목을 생성합니다.
이러한 민감성은 무엇을 캐시할지 신중하게 고려해야 함을 의미합니다. 많은 요청에 걸쳐 안정적으로 유지되는 도구 스키마와 시스템 프롬프트는 이상적인 후보입니다. 자주 변경되는 동적 콘텐츠는 캐싱의 이점을 얻지 못합니다.
실제 구현
실제로는 기본적으로 채팅 함수에 캐싱을 구축하고 싶을 것입니다. 대부분의 애플리케이션은 여러 요청에 걸쳐 동일한 도구 스키마와 시스템 프롬프트를 사용하므로 캐싱에 완벽하게 적합합니다. 유사한 콘텐츠로 많은 요청을 할 때 성능과 비용 측면의 이점이 상당합니다.
캐싱은 동일한 콘텐츠를 반복적으로 전송할 때 가장 가치가 있다는 점을 기억하세요. 실제 애플리케이션에서는 이러한 일이 매우 빈번하게 발생하므로—특히 도구 스키마와 시스템 프롬프트의 경우—개발 프로세스 초기에 캐싱을 구현하면 애플리케이션이 확장됨에 따라 그 효과를 보게 될 것입니다.