프롬프트 캐싱은 프롬프트의 특정 접두사에서 재개할 수 있도록 하여 API 사용을 최적화하는 강력한 기능입니다. 이 접근 방식은 반복적인 작업이나 일관된 요소가 있는 프롬프트의 처리 시간과 비용을 크게 줄입니다.

다음은 cache_control 블록을 사용하여 Messages API로 프롬프트 캐싱을 구현하는 예시입니다:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of Pride and Prejudice>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

# Call the model again with the same inputs up to the cache checkpoint
curl https://api.anthropic.com/v1/messages # rest of input
JSON
{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

이 예시에서는 “오만과 편견”의 전체 텍스트가 cache_control 매개변수를 사용하여 캐시됩니다. 이를 통해 매번 다시 처리하지 않고도 여러 API 호출에서 이 큰 텍스트를 재사용할 수 있습니다. 사용자 메시지만 변경하면 캐시된 콘텐츠를 활용하면서 책에 대한 다양한 질문을 할 수 있어 더 빠른 응답과 향상된 효율성을 얻을 수 있습니다.

​
프롬프트 캐싱 작동 방식

프롬프트 캐싱이 활성화된 요청을 보낼 때:

  1. 시스템은 지정된 캐시 중단점까지의 프롬프트 접두사가 최근 쿼리에서 이미 캐시되었는지 확인합니다.
  2. 찾으면 캐시된 버전을 사용하여 처리 시간과 비용을 줄입니다.
  3. 그렇지 않으면 전체 프롬프트를 처리하고 응답이 시작되면 접두사를 캐시합니다.

이는 특히 다음과 같은 경우에 유용합니다:

  • 많은 예시가 있는 프롬프트
  • 대량의 컨텍스트나 배경 정보
  • 일관된 지침이 있는 반복적인 작업
  • 긴 다중 턴 대화

기본적으로 캐시는 5분의 수명을 가집니다. 캐시된 콘텐츠가 사용될 때마다 추가 비용 없이 캐시가 새로 고쳐집니다.

5분이 너무 짧다고 생각되면 Anthropic은 1시간 캐시 지속 시간도 제공합니다.

자세한 정보는 1시간 캐시 지속 시간을 참조하세요.

프롬프트 캐싱은 전체 접두사를 캐시합니다

프롬프트 캐싱은 cache_control로 지정된 블록까지 포함하여 전체 프롬프트 - tools, system, messages (이 순서로)를 참조합니다.

​
가격

프롬프트 캐싱은 새로운 가격 구조를 도입합니다. 아래 표는 지원되는 각 모델의 백만 토큰당 가격을 보여줍니다:

ModelBase Input Tokens5m Cache Writes1h Cache WritesCache Hits & RefreshesOutput Tokens
Claude Opus 4.1$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
Claude Opus 4$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
Claude Sonnet 4$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Sonnet 3.7$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Sonnet 3.5 (deprecated)$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Haiku 3.5$0.80 / MTok$1 / MTok$1.6 / MTok$0.08 / MTok$4 / MTok
Claude Opus 3 (deprecated)$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
Claude Haiku 3$0.25 / MTok$0.30 / MTok$0.50 / MTok$0.03 / MTok$1.25 / MTok

위 표는 프롬프트 캐싱에 대한 다음 가격 승수를 반영합니다:

  • 5분 캐시 쓰기 토큰은 기본 입력 토큰 가격의 1.25배입니다
  • 1시간 캐시 쓰기 토큰은 기본 입력 토큰 가격의 2배입니다
  • 캐시 읽기 토큰은 기본 입력 토큰 가격의 0.1배입니다

​
프롬프트 캐싱 구현 방법

​
지원되는 모델

프롬프트 캐싱은 현재 다음에서 지원됩니다:

  • Claude Opus 4.1
  • Claude Opus 4
  • Claude Sonnet 4
  • Claude Sonnet 3.7
  • Claude Sonnet 3.5 (deprecated)
  • Claude Haiku 3.5
  • Claude Haiku 3
  • Claude Opus 3 (deprecated)

​
프롬프트 구조화

정적 콘텐츠(도구 정의, 시스템 지침, 컨텍스트, 예시)를 프롬프트의 시작 부분에 배치하세요. cache_control 매개변수를 사용하여 캐싱을 위한 재사용 가능한 콘텐츠의 끝을 표시하세요.

캐시 접두사는 다음 순서로 생성됩니다: tools, system, 그 다음 messages. 이 순서는 각 레벨이 이전 레벨을 기반으로 구축되는 계층을 형성합니다.

​
자동 접두사 확인 작동 방식

정적 콘텐츠의 끝에 하나의 캐시 중단점만 사용할 수 있으며, 시스템이 자동으로 가장 긴 일치하는 접두사를 찾습니다. 작동 방식은 다음과 같습니다:

  • cache_control 중단점을 추가하면 시스템이 자동으로 모든 이전 콘텐츠 블록 경계에서 캐시 히트를 확인합니다(명시적 중단점 이전 약 20개 블록까지)
  • 이러한 이전 위치 중 어느 것이라도 이전 요청의 캐시된 콘텐츠와 일치하면 시스템은 가장 긴 일치하는 접두사를 사용합니다
  • 이는 캐싱을 활성화하기 위해 여러 중단점이 필요하지 않다는 것을 의미합니다 - 끝에 하나만 있으면 충분합니다

​
여러 중단점을 사용하는 경우

다음을 원하는 경우 최대 4개의 캐시 중단점을 정의할 수 있습니다:

  • 다른 빈도로 변경되는 다른 섹션을 캐시 (예: 도구는 거의 변경되지 않지만 컨텍스트는 매일 업데이트됨)
  • 정확히 무엇이 캐시되는지에 대한 더 많은 제어권을 가짐
  • 최종 중단점 이전 20개 블록보다 많은 콘텐츠에 대한 캐싱을 보장

중요한 제한사항: 자동 접두사 확인은 각 명시적 중단점에서 약 20개 콘텐츠 블록만 뒤로 확인합니다. 프롬프트에 캐시 중단점 이전에 20개 이상의 콘텐츠 블록이 있는 경우, 추가 중단점을 추가하지 않으면 그보다 이전의 콘텐츠는 캐시 히트를 확인하지 않습니다.

​
캐시 제한사항

캐시 가능한 최소 프롬프트 길이는:

  • Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (deprecated) 및 Claude Opus 3 (deprecated)의 경우 1024 토큰
  • Claude Haiku 3.5 및 Claude Haiku 3의 경우 2048 토큰

더 짧은 프롬프트는 cache_control로 표시되어도 캐시할 수 없습니다. 이 토큰 수보다 적게 캐시하려는 요청은 캐싱 없이 처리됩니다. 프롬프트가 캐시되었는지 확인하려면 응답 사용량 필드를 참조하세요.

동시 요청의 경우 캐시 항목은 첫 번째 응답이 시작된 후에만 사용할 수 있습니다. 병렬 요청에 대한 캐시 히트가 필요한 경우 후속 요청을 보내기 전에 첫 번째 응답을 기다리세요.

현재 “ephemeral”이 유일하게 지원되는 캐시 유형이며, 기본적으로 5분의 수명을 가집니다.

​
캐시 중단점 비용 이해

캐시 중단점 자체는 비용을 추가하지 않습니다. 다음에 대해서만 요금이 부과됩니다:

  • 캐시 쓰기: 새로운 콘텐츠가 캐시에 쓰여질 때 (5분 TTL의 경우 기본 입력 토큰보다 25% 더 많음)
  • 캐시 읽기: 캐시된 콘텐츠가 사용될 때 (기본 입력 토큰 가격의 10%)
  • 일반 입력 토큰: 캐시되지 않은 콘텐츠에 대해

더 많은 cache_control 중단점을 추가해도 비용이 증가하지 않습니다 - 실제로 캐시되고 읽힌 콘텐츠에 따라 동일한 금액을 지불합니다. 중단점은 단순히 어떤 섹션이 독립적으로 캐시될 수 있는지에 대한 제어권을 제공합니다.

​
캐시할 수 있는 것

요청의 대부분 블록은 cache_control로 캐싱을 위해 지정할 수 있습니다. 여기에는 다음이 포함됩니다:

  • 도구: tools 배열의 도구 정의
  • 시스템 메시지: system 배열의 콘텐츠 블록
  • 텍스트 메시지: 사용자 및 어시스턴트 턴 모두에 대한 messages.content 배열의 콘텐츠 블록
  • 이미지 및 문서: 사용자 턴의 messages.content 배열의 콘텐츠 블록
  • 도구 사용 및 도구 결과: 사용자 및 어시스턴트 턴 모두에 대한 messages.content 배열의 콘텐츠 블록

이러한 각 요소는 cache_control로 표시하여 요청의 해당 부분에 대한 캐싱을 활성화할 수 있습니다.

​
캐시할 수 없는 것

대부분의 요청 블록을 캐시할 수 있지만 몇 가지 예외가 있습니다:

  • 사고 블록은 cache_control로 직접 캐시할 수 없습니다. 그러나 사고 블록은 이전 어시스턴트 턴에 나타날 때 다른 콘텐츠와 함께 캐시될 수 있습니다. 이렇게 캐시될 때 캐시에서 읽을 때 입력 토큰으로 계산됩니다.

  • 하위 콘텐츠 블록(인용 같은) 자체는 직접 캐시할 수 없습니다. 대신 최상위 블록을 캐시하세요.

    인용의 경우 인용이 참조할 소스 자료 역할을 하는 최상위 문서 콘텐츠 블록을 캐시할 수 있습니다. 이를 통해 인용이 참조할 문서를 캐시하여 인용과 함께 프롬프트 캐싱을 효과적으로 사용할 수 있습니다.

  • 빈 텍스트 블록은 캐시할 수 없습니다.

​
캐시를 무효화하는 것

캐시된 콘텐츠의 수정은 캐시의 일부 또는 전부를 무효화할 수 있습니다.

프롬프트 구조화에서 설명한 바와 같이 캐시는 계층을 따릅니다: tools → system → messages. 각 레벨의 변경은 해당 레벨과 모든 후속 레벨을 무효화합니다.

다음 표는 다른 유형의 변경으로 인해 캐시의 어떤 부분이 무효화되는지 보여줍니다. ✘는 캐시가 무효화됨을 나타내고 ✓는 캐시가 유효함을 나타냅니다.

변경 사항도구 캐시시스템 캐시메시지 캐시영향
도구 정의✘✘✘도구 정의(이름, 설명, 매개변수) 수정은 전체 캐시를 무효화합니다
웹 검색 토글✓✘✘웹 검색 활성화/비활성화는 시스템 프롬프트를 수정합니다
인용 토글✓✘✘인용 활성화/비활성화는 시스템 프롬프트를 수정합니다
도구 선택✓✓✘tool_choice 매개변수 변경은 메시지 블록에만 영향을 줍니다
이미지✓✓✘프롬프트 어디든 이미지 추가/제거는 메시지 블록에 영향을 줍니다
사고 매개변수✓✓✘확장 사고 설정 변경(활성화/비활성화, 예산)은 메시지 블록에 영향을 줍니다
확장 사고 요청에 전달된 비도구 결과✓✓✘확장 사고가 활성화된 상태에서 비도구 결과가 요청에 전달되면 이전에 캐시된 모든 사고 블록이 컨텍스트에서 제거되고 해당 사고 블록을 따르는 컨텍스트의 모든 메시지가 캐시에서 제거됩니다. 자세한 내용은 사고 블록과 함께 캐싱을 참조하세요.

​
캐시 성능 추적

API 응답 필드를 사용하여 캐시 성능을 모니터링하세요. 응답의 usage 내에서 (스트리밍인 경우 message_start 이벤트):

  • cache_creation_input_tokens: 새 항목을 생성할 때 캐시에 쓰여진 토큰 수.
  • cache_read_input_tokens: 이 요청에 대해 캐시에서 검색된 토큰 수.
  • input_tokens: 캐시에서 읽히거나 캐시를 생성하는 데 사용되지 않은 입력 토큰 수.

​
효과적인 캐싱을 위한 모범 사례

프롬프트 캐싱 성능을 최적화하려면:

  • 시스템 지침, 배경 정보, 큰 컨텍스트 또는 자주 사용하는 도구 정의와 같은 안정적이고 재사용 가능한 콘텐츠를 캐시하세요.
  • 최상의 성능을 위해 캐시된 콘텐츠를 프롬프트의 시작 부분에 배치하세요.
  • 캐시 중단점을 전략적으로 사용하여 다른 캐시 가능한 접두사 섹션을 분리하세요.
  • 캐시 히트율을 정기적으로 분석하고 필요에 따라 전략을 조정하세요.

​
다양한 사용 사례에 대한 최적화

시나리오에 맞게 프롬프트 캐싱 전략을 조정하세요:

  • 대화형 에이전트: 특히 긴 지침이나 업로드된 문서가 있는 확장된 대화의 비용과 지연 시간을 줄입니다.
  • 코딩 어시스턴트: 관련 섹션이나 코드베이스의 요약된 버전을 프롬프트에 유지하여 자동 완성 및 코드베이스 Q&A를 개선합니다.
  • 대용량 문서 처리: 응답 지연 시간을 늘리지 않고 이미지를 포함한 완전한 장문 자료를 프롬프트에 통합합니다.
  • 상세한 지침 세트: Claude의 응답을 미세 조정하기 위해 광범위한 지침, 절차 및 예시 목록을 공유합니다. 개발자들은 종종 프롬프트에 한두 개의 예시를 포함하지만 프롬프트 캐싱을 사용하면 20개 이상의 다양한 고품질 답변 예시를 포함하여 더 나은 성능을 얻을 수 있습니다.
  • 에이전틱 도구 사용: 여러 도구 호출과 반복적인 코드 변경이 포함된 시나리오의 성능을 향상시킵니다. 각 단계에서 일반적으로 새로운 API 호출이 필요합니다.
  • 책, 논문, 문서, 팟캐스트 대본 및 기타 장문 콘텐츠와 대화: 전체 문서를 프롬프트에 임베드하고 사용자가 질문할 수 있도록 하여 모든 지식 베이스를 생생하게 만듭니다.

​
일반적인 문제 해결

예상치 못한 동작이 발생하는 경우:

  • 캐시된 섹션이 동일하고 호출 간에 동일한 위치에서 cache_control로 표시되었는지 확인하세요
  • 호출이 캐시 수명(기본적으로 5분) 내에 이루어졌는지 확인하세요
  • tool_choice와 이미지 사용이 호출 간에 일관되게 유지되는지 확인하세요
  • 최소 토큰 수 이상을 캐시하고 있는지 확인하세요
  • 시스템은 자동으로 이전 콘텐츠 블록 경계에서 캐시 히트를 확인합니다(중단점 이전 약 20개 블록까지). 20개 이상의 콘텐츠 블록이 있는 프롬프트의 경우 모든 콘텐츠가 캐시될 수 있도록 프롬프트 앞부분에 추가 cache_control 매개변수가 필요할 수 있습니다

tool_choice의 변경이나 프롬프트 어디든 이미지의 존재/부재는 캐시를 무효화하여 새로운 캐시 항목을 생성해야 합니다. 캐시 무효화에 대한 자세한 내용은 캐시를 무효화하는 것을 참조하세요.

​
사고 블록과 함께 캐싱

확장 사고를 프롬프트 캐싱과 함께 사용할 때 사고 블록은 특별한 동작을 합니다:

다른 콘텐츠와 함께 자동 캐싱: 사고 블록은 cache_control로 명시적으로 표시할 수 없지만 도구 결과와 함께 후속 API 호출을 할 때 요청 콘텐츠의 일부로 캐시됩니다. 이는 사고 블록을 다시 전달하여 대화를 계속할 때 도구 사용 중에 일반적으로 발생합니다.

입력 토큰 계산: 사고 블록이 캐시에서 읽힐 때 사용량 메트릭에서 입력 토큰으로 계산됩니다. 이는 비용 계산과 토큰 예산 책정에 중요합니다.

캐시 무효화 패턴:

  • 도구 결과만 사용자 메시지로 제공될 때 캐시가 유효하게 유지됩니다
  • 비도구 결과 사용자 콘텐츠가 추가되면 캐시가 무효화되어 모든 이전 사고 블록이 제거됩니다
  • 이 캐싱 동작은 명시적인 cache_control 마커 없이도 발생합니다

캐시 무효화에 대한 자세한 내용은 캐시를 무효화하는 것을 참조하세요.

도구 사용 예시:

요청 1: 사용자: "파리의 날씨는 어떤가요?"
응답: [thinking_block_1] + [tool_use block 1]

요청 2: 
사용자: ["파리의 날씨는 어떤가요?"], 
어시스턴트: [thinking_block_1] + [tool_use block 1], 
사용자: [tool_result_1, cache=True]
응답: [thinking_block_2] + [text block 2]
# 요청 2는 요청 콘텐츠를 캐시합니다(응답이 아님)
# 캐시에는 사용자 메시지, thinking_block_1, tool_use block 1, tool_result_1이 포함됩니다

요청 3:
사용자: ["파리의 날씨는 어떤가요?"], 
어시스턴트: [thinking_block_1] + [tool_use block 1], 
사용자: [tool_result_1, cache=True], 
어시스턴트: [thinking_block_2] + [text block 2], 
사용자: [Text response, cache=True]
# 비도구 결과 사용자 블록으로 인해 모든 사고 블록이 무시됩니다
# 이 요청은 사고 블록이 존재하지 않았던 것처럼 처리됩니다

비도구 결과 사용자 블록이 포함되면 새로운 어시스턴트 루프를 지정하고 모든 이전 사고 블록이 컨텍스트에서 제거됩니다.

자세한 정보는 확장 사고 문서를 참조하세요.

​
캐시 저장 및 공유

  • 조직 격리: 캐시는 조직 간에 격리됩니다. 동일한 프롬프트를 사용하더라도 다른 조직은 캐시를 공유하지 않습니다.

  • 정확한 일치: 캐시 히트는 캐시 제어로 표시된 블록까지 포함하여 모든 텍스트와 이미지를 포함한 100% 동일한 프롬프트 세그먼트가 필요합니다.

  • 출력 토큰 생성: 프롬프트 캐싱은 출력 토큰 생성에 영향을 주지 않습니다. 받는 응답은 프롬프트 캐싱을 사용하지 않았을 때와 동일합니다.

​
1시간 캐시 지속 시간

5분이 너무 짧다고 생각되면 Anthropic은 1시간 캐시 지속 시간도 제공합니다.

확장 캐시를 사용하려면 다음과 같이 cache_control 정의에 ttl을 포함하세요:

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

응답에는 다음과 같은 자세한 캐시 정보가 포함됩니다:

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,
        
        "cache_creation": {
            "ephemeral_5m_input_tokens": 456,
            "ephemeral_1h_input_tokens": 100,
        }
    }
}

현재 cache_creation_input_tokens 필드는 cache_creation 객체의 값들의 합과 같습니다.

​
1시간 캐시를 사용하는 경우

정기적인 주기로 사용되는 프롬프트(즉, 5분마다보다 더 자주 사용되는 시스템 프롬프트)가 있는 경우 5분 캐시를 계속 사용하세요. 이는 추가 요금 없이 계속 새로 고쳐지기 때문입니다.

1시간 캐시는 다음 시나리오에서 가장 잘 사용됩니다:

  • 5분보다는 덜 자주 사용되지만 매시간보다는 더 자주 사용될 가능성이 있는 프롬프트가 있는 경우. 예를 들어, 에이전틱 사이드 에이전트가 5분보다 오래 걸리거나 사용자와의 긴 채팅 대화를 저장하고 일반적으로 해당 사용자가 다음 5분 내에 응답하지 않을 것으로 예상되는 경우.
  • 지연 시간이 중요하고 후속 프롬프트가 5분을 넘어서 전송될 수 있는 경우.
  • 캐시 히트가 속도 제한에서 차감되지 않으므로 속도 제한 활용도를 개선하려는 경우.

5분 및 1시간 캐시는 지연 시간과 관련하여 동일하게 동작합니다. 긴 문서에 대해 일반적으로 첫 번째 토큰까지의 시간이 개선됩니다.

​
다른 TTL 혼합

동일한 요청에서 1시간 및 5분 캐시 제어를 모두 사용할 수 있지만 중요한 제약이 있습니다: 더 긴 TTL을 가진 캐시 항목이 더 짧은 TTL보다 먼저 나타나야 합니다(즉, 1시간 캐시 항목이 5분 캐시 항목보다 먼저 나타나야 함).

TTL을 혼합할 때 프롬프트에서 세 가지 청구 위치를 결정합니다:

  1. 위치 A: 가장 높은 캐시 히트에서의 토큰 수(히트가 없으면 0).
  2. 위치 B: A 이후 가장 높은 1시간 cache_control 블록에서의 토큰 수(존재하지 않으면 A와 같음).
  3. 위치 C: 마지막 cache_control 블록에서의 토큰 수.

B 및/또는 C가 A보다 큰 경우 A가 가장 높은 캐시 히트이므로 반드시 캐시 미스가 됩니다.

다음에 대해 요금이 부과됩니다:

  1. A에 대한 캐시 읽기 토큰.
  2. (B - A)에 대한 1시간 캐시 쓰기 토큰.
  3. (C - B)에 대한 5분 캐시 쓰기 토큰.

다음은 3가지 예시입니다. 이는 3개 요청의 입력 토큰을 나타내며, 각각 다른 캐시 히트와 캐시 미스를 가집니다. 각각은 결과적으로 색상 상자에 표시된 대로 다른 계산된 가격을 가집니다.

​
프롬프트 캐싱 예시

프롬프트 캐싱을 시작하는 데 도움이 되도록 자세한 예시와 모범 사례가 포함된 프롬프트 캐싱 쿡북을 준비했습니다.

아래에는 다양한 프롬프트 캐싱 패턴을 보여주는 여러 코드 스니펫을 포함했습니다. 이러한 예시는 다양한 시나리오에서 캐싱을 구현하는 방법을 보여주어 이 기능의 실제 적용을 이해하는 데 도움이 됩니다:

​
FAQ