프롬프트 캐싱은 동일한 콘텐츠를 Claude에 반복적으로 전송할 때 API 요청을 더 빠르고 더 저렴하게 만들어주는 강력한 최적화 기능입니다. 이를 애플리케이션에 효과적으로 구현하는 방법을 살펴보겠습니다.
프롬프트 캐싱의 작동 방식
프롬프트 캐싱을 활성화하면 첫 번째 요청이 기본 수명 5분으로 콘텐츠를 캐시에 기록하며, 캐시된 콘텐츠가 사용될 때마다 추가 비용 없이 해당 창이 갱신됩니다. 더 긴 창이 필요한 경우 추가 비용을 내고 1시간 캐시 지속 시간을 선택할 수 있습니다. 후속 요청은 동일한 콘텐츠를 다시 처리하는 대신 이 캐시에서 읽어옵니다. 이는 다음과 같은 콘텐츠를 전송할 때 특히 유용합니다:
- 대규모 시스템 프롬프트(예: 6K 토큰 규모의 코딩 어시스턴트 프롬프트)
- 복잡한 도구 스키마(예: 여러 도구에 대한 상세한 정의)
- 반복되는 메시지 콘텐츠
핵심은 동일한 콘텐츠를 반복적으로 전송하는 경우에만 캐싱이 도움이 된다는 점이지만, 많은 애플리케이션에서 이런 상황은 매우 자주 발생합니다.
도구 스키마 캐싱 설정하기
도구 스키마를 캐싱하려면 목록의 마지막 도구에 캐시 제어 필드를 추가해야 합니다. 원래의 도구 정의를 수정하지 않고 이를 올바르게 수행하는 방법은 다음과 같습니다:
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이 방식은 캐시 제어 필드를 추가하기 전에 도구 목록과 마지막 도구 스키마 모두의 복사본을 생성합니다. tools[-1]["cache_control"]을 직접 수정할 수도 있지만, 복사하는 방식을 사용하면 나중에 도구 순서를 바꾸더라도 문제가 생기지 않습니다.
시스템 프롬프트 캐싱
시스템 프롬프트의 경우, 캐시 제어가 포함된 텍스트 블록으로 구조화해야 합니다:
if system:
params["system"] = [
{
"type": "text",
"text": system,
"cache_control": {"type": "ephemeral"}
}
]이는 시스템 프롬프트를 단순한 문자열에서 캐싱을 지원하는 구조화된 형식으로 변환합니다.
캐시 동작 이해하기
캐싱을 활성화한 상태로 요청을 실행하면 응답에서 다양한 사용 패턴을 확인할 수 있습니다:
- 첫 번째 요청:
cache_creation_input_tokens는 기록된 토큰 수를 보여줍니다 - Claude가 캐시에 기록합니다 - 후속 요청:
cache_read_input_tokens는 다시 읽어들인 동일한 토큰 수를 보여줍니다 - Claude가 캐시에서 읽어옵니다 - 콘텐츠가 변경된 경우: 새로운 캐시 생성 토큰이 나타납니다
캐시는 매우 민감해서 도구나 시스템 프롬프트에서 단 한 글자만 바꿔도 해당 구성요소의 전체 캐시가 무효화됩니다.
캐시 순서와 중단점
한 요청에서 여러 캐시 중단점을 설정할 수 있습니다. 순서가 중요합니다:
- 도구(제공된 경우)
- 시스템 프롬프트(제공된 경우)
- 메시지
시스템 프롬프트를 변경하되 도구는 동일하게 유지하면, (도구에 대해서는) 부분 캐시 읽기와 (새 시스템 프롬프트에 대해서는) 캐시 쓰기가 발생합니다. 이러한 부분 읽기는 도구만으로 최소 길이에 도달했을 때만 가능한데, 캐시 중단점까지의 콘텐츠가 최소 길이에 미치지 못하면 아무것도 기록하지 않기 때문입니다. 이러한 세분화된 캐싱 덕분에 실제로 변경된 부분에 대한 처리 비용만 지불하면 됩니다.
실용적인 고려사항
프롬프트 캐싱은 다음과 같은 경우에 가장 효과적입니다:
- 요청 전반에 걸쳐 일관된 도구 스키마
- 안정적인 시스템 프롬프트
- 유사한 컨텍스트로 여러 요청을 보내는 애플리케이션
기본 캐시는 5분간 지속되며(사용할 때마다 갱신됨), 추가 비용을 내면 1시간 옵션을 사용할 수 있다는 점을 기억하세요. 따라서 장기 저장보다는 상대적으로 API 사용이 빈번한 애플리케이션에 적합하도록 설계되었습니다.