실전 프롬프트 캐싱

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

프롬프트 캐싱의 작동 방식

콘텐츠를 캐싱 대상으로 표시하면, Claude는 이를 한 번 처리하고 결과를 저장합니다. 동일한 콘텐츠를 포함하는 후속 요청은 처리 단계를 건너뛰고 캐시에서 직접 읽어올 수 있습니다. 이는 캐시된 콘텐츠가 완전히 동일한 경우에만 작동하며, 단 한 글자만 변경되어도 캐시가 무효화됩니다.

하나의 요청에서 여러 개의 캐시 중단점을 설정할 수 있습니다. 캐싱 순서는 다음 순서를 따릅니다:

• 도구 스키마
• 시스템 프롬프트
• 메시지 기록

도구 스키마 캐싱 설정하기

도구 스키마를 캐싱하려면 목록의 마지막 도구에 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는 이를 완전히 새로운 콘텐츠로 취급하고 새로운 캐시 항목을 생성합니다.

이러한 민감성은 무엇을 캐싱할지 신중하게 고려해야 함을 의미합니다. 많은 요청에서 안정적으로 유지되는 도구 스키마와 시스템 프롬프트가 이상적인 후보입니다. 자주 변경되는 동적 콘텐츠는 캐싱의 이점을 얻지 못합니다.

실전 구현

실제로는 기본적으로 채팅 함수에 캐싱을 구축하는 것이 좋습니다. 대부분의 애플리케이션은 여러 요청에서 동일한 도구 스키마와 시스템 프롬프트를 사용하므로, 캐싱에 완벽하게 적합합니다. 유사한 콘텐츠로 많은 요청을 보낼 때 성능과 비용 측면의 이점이 상당합니다.

캐싱은 동일한 콘텐츠를 반복적으로 전송할 때 가장 가치가 있다는 점을 기억하세요. 실제 애플리케이션에서는 이런 상황이 매우 자주 발생하므로 - 특히 도구 스키마와 시스템 프롬프트의 경우 - 개발 프로세스 초기에 캐싱을 구현하면 애플리케이션이 확장됨에 따라 그 효과를 거두게 될 것입니다.