프롬프트 캐싱은 동일한 콘텐츠를 Claude에 반복적으로 전송할 때 요청을 더 저렴하고 빠르게 만들어주는 강력한 최적화 기능입니다. 최초 요청은 캐시에 기록하며, 후속 요청은 캐시에서 읽을 수 있습니다. 캐시는 5분 동안 유지되며, 많은 애플리케이션이 동일한 도구 스키마, 시스템 프롬프트 또는 메시지 기록을 반복적으로 전송하기 때문에 매우 유용합니다.
프롬프트 캐싱 작동 방식
캐싱할 콘텐츠를 표시하면 Claude는 이를 한 번 처리하고 결과를 저장합니다. 정확히 동일한 콘텐츠를 포함하는 후속 요청은 처리 단계를 건너뛰고 캐시에서 직접 읽을 수 있습니다. 이는 캐시된 콘텐츠가 완전히 동일한 경우에만 작동합니다. 단 한 글자만 변경되어도 캐시가 무효화됩니다.
하나의 요청에서 여러 캐시 중단점(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는 이를 완전히 새로운 콘텐츠로 취급하고 새로운 캐시 항목을 생성합니다.
이러한 민감성 때문에 무엇을 캐싱할지 신중하게 고려해야 합니다. 여러 요청에 걸쳐 안정적으로 유지되는 도구 스키마와 시스템 프롬프트가 이상적인 후보입니다. 자주 변경되는 동적 콘텐츠는 캐싱의 이점을 누리기 어렵습니다.
실제 구현
실제로는 기본적으로 채팅 함수에 캐싱을 구축해 넣는 것이 좋습니다. 대부분의 애플리케이션은 여러 요청에 걸쳐 동일한 도구 스키마와 시스템 프롬프트를 사용하므로, 캐싱에 완벽하게 적합합니다. 유사한 콘텐츠로 많은 요청을 보낼 때 성능과 비용 면에서의 이점이 상당합니다.
캐싱은 동일한 콘텐츠를 반복적으로 전송할 때 가장 가치가 있다는 점을 기억하세요. 실제 애플리케이션에서는 이런 일이, 특히 도구 스키마와 시스템 프롬프트의 경우 매우 자주 발생하므로, 개발 프로세스 초기에 캐싱을 구현하면 애플리케이션이 확장됨에 따라 큰 이점을 누릴 수 있습니다.