Claude Academy
로그인

실전 프롬프트 캐싱

강의 457분
Sign in to save your progressYou can keep reading without an account, but completed lessons won't be saved.
Sign in

프롬프트 캐싱은 동일한 콘텐츠를 Claude에 반복적으로 전송할 때 API 요청을 더 빠르고 더 저렴하게 만들어주는 강력한 최적화 기능입니다. 애플리케이션에서 이를 효과적으로 구현하는 방법을 살펴보겠습니다.

프롬프트 캐싱의 작동 방식

프롬프트 캐싱을 활성화하면 첫 번째 요청이 기본 5분 수명을 가진 캐시에 콘텐츠를 기록하며, 캐시된 콘텐츠가 사용될 때마다 추가 비용 없이 해당 기간이 갱신됩니다. 더 긴 기간이 필요한 경우, 추가 비용을 지불하고 1시간 캐시 기간을 선택할 수 있습니다. 후속 요청은 동일한 콘텐츠를 다시 처리하는 대신 이 캐시에서 읽어옵니다. 이는 다음과 같은 콘텐츠를 전송할 때 특히 유용합니다:

  • 대규모 시스템 프롬프트(예: 6K 토큰 규모의 코딩 어시스턴트 프롬프트)
  • 복잡한 도구 스키마(여러 도구에 대해 약 1.7K 토큰)
  • 반복되는 메시지 콘텐츠

핵심은 캐싱이 동일한 콘텐츠를 반복적으로 전송하는 경우에만 도움이 된다는 점입니다 - 하지만 많은 애플리케이션에서 이는 매우 자주 발생합니다.

도구 스키마 캐싱 설정하기

도구 스키마를 캐싱하려면 목록의 마지막 도구에 cache control 필드를 추가해야 합니다. 원래의 도구 정의를 수정하지 않고 이를 수행하는 올바른 방법은 다음과 같습니다:

python
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

이 접근 방식은 cache control 필드를 추가하기 전에 도구 목록과 마지막 도구 스키마 모두의 복사본을 생성합니다. tools[-1]["cache_control"]을 직접 수정할 수도 있지만, 복사 방식을 사용하면 나중에 도구 순서를 변경할 때 발생할 수 있는 문제를 방지할 수 있습니다.

시스템 프롬프트 캐싱

시스템 프롬프트의 경우, cache control이 포함된 텍스트 블록으로 구조화해야 합니다:

python
if system:
    params["system"] = [
        {
            "type": "text",
            "text": system,
            "cache_control": {"type": "ephemeral"}
        }
    ]

이렇게 하면 시스템 프롬프트가 단순한 문자열에서 캐싱을 지원하는 구조화된 형식으로 변환됩니다.

캐시 동작 이해하기

캐싱을 활성화한 상태로 요청을 실행하면 응답에서 다양한 사용 패턴을 확인할 수 있습니다:

  • 첫 번째 요청: cache_creation_input_tokens=1772 - Claude가 캐시에 기록합니다
  • 후속 요청: cache_read_input_tokens=1772 - Claude가 캐시에서 읽어옵니다
  • 변경된 콘텐츠: 새로운 캐시 생성 토큰이 나타납니다

캐시는 매우 민감합니다 - 도구나 시스템 프롬프트에서 단 한 글자만 변경해도 해당 구성 요소의 전체 캐시가 무효화됩니다.

캐시 순서와 중단점

단일 요청에서 여러 캐시 중단점을 설정할 수 있습니다. 순서가 중요합니다:

  1. 도구(제공된 경우)
  2. 시스템 프롬프트(제공된 경우)
  3. 메시지

시스템 프롬프트를 변경하되 동일한 도구를 유지하면, 부분 캐시 읽기(도구의 경우)와 캐시 쓰기(새로운 시스템 프롬프트의 경우)가 발생합니다. 이러한 세분화된 캐싱을 통해 실제로 변경된 부분에 대해서만 처리 비용을 지불하게 됩니다.

실용적인 고려 사항

프롬프트 캐싱은 다음과 같은 경우에 가장 효과적입니다:

  • 요청 전반에 걸쳐 일관된 도구 스키마
  • 안정적인 시스템 프롬프트
  • 유사한 컨텍스트로 여러 요청을 수행하는 애플리케이션

기본 캐시는 5분 동안 지속되며(사용할 때마다 갱신됨), 추가 비용을 지불하면 1시간 옵션을 사용할 수 있다는 점을 기억하세요. 따라서 장기 저장용이 아니라 API 사용이 상대적으로 빈번한 애플리케이션을 위해 설계되었습니다.