Claude Platform Docs
Messages컨텍스트 관리

프롬프트 캐싱

cache_control로 프롬프트 접두사를 캐싱하여 비용과 지연 시간을 줄이세요. 자동 캐싱 또는 5분 또는 1시간 TTL의 명시적 중단점을 사용할 수 있습니다.

제품별로 사용법이 다릅니다

Messages API
최상위 수준 또는 블록에서 cache_control로 사용을 선택하세요.
Managed Agents
항상 활성화캐시 항목은 기본적으로 5분 수명을 사용하며, 캐시 읽기와 쓰기는 세션 사용량에 표시됩니다.

“Prompt caching”(프롬프트 캐싱)은 API가 프롬프트의 특정 접두사(prefix)부터 재개할 수 있도록 하여 API 사용을 최적화합니다. 이를 통해 반복적인 작업이나 일관된 요소를 가진 프롬프트의 처리 시간과 비용이 크게 줄어듭니다.

프롬프트 캐싱을 활성화하는 방법은 두 가지입니다:

  • 자동 캐싱: 요청의 최상위 수준에 단일 cache_control 필드를 추가합니다. 시스템이 캐시 중단점을 마지막 캐시 가능한 블록에 자동으로 적용하고, 대화가 길어짐에 따라 앞으로 이동시킵니다. 늘어나는 메시지 기록을 자동으로 캐싱해야 하는 멀티턴 대화에 가장 적합합니다.
  • 명시적 캐시 중단점: 개별 콘텐츠 블록에 cache_control을 직접 배치하여 정확히 무엇을 캐싱할지 세밀하게 제어합니다.

가장 간단하게 시작하는 방법은 자동 캐싱을 사용하는 것입니다:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
    messages=[
        {
            "role": "user",
            "content": "Analyze the major themes in 'Pride and Prejudice'.",
        }
    ],
)
print(response.usage.model_dump_json())

자동 캐싱을 사용하면 시스템은 마지막 캐시 가능한 블록까지(해당 블록 포함)의 모든 콘텐츠를 캐싱합니다. 동일한 접두사를 가진 후속 요청에서는 캐싱된 콘텐츠가 자동으로 재사용됩니다.

프롬프트 캐싱의 작동 방식

프롬프트 캐싱이 활성화된 상태로 요청을 보내면:

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

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

  • 많은 예시가 포함된 프롬프트
  • 대량의 컨텍스트 또는 배경 정보
  • 일관된 지침을 가진 반복 작업
  • 긴 멀티턴 대화

기본적으로 캐시의 수명은 5분입니다. 캐싱된 콘텐츠가 사용될 때마다 추가 비용 없이 캐시가 갱신됩니다.

수명은 캐시 항목을 쓰거나 읽는 요청의 시작 시점부터 측정되며, 응답이 끝난 시점부터가 아닙니다. 응답 생성에 소요된 시간도 수명에 포함됩니다. 응답을 스트리밍하는 데 4분이 걸린다면, 동일한 캐싱된 접두사를 재사용하는 후속 요청은 해당 응답이 완료된 후 약 1분 이내에 시작되어야 합니다.

가격

프롬프트 캐싱에는 별도의 가격이 적용됩니다. 다음 표는 지원되는 각 모델의 백만 토큰당 가격을 보여줍니다:

모델기본 토큰프롬프트 캐싱
이름입력출력5분 쓰기1시간 쓰기캐시 적중 및 갱신
Claude Fable 5.1For demanding reasoning and long-horizon agentic work
US$10 / MTok
US$50 / MTok
US$12.50 / MTok
US$20 / MTok
US$0.25 / MTok1
Claude Opus 5.5For long-running agentic coding and knowledge work
US$4 / MTok
US$20 / MTok
US$5 / MTok
US$8 / MTok
US$0.20 / MTok2
Claude Sonnet 5.5The best combination of speed and intelligence
US$2 / MTok
US$10 / MTok
US$2.50 / MTok
US$4 / MTok
US$0.10 / MTok2
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing
US$0.10 / MTok100,000토큰 이하 프롬프트 기준
US$0.50 / MTok
US$0.125 / MTok
US$0.20 / MTok
US$0.01 / MTok
US$0.50 / MTok100,000토큰을 초과하는 프롬프트의 경우
US$2.50 / MTok
US$0.625 / MTok
US$1 / MTok
US$0.05 / MTok
US$10 / MTok
US$50 / MTok
US$12.50 / MTok
US$20 / MTok
US$0.25 / MTok1
US$10 / MTok
US$50 / MTok
US$12.50 / MTok
US$20 / MTok
US$1 / MTok
US$10 / MTok
US$50 / MTok
US$12.50 / MTok
US$20 / MTok
US$1 / MTok
US$5 / MTok
US$25 / MTok
US$6.25 / MTok
US$10 / MTok
US$0.50 / MTok
US$5 / MTok
US$25 / MTok
US$6.25 / MTok
US$10 / MTok
US$0.50 / MTok
US$5 / MTok
US$25 / MTok
US$6.25 / MTok
US$10 / MTok
US$0.50 / MTok
US$5 / MTok
US$25 / MTok
US$6.25 / MTok
US$10 / MTok
US$0.50 / MTok
US$5 / MTok
US$25 / MTok
US$6.25 / MTok
US$10 / MTok
US$0.50 / MTok
Claude Opus 4.1
US$15 / MTok
US$75 / MTok
US$18.75 / MTok
US$30 / MTok
US$1.50 / MTok
Claude Opus 4
US$15 / MTok
US$75 / MTok
US$18.75 / MTok
US$30 / MTok
US$1.50 / MTok
US$2 / MTok
US$10 / MTok
US$2.50 / MTok
US$4 / MTok
US$0.20 / MTok
US$3 / MTok
US$15 / MTok
US$3.75 / MTok
US$6 / MTok
US$0.30 / MTok
US$3 / MTok
US$15 / MTok
US$3.75 / MTok
US$6 / MTok
US$0.30 / MTok
Claude Sonnet 4
US$3 / MTok
US$15 / MTok
US$3.75 / MTok
US$6 / MTok
US$0.30 / MTok
US$1 / MTok
US$5 / MTok
US$1.25 / MTok
US$2 / MTok
US$0.10 / MTok

1 Claude Fable 5.1 및 Claude Mythos 5.1 모델의 캐시 적중 및 갱신에는 기본 입력 가격의 0.025x 요금이 적용됩니다.

2 Claude Opus 5.5 및 Claude Sonnet 5.5 모델의 캐시 적중 및 갱신에는 기본 입력 가격의 0.05x 요금이 적용됩니다.

다른 모든 모델은 표준 0.1x 배수를 사용합니다.

지원되는 모델

프롬프트 캐싱(자동 및 명시적 모두)은 모든 활성 Claude 모델에서 지원됩니다.

자동 캐싱

자동 캐싱은 프롬프트 캐싱을 활성화하는 가장 간단한 방법입니다. 개별 콘텐츠 블록에 cache_control을 배치하는 대신, 요청 본문의 최상위 수준에 단일 cache_control 필드를 추가하세요. 시스템이 캐시 중단점을 마지막 캐시 가능한 블록에 자동으로 적용합니다.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a helpful assistant that remembers our conversation.",
    messages=[
        {"role": "user", "content": "My name is Alex. I work on machine learning."},
        {
            "role": "assistant",
            "content": "Nice to meet you, Alex! How can I help with your ML work today?",
        },
        {"role": "user", "content": "What did I say I work on?"},
    ],
)
print(response.usage.model_dump_json())

멀티턴 대화에서 자동 캐싱의 작동 방식

자동 캐싱을 사용하면 대화가 길어짐에 따라 캐시 지점이 자동으로 앞으로 이동합니다. 각 새 요청은 마지막 캐시 가능한 블록까지의 모든 내용을 캐싱하고, 이전 콘텐츠는 캐시에서 읽습니다.

요청콘텐츠캐시 동작
요청 1System
+ User(1) + Asst(1)
+ User(2) ◀ 캐시		모든 내용이 캐시에 쓰여짐
요청 2System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ User(3) ◀ 캐시		System부터 User(2)까지 캐시에서 읽음;
Asst(2) + User(3)이 캐시에 쓰여짐
요청 3System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ User(3) + Asst(3)
+ User(4) ◀ 캐시		System부터 User(3)까지 캐시에서 읽음;
Asst(3) + User(4)가 캐시에 쓰여짐

캐시 중단점은 각 요청에서 마지막 캐시 가능한 블록으로 자동 이동하므로, 대화가 길어져도 cache_control 마커를 업데이트할 필요가 없습니다.

TTL 지원

기본적으로 자동 캐싱은 5분 TTL을 사용합니다. 기본 입력 토큰 가격의 2배로 1시간 TTL을 지정할 수 있습니다:

{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }

블록 수준 캐싱과 결합하기

자동 캐싱은 명시적 캐시 중단점과 호환됩니다. 함께 사용하면 자동 캐시 중단점은 사용 가능한 4개의 중단점 슬롯 중 하나를 사용합니다.

이를 통해 두 가지 접근 방식을 결합할 수 있습니다. 예를 들어, 명시적 중단점을 사용하여 시스템 프롬프트를 캐싱하고, 자동 캐싱이 대화를 처리하도록 할 수 있습니다:

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What are the key terms?" }]
}

동일하게 유지되는 사항

자동 캐싱은 동일한 기본 캐싱 인프라를 사용합니다. 가격, 최소 토큰 임계값, 컨텍스트 순서 요구 사항, 20블록 lookback 윈도우는 모두 명시적 중단점과 동일하게 적용됩니다.

엣지 케이스

  • 마지막 블록에 이미 동일한 TTL의 명시적 cache_control이 있으면 자동 캐싱은 아무 작업도 하지 않습니다.
  • 마지막 블록에 다른 TTL의 명시적 cache_control이 있으면 API는 400 오류를 반환합니다.
  • 명시적 블록 수준 중단점이 이미 4개 있으면 API는 400 오류를 반환합니다(자동 캐싱을 위한 슬롯이 남아 있지 않음).
  • 마지막 블록이 자동 캐시 중단점 대상으로 적합하지 않으면, 시스템은 조용히 뒤로 이동하여 가장 가까운 적합한 블록을 찾습니다. 찾지 못하면 캐싱을 건너뜁니다.

명시적 캐시 중단점

캐싱을 더 세밀하게 제어하려면 개별 콘텐츠 블록에 cache_control을 직접 배치할 수 있습니다. 이는 서로 다른 빈도로 변경되는 여러 섹션을 캐싱해야 하거나, 정확히 무엇을 캐싱할지 세밀하게 제어해야 할 때 유용합니다.

프롬프트 구성하기

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

캐시 접두사는 tools, system, messages 순서로 생성됩니다. 이 순서는 각 수준이 이전 수준을 기반으로 구축되는 계층 구조를 형성합니다.

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

정적 콘텐츠의 끝에 캐시 중단점 하나만 사용해도, 시스템은 이전 요청이 이미 캐시에 쓴 가장 긴 접두사를 자동으로 찾습니다. 이 작동 방식을 이해하면 캐싱 전략을 최적화하는 데 도움이 됩니다.

세 가지 핵심 원칙:

  1. 캐시 쓰기는 중단점에서만 발생합니다. 블록을 cache_control로 표시하면 정확히 하나의 캐시 항목, 즉 해당 블록에서 끝나는 접두사의 해시가 쓰여집니다. 시스템은 그보다 앞선 위치에 대해서는 항목을 쓰지 않습니다. 해시는 중단점까지(해당 블록 포함)의 모든 내용을 포괄하는 누적 값이므로, 중단점 또는 그 이전의 블록을 변경하면 다음 요청에서 다른 해시가 생성됩니다.

  2. 캐시 읽기는 이전 요청이 쓴 항목을 찾기 위해 뒤로 탐색합니다. 각 요청에서 시스템은 중단점의 접두사 해시를 계산하고 일치하는 캐시 항목이 있는지 확인합니다. 없으면 한 번에 한 블록씩 뒤로 이동하며, 각 이전 위치의 접두사 해시가 이미 캐시에 있는 항목과 일치하는지 확인합니다. 이는 안정적인 콘텐츠가 아니라 이전의 쓰기를 찾는 것입니다.

  3. Lookback 윈도우는 20블록입니다. 시스템은 각 중단점에 대해 중단점 자체를 첫 번째로 세어 최대 20개 위치를 확인합니다. 해당 윈도우에서 일치하는 항목을 찾지 못하면 확인이 중단됩니다(또는 다음 명시적 중단점이 있으면 그곳에서 재개됩니다). Claude API에서는 연속된 tool_use 블록들이 하나의 위치로 계산되고, 연속된 tool_result 블록들도 마찬가지이므로, 병렬 도구 호출이 많은 턴이 그 자체만으로 이전 요청의 항목을 윈도우 밖으로 밀어내지는 않습니다.

예시: 늘어나는 대화에서의 lookback

매 턴마다 새 블록을 추가하고 각 요청의 마지막 블록에 cache_control을 설정합니다:

  • 턴 1: 10개 블록, 블록 10에 중단점. 이전 캐시 항목이 없습니다. 시스템은 블록 10에 항목을 씁니다.
  • 턴 2: 15개 블록, 블록 15에 중단점. 블록 15에는 항목이 없으므로 시스템은 블록 10까지 뒤로 이동하여 턴 1의 항목을 찾습니다. 블록 10에서 캐시 적중이 발생합니다. 시스템은 블록 11부터 15까지만 새로 처리하고 블록 15에 새 항목을 씁니다.
  • 턴 3: 35개 블록, 블록 35에 중단점. 시스템은 20개 위치(블록 35부터 16까지)를 확인하지만 아무것도 찾지 못합니다. 블록 15에 있는 턴 2의 항목은 윈도우에서 한 위치 벗어나 있으므로 캐시 적중이 없습니다. 블록 15에 두 번째 중단점을 추가하면 그곳에서 두 번째 lookback 윈도우가 시작되어 턴 2의 항목을 찾습니다.

흔한 실수: 매 요청마다 변경되는 콘텐츠에 중단점 설정

프롬프트에 큰 정적 시스템 컨텍스트(블록 1부터 5까지)가 있고, 그 뒤에 타임스탬프와 사용자 메시지가 포함된 요청별 블록(블록 6)이 있습니다. 블록 6에 cache_control을 설정합니다:

  • 요청 1: 블록 6에서 캐시 쓰기. 해시에 타임스탬프가 포함됩니다.
  • 요청 2: 타임스탬프가 다르므로 블록 6의 접두사 해시가 다릅니다. Lookback은 블록 5, 4, 3, 2, 1을 거치지만, 시스템은 이 위치들 중 어디에도 항목을 쓴 적이 없습니다. 캐시 적중이 없습니다. 매 요청마다 새 캐시 쓰기 비용을 지불하면서 읽기는 한 번도 얻지 못합니다.

Lookback은 중단점 이전에 있는 안정적인 콘텐츠를 찾아서 캐싱하지 않습니다. 이전 요청이 이미 쓴 항목을 찾으며, 쓰기는 중단점에서만 발생합니다. 요청 간에 동일하게 유지되는 마지막 블록인 블록 5로 cache_control을 옮기면, 이후의 모든 요청이 캐싱된 접두사를 읽습니다. 자동 캐싱에도 같은 문제가 있습니다. 자동 캐싱은 마지막 캐시 가능한 블록에 중단점을 배치하는데, 이 구조에서는 그 블록이 매 요청마다 변경되는 블록이므로, 대신 블록 5에 명시적 중단점을 사용하세요.

핵심 요점: 캐시를 공유하려는 요청들 간에 접두사가 동일한 마지막 블록에 cache_control을 배치하세요. 늘어나는 대화에서는 각 턴이 추가하는 블록이 20개 미만인 한 마지막 블록이 잘 작동합니다. 이전 콘텐츠는 절대 변경되지 않으므로 다음 요청의 lookback이 이전의 쓰기를 찾습니다. 변하는 접미사(타임스탬프, 요청별 컨텍스트, 들어오는 메시지)가 있는 프롬프트의 경우, 변하는 블록이 아니라 정적 접두사의 끝에 중단점을 배치하세요.

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

다음과 같은 경우 최대 4개의 캐시 중단점을 정의할 수 있습니다:

  • 서로 다른 빈도로 변경되는 섹션을 캐싱하려는 경우(예: 도구는 거의 변경되지 않지만 컨텍스트는 매일 업데이트됨)
  • 정확히 무엇이 캐싱되는지 더 세밀하게 제어하려는 경우
  • 늘어나는 대화가 중단점을 마지막 캐시 쓰기보다 20블록 이상 뒤로 밀어낼 때 캐시 적중을 보장하려는 경우

캐시 중단점 비용 이해하기

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

  • 캐시 쓰기: 새 콘텐츠가 캐시에 쓰여질 때(5분 TTL의 경우 기본 입력 토큰보다 25퍼센트 더 비쌈)
  • 캐시 읽기: 캐싱된 콘텐츠가 사용될 때(기본 입력 토큰 가격의 10퍼센트, 모델별 예외 있음)
  • 일반 입력 토큰: 캐싱되지 않은 모든 콘텐츠

cache_control 중단점을 더 추가해도 비용은 증가하지 않습니다. 실제로 캐싱되고 읽히는 콘텐츠에 따라 동일한 금액을 지불합니다. 중단점은 어떤 섹션을 독립적으로 캐싱할 수 있는지 제어할 수 있게 해줍니다.

캐싱 전략 및 고려 사항

캐시 제한 사항

Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Google managed), Microsoft Foundry에서 캐시 가능한 최소 프롬프트 길이는 다음과 같습니다:

이러한 최솟값은 각 모델을 사용할 수 있는 모든 플랫폼에 적용됩니다.

더 짧은 프롬프트는 cache_control로 표시되어 있더라도 캐싱할 수 없습니다. 이 토큰 수보다 적은 토큰을 캐싱하려는 요청은 캐싱 없이 처리되며, 오류는 반환되지 않습니다. 프롬프트가 캐싱되었는지 확인하려면 응답 usage 필드를 확인하세요. cache_creation_input_tokens와 cache_read_input_tokens가 모두 0이면 프롬프트가 캐싱되지 않은 것입니다(최소 길이 요구 사항을 충족하지 못했기 때문일 가능성이 높음).

프롬프트가 해당 모델과 플랫폼의 최솟값에 약간 못 미치는 경우, 캐싱되는 콘텐츠를 확장하여 임계값에 도달하는 것이 종종 가치가 있습니다. 캐시 읽기는 캐싱되지 않은 입력 토큰보다 비용이 훨씬 적으므로, 최솟값에 도달하면 자주 재사용되는 프롬프트의 비용을 줄일 수 있습니다.

동시 요청의 경우, 캐시 항목은 첫 번째 응답이 시작된 후에만 사용 가능하다는 점에 유의하세요. 병렬 요청에서 캐시 적중이 필요한 경우, 후속 요청을 보내기 전에 첫 번째 응답을 기다리세요.

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

캐싱할 수 있는 항목

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

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

이러한 각 요소는 자동으로 또는 cache_control로 표시하여 캐싱할 수 있습니다.

캐싱할 수 없는 항목

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

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

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

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

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

캐시를 무효화하는 요소

캐싱된 콘텐츠를 수정하면 캐시의 일부 또는 전체가 무효화될 수 있습니다.

프롬프트 구성하기에서 설명한 대로, 캐시는 tools → system → messages 계층 구조를 따릅니다. 각 수준의 변경은 해당 수준과 이후의 모든 수준을 무효화합니다.

다음 표는 다양한 유형의 변경에 따라 캐시의 어느 부분이 무효화되는지 보여줍니다. ✘는 캐시가 무효화됨을 나타내고, ✓는 캐시가 유효하게 유지됨을 나타냅니다.

변경 사항도구 캐시시스템 캐시메시지 캐시영향
도구 정의✘✘✘도구 정의(이름, 설명, 매개변수)를 수정하면 전체 캐시가 무효화됩니다
웹 검색 토글✓✘✘웹 검색을 활성화/비활성화하면 시스템 프롬프트가 수정됩니다
인용 토글✓✘✘인용을 활성화/비활성화하면 시스템 프롬프트가 수정됩니다
속도 설정✓✘✘speed: "fast"와 표준 속도 간 전환은 시스템 및 메시지 캐시를 무효화합니다
도구 선택✓✓✘tool_choice 매개변수의 변경은 메시지 블록에만 영향을 미칩니다
이미지✓✓✘프롬프트의 어느 위치에서든 이미지를 추가/제거하면 메시지 블록에 영향을 미칩니다
사고 매개변수모델별 상이모델별 상이✘사고 구성(모드, 그리고 확장 모드의 budget_tokens)은 프롬프트에 렌더링되므로, 이를 변경하면 항상 메시지 블록이 무효화됩니다. 구성을 도구 및 시스템보다 앞에 렌더링하는 모델에서는 도구 및 시스템 캐시도 무효화됩니다. 사고와 프롬프트 캐싱을 참조하세요.
노력 수준 설정모델별 상이모델별 상이✘output_config.effort 값을 변경하면 항상 메시지 블록이 무효화되며, 도구 및 시스템 캐시에는 사고 매개변수와 동일한 모델별 영향이 있습니다. 노력 수준을 모델의 기본값으로 명시적으로 설정하는 것은 생략하는 것과 동일하며 무효화하지 않습니다. 메시지별 노력 수준을 지원하는 모델에서는 messages 내부의 role: "system" 메시지로 전달된 노력 수준 변경이 캐싱된 접두사를 그대로 유지합니다.
사고가 포함된 요청에 전달된 도구 결과가 아닌 콘텐츠✓✓모델별 상이Opus 4.5+, Sonnet 4.6+, Haiku 5.5에서는 사고 블록이 기본적으로 보존되므로 캐시가 유효하게 유지됩니다(✓). 이전 Opus/Sonnet 모델과 Claude Haiku 4.5까지의 Haiku 모델에서는 이전에 캐싱된 모든 사고 블록이 컨텍스트에서 제거되고, 해당 사고 블록 뒤에 오는 모든 메시지가 캐시에서 제거됩니다(✘). 자세한 내용은 사고 블록과 함께 캐싱하기를 참조하세요.
삭제된 사고 블록✓✓✘API가 해당 요청에서 보존되지 않는 Claude 5.1 이상 모델의 사고 블록을 삭제하면, 해당 요청에서 그 블록의 위치부터 캐싱된 접두사가 변경됩니다. 수신 모델이 읽을 수 있는 블록을 변경 없이 다시 전달하면 캐시가 그대로 유지됩니다.

대화 중 도구 변경을 지원하는 모델에서는 inline-tools-2026-09-15 베타 헤더를 사용하여 tools를 편집하지 않고도 대화 도중에 도구를 추가하거나 도구의 정의를 변경할 수 있습니다. 대화 중 시스템 메시지의 tool_addition 블록에 정의를 보내고 tools는 처음 보낸 그대로 두세요. 캐싱된 접두사가 여전히 일치하므로 추가된 메시지만 새 입력으로 처리됩니다. 유일한 예외는 지연되지 않은(non-deferred) 도구가 없는 tools 배열의 경우로, 이 방식으로 정의된 첫 번째 도구는 해당 요청에서 전체 캐시 미스 1회의 비용이 발생합니다. 메시지에서 도구 정의하기를 참조하세요.

캐시 성능 추적하기

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

  • cache_creation_input_tokens: 새 항목을 생성할 때 캐시에 쓰여진 토큰 수
  • cache_read_input_tokens: 이 요청에서 캐시로부터 검색된 토큰 수
  • input_tokens: 캐시에서 읽거나 캐시 생성에 사용되지 않은 입력 토큰 수(즉, 마지막 캐시 중단점 이후의 토큰)

사고 블록과 함께 캐싱하기

프롬프트 캐싱과 함께 사고를 사용할 때, 사고 블록에는 특별한 동작이 있습니다:

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

입력 토큰 계산: 사고 블록이 캐시에서 읽히면 사용량 지표에서 입력 토큰으로 계산됩니다. 이는 비용 계산과 토큰 예산 책정에 중요합니다.

캐시 무효화 패턴:

  • 도구 결과만 사용자 메시지로 제공되는 경우 캐시는 유효하게 유지됩니다.
  • Opus 4.5+, Sonnet 4.6+, Haiku 5.5에서는 도구 결과가 아닌 사용자 콘텐츠가 추가되더라도 사고 블록이 기본적으로 보존되므로 캐시가 유효하게 유지됩니다.
  • 이전 Opus/Sonnet 모델과 Claude Haiku 4.5까지의 Haiku 모델에서는 도구 결과가 아닌 사용자 콘텐츠가 추가되면 캐시가 무효화되어, 이전의 모든 사고 블록이 컨텍스트에서 제거됩니다.
  • 이러한 캐싱 동작은 명시적인 cache_control 마커가 없어도 발생합니다.

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

도구 사용 예시:

Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]

Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1

Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# Depending on the model, this non-tool-result user block either keeps prior thinking blocks or strips them (see the next paragraph)

이전 Opus/Sonnet 모델과 Claude Haiku 4.5까지의 Haiku 모델에서는 이 시점에서 이전의 모든 사고 블록이 컨텍스트에서 제거됩니다. Opus 4.5+, Sonnet 4.6+, Haiku 5.5에서는 이전 사고 블록이 기본적으로 유지되며 캐싱된 접두사의 일부로 남습니다.

자세한 내용은 사고와 프롬프트 캐싱을 참조하세요.

캐시 저장 및 공유

  • 조직 및 워크스페이스 격리: 캐시는 조직 간에 격리됩니다. 서로 다른 조직은 동일한 프롬프트를 사용하더라도 절대 캐시를 공유하지 않습니다. Claude API, Claude Platform on AWS, Microsoft Foundry에서는 캐시가 조직 내에서도 워크스페이스별로 격리되며, Claude Models on Google Cloud (Google managed) 및 Bedrock은 조직 수준의 격리만 사용합니다.

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

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

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

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

  • 멀티턴 대화에는 자동 캐싱으로 시작하세요. 중단점 관리를 자동으로 처리합니다.
  • 변경 빈도가 서로 다른 섹션을 캐싱해야 할 때는 명시적 블록 수준 중단점을 사용하세요.
  • 시스템 지침, 배경 정보, 대규모 컨텍스트, 자주 사용되는 도구 정의와 같이 안정적이고 재사용 가능한 콘텐츠를 캐싱하세요.
  • 최상의 성능을 위해 캐싱된 콘텐츠를 프롬프트의 시작 부분에 배치하세요.
  • 캐시 중단점을 전략적으로 사용하여 서로 다른 캐시 가능한 접두사 섹션을 분리하세요.
  • 요청 간에 동일하게 유지되는 마지막 블록에 중단점을 배치하세요. 정적 접두사와 변하는 접미사(타임스탬프, 요청별 컨텍스트, 들어오는 메시지)가 있는 프롬프트의 경우, 이는 변하는 블록이 아니라 접두사의 끝입니다.
  • 캐시 적중률을 정기적으로 분석하고 필요에 따라 전략을 조정하세요.

다양한 사용 사례에 맞게 최적화하기

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

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

일반적인 문제 해결

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

  • 캐싱된 섹션이 호출 간에 동일한지 확인하세요. 명시적 중단점의 경우, cache_control 마커가 동일한 위치에 있는지 확인하세요.
  • 호출이 캐시 수명(기본값 5분) 내에 이루어지는지 확인하세요.
  • tool_choice, 이미지 사용, 사고 구성, output_config.effort가 호출 간에 일관되게 유지되는지 확인하세요.
  • 모델과 플랫폼에 대한 최소 토큰 수 이상을 캐싱하고 있는지 검증하세요(캐시 제한 사항 참조).
  • 중단점이 요청 간에 동일하게 유지되는 블록에 있는지 확인하세요. 캐시 쓰기는 중단점에서만 발생하며, 해당 블록이 변경되면(타임스탬프, 요청별 컨텍스트, 들어오는 메시지) 접두사 해시가 절대 일치하지 않습니다. Lookback은 중단점 이전의 안정적인 콘텐츠를 찾지 않으며, 이전 요청이 자체 중단점에서 쓴 항목만 찾습니다.
  • 일부 언어(예: Swift, Go)는 JSON 변환 중에 키 순서를 무작위화하여 캐시를 깨뜨리므로, tool_use 콘텐츠 블록의 키가 안정적인 순서를 갖는지 확인하세요.
  • 캐시 진단을 사용하여 API가 연속된 요청을 비교하고 프롬프트의 어느 부분이 달라졌는지 보고하도록 하세요.

1시간 캐시 지속 시간

5분이 너무 짧다고 생각되면, Anthropic은 추가 비용으로 1시간 캐시 지속 시간도 제공합니다.

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

"cache_control": {
  "type": "ephemeral",
  "ttl": "1h"
}

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

Output
{
  "usage": {
    "input_tokens": 2048,
    "cache_read_input_tokens": 1800,
    "cache_creation_input_tokens": 248,
    "output_tokens": 503,

    "cache_creation": {
      "ephemeral_5m_input_tokens": 148,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

cache_creation_input_tokens 필드는 cache_creation 객체에 있는 값들의 합계와 같습니다.

웹 검색과 같은 서버 도구를 사용하는 동안 요청하지 않은 ephemeral_5m_input_tokens 쓰기가 보이는 경우, 서버 도구 결과는 자동으로 캐싱됩니다를 참조하세요.

1시간 캐시를 사용해야 하는 경우

정기적인 주기로 프롬프트를 사용하는 경우(예: 5분보다 더 자주 보내는 시스템 프롬프트), 추가 비용 없이 계속 갱신되므로 5분 캐시를 계속 사용하세요.

1시간 캐시는 다음 시나리오에서 가장 적합합니다:

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

서로 다른 TTL 혼합하기

동일한 요청에서 1시간 캐시 제어와 5분 캐시 제어를 함께 사용할 수 있지만, 중요한 제약 조건이 있습니다. TTL이 더 긴 캐시 항목은 TTL이 더 짧은 항목보다 앞에 나타나야 합니다(즉, 1시간 캐시 항목은 모든 5분 캐시 항목보다 앞에 나타나야 합니다).

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

  1. 위치 A: 프롬프트에서 마지막 캐시 적중 지점의 토큰 수(적중이 없으면 0).
    • 5분 TTL로 캐싱된 항목에 대한 적중은, 프롬프트에서 그 항목보다 뒤에 위치하며 TTL이 1시간인 cache_control 블록이 캐시 미스이면 적중으로 인정되지 않습니다.
    • 5분 TTL로 캐싱된 항목을 읽는 요청은, 이번 요청이 "ttl": "1h"를 설정하더라도 해당 항목의 5분 수명을 처음부터 다시 시작합니다.
  2. 위치 B: A보다 뒤에 위치하며 TTL이 1시간인 마지막 cache_control 블록 지점의 토큰 수(없으면 A와 같음).
  3. 위치 C: 마지막 cache_control 블록 지점의 토큰 수.

다음 항목에 대해 요금이 청구됩니다:

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

다음은 각각 서로 다른 캐시 적중과 캐시 미스를 가진 세 가지 예시 요청입니다. 각 요청은 상자에 표시된 것처럼 서로 다르게 계산된 가격을 갖습니다.

캐시 읽기
1h 캐시 쓰기
5m 캐시 쓰기
프롬프트의 나머지
1h 적중
(A)
1h 미스
1h 미스
1h 미스
(B)
5m 미스
(C)
1h 캐시 쓰기
5m 캐시 쓰기
프롬프트의 나머지
(A는 0)
1h 미스
1h 미스
1h 미스
1h 미스
(B)
5m 미스
(C)
캐시 읽기
프롬프트의 나머지
1h 미스
5m 적중
(A, B, C)

캐시 사전 워밍

“Cache pre-warming”(캐시 사전 워밍)을 사용하면 사용자가 실제 요청을 트리거하기 전에 시스템 프롬프트나 도구 정의를 프롬프트 캐시에 로드할 수 있습니다. 이를 통해 첫 번째 사용자 상호작용에서 발생하는 캐시 미스 지연 시간 페널티를 줄여, 지연 시간에 민감한 애플리케이션의 “time-to-first-token”(첫 토큰까지의 시간), 즉 TTFT를 낮출 수 있습니다.

작동 방식

요청에서 max_tokens: 0을 설정하세요. API는 프롬프트를 모델에 읽어 들이고 모든 cache_control 중단점에서 캐시를 기록한 다음, 출력을 생성하지 않고 즉시 반환합니다. 응답에는 빈 content 배열, stop_reason: "max_tokens", 그리고 완전히 채워진 usage 블록이 포함됩니다.

cache_control 중단점은 자리 표시자 사용자 메시지가 아니라 후속 요청과 공유되는 마지막 블록(일반적으로 시스템 프롬프트 또는 도구 정의)에 배치하세요. 그렇지 않으면 캐시 항목이 자리 표시자에 키가 지정되어 후속 요청이 이를 적중하지 못합니다. 또한 후속 요청과 동일한 사고 구성 및 output_config.effort를 사용하세요. 이 값들은 프롬프트에 렌더링되므로(캐시를 무효화하는 요소 참조), 다른 구성으로 사전 워밍을 하면 실제 트래픽이 절대 적중하지 않는 항목이 기록될 수 있습니다. 이는 자동 캐싱이 아닌 명시적 캐시 중단점을 사용해야 함을 의미합니다. 자동 캐싱은 중단점을 마지막 블록에 배치하는데, 여기서는 그것이 자리 표시자이기 때문입니다. 자리 표시자 사용자 메시지는 공백이 아닌 내용을 가진 어떤 문자열이든 될 수 있습니다(여기 예시에서는 "warmup"을 사용합니다). 그 내용은 모델에 읽혀지지만 응답되지는 않습니다.

client = anthropic.Anthropic()

# 사용자가 접속하기 전에 이 요청을 보내 공유 시스템 프롬프트 캐시를 미리 준비하세요.
prewarm = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=0,
    system=[
        {
            "type": "text",
            "text": "You are an expert software engineer with deep knowledge of distributed systems...",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "warmup"}],
)
print(prewarm.stop_reason)  # "max_tokens"
print(prewarm.content)  # []
print(prewarm.usage)

API는 빈 content 배열을 반환합니다:

Output
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [],
  "model": "claude-opus-5-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 8,
    "cache_creation_input_tokens": 5120,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 5120,
      "ephemeral_1h_input_tokens": 0
    },
    "iterations": [
      {
        "input_tokens": 8,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 5120,
        "cache_creation": {
          "ephemeral_5m_input_tokens": 5120,
          "ephemeral_1h_input_tokens": 0
        },
        "type": "message"
      }
    ],
    "output_tokens": 0,
    "service_tier": "standard",
    "inference_geo": "global"
  }
}

일반적인 사용 패턴

애플리케이션이 시작될 때(또는 예약된 간격으로) 사전 워밍 요청을 보낸 다음, 사전 워밍이 완료된 후 실제 사용자 요청을 보내세요:

client = anthropic.Anthropic()

SYSTEM_PROMPT = [
    {
        "type": "text",
        "text": "You are an expert software engineer with deep knowledge of distributed systems...",
        "cache_control": {"type": "ephemeral"},
    }
]


def prewarm_cache() -> None:
    """Call this at application startup or on a scheduled interval."""
    client.messages.create(
        model="claude-opus-5-5",
        max_tokens=0,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": "warmup"}],
    )


def respond(user_message: str) -> anthropic.types.Message:
    """The real user request; benefits from a warm cache."""
    return client.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


# 사용자 트래픽이 도착하기 전에 캐시를 미리 준비합니다.
prewarm_cache()

# 이후 사용자가 메시지를 제출하면 시스템 프롬프트 접두사는 이미 캐시되어 있습니다.
response = respond("How do I implement a binary search tree?")
for block in response.content:
    if block.type == "text":
        print(block.text)

캐시 TTL은 여전히 적용된다는 점을 유념하세요. 기본 5분 캐시의 경우, 캐시를 따뜻하게 유지하려면 최소 5분마다 새로운 사전 워밍 요청을 보내세요. 사용자 요청 사이의 간격이 더 긴 경우에는 대신 1시간 캐시 지속 시간을 사용하세요.

제한 사항

다음 중 하나라도 설정된 경우 max_tokens: 0 요청은 invalid_request_error와 함께 거부됩니다. 각각은 토큰 예산이 0인 상태에서는 생성할 수 없는 출력을 의미하기 때문입니다:

max_tokens: 0은 Message Batches 요청 내에서도 거부됩니다. 사전 워밍은 첫 토큰까지의 시간을 목표로 하는데, 이는 배치 처리에는 적용되지 않으며, 배치 처리 중에 기록된 캐시 항목은 후속 요청이 실행되기 전에 만료될 가능성이 높습니다.

max_tokens=1 우회 방법 대체하기

일부 애플리케이션은 캐시를 워밍하기 위해 max_tokens: 1 요청을 보냅니다. 요청이 허용하는 경우 max_tokens: 0을 사용하는 것이 좋습니다. 출력이 생성되지 않으므로 버려야 할 단일 토큰 응답이 없고, 출력 토큰이 청구되지 않으며, 요청의 의도가 명확합니다.

프롬프트 캐싱 예시

프롬프트 캐싱을 시작하는 데 도움이 되도록, Claude Cookbook의 프롬프트 캐싱 레시피에서 자세한 예시와 모범 사례를 제공합니다.

다음 코드 스니펫은 다양한 프롬프트 캐싱 패턴을 보여줍니다. 이 예시들은 다양한 시나리오에서 캐싱을 구현하는 방법을 보여주어 이 기능의 실제 활용 방식을 이해하는 데 도움을 줍니다:

데이터 보존

프롬프트 캐싱(자동 및 명시적 모두)은 “zero data retention”(제로 데이터 보존), 즉 ZDR 적용 대상입니다. Anthropic은 프롬프트나 Claude 응답의 원시 텍스트를 저장하지 않습니다.

캐시된 콘텐츠의 KV(키-값) 캐시 표현과 암호화 해시는 메모리에만 보관되며 저장 상태로 보관되지 않습니다. 캐시된 항목의 최소 수명은 5분(표준) 또는 1시간(확장)이며, 그 후에는 즉시는 아니지만 신속하게 삭제됩니다. 캐시 항목은 조직 간에 격리되며, Claude API, Claude Platform on AWS, Microsoft Foundry에서는 조직 내 워크스페이스 간에도 격리됩니다.

FAQ

제공 여부

프롬프트 캐싱은(는) API에 따라 사용 가능 또는 베타 상태이며 제로 데이터 보존 및 HIPAA 대비에 적격합니다.

API 지원

Messages API

사용법

최상위 수준 또는 블록에서 cache_control로 사용을 선택하세요.

상태사용 가능
클라우드 플랫폼
  • 지원되는 모든 플랫폼
모델
Managed Agents

사용법

항상 활성화

캐시 항목은 기본적으로 5분 수명을 사용하며, 캐시 읽기와 쓰기는 세션 사용량에 표시됩니다.

상태베타
클라우드 플랫폼
  • 지원되는 모든 플랫폼
모델

데이터 처리

데이터 처리 개요

적용 엔드포인트

  • /v1/messages
제로 데이터 보존적격

적용 모델 제외

프롬프트와 Claude의 출력은 저장되지 않습니다. KV 캐시 표현과 암호화 해시는 캐시 TTL 동안 메모리에 보관되며 만료 후 즉시 삭제됩니다. 자세히 알아보기

HIPAA적격

이 페이지가 도움이 되었나요?