프롬프트 캐싱

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

프롬프트 캐싱을 활성화하는 두 가지 방법이 있습니다:

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

시작하는 가장 간단한 방법은 자동 캐싱입니다:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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분입니다. 캐시된 콘텐츠를 사용할 때마다 추가 비용 없이 캐시가 새로 고쳐집니다.

가격 책정

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

지원되는 모델

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

자동 캐싱

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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())

다중 턴 대화에서 자동 캐싱의 작동 원리

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

캐시 중단점은 각 요청의 마지막 캐시 가능 블록으로 자동으로 이동하므로 대화가 증가함에 따라 cache_control 마커를 업데이트할 필요가 없습니다.

TTL 지원

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

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

블록 수준 캐싱과 결합

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

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

{
  "model": "claude-opus-4-7",
  "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블록 룩백 윈도우는 모두 명시적 중단점과 동일하게 적용됩니다.

엣지 케이스

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

명시적 캐시 중단점

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

프롬프트 구조화

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

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

자동 접두사 확인의 작동 원리

정적 콘텐츠의 끝에 하나의 캐시 중단점만 사용할 수 있으며 시스템은 이전 요청이 이미 캐시에 기록한 가장 긴 접두사를 자동으로 찾습니다. 이것이 어떻게 작동하는지 이해하면 캐싱 전략을 최적화하는 데 도움이 됩니다.

세 가지 핵심 원칙:

1. 캐시 쓰기는 중단점에서만 발생합니다. 블록을 cache_control로 표시하면 정확히 하나의 캐시 항목이 기록됩니다: 해당 블록에서 끝나는 접두사의 해시입니다. 시스템은 이전 위치에 항목을 기록하지 않습니다. 해시는 누적되어 중단점까지의 모든 것을 포함하므로 중단점에서 또는 그 이전의 블록을 변경하면 다음 요청에서 다른 해시가 생성됩니다.

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

3. 룩백 윈도우는 20블록입니다. 시스템은 중단점당 최대 20개 위치를 확인하며 중단점 자체를 첫 번째로 계산합니다. 시스템이 해당 윈도우에서 일치하는 항목을 찾지 못하면 확인이 중지됩니다(또는 다른 명시적 중단점이 있으면 그곳에서 재개됨).

예제: 증가하는 대화에서의 룩백

각 턴에 새 블록을 추가하고 각 요청의 최종 블록에 cache_control을 설정합니다:

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

일반적인 실수: 모든 요청에서 변경되는 콘텐츠의 중단점

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

• 요청 1: 블록 6에 캐시 쓰기. 해시에는 타임스탬프가 포함됩니다.
• 요청 2: 타임스탬프가 다르므로 블록 6의 접두사 해시가 다릅니다. 룩백은 블록 5, 4, 3, 2, 1을 통과하지만 시스템은 이러한 위치 중 어디에도 항목을 기록하지 않았습니다. 캐시 히트가 없습니다. 모든 요청에서 새 캐시 쓰기 비용을 지불하고 읽기를 받지 못합니다.

룩백은 중단점 뒤의 안정적인 콘텐츠를 찾아서 캐시하지 않습니다. 이전 요청이 이미 기록한 항목을 찾으며 쓰기는 중단점에서만 발생합니다. cache_control을 블록 5(요청 간에 동일하게 유지되는 마지막 블록)로 이동하면 모든 후속 요청이 캐시된 접두사를 읽습니다. 자동 캐싱은 동일한 함정에 빠집니다: 중단점을 마지막 캐시 가능 블록에 배치하는데, 이 구조에서는 모든 요청에서 변경되는 블록이므로 대신 블록 5에 명시적 중단점을 사용합니다.

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

여러 중단점을 사용할 때

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

• 다양한 빈도로 변경되는 다양한 섹션을 캐시합니다(예: 도구는 거의 변경되지 않지만 컨텍스트는 매일 업데이트됨).
• 정확히 무엇을 캐시할지에 대한 더 많은 제어를 가집니다.
• 증가하는 대화가 마지막 캐시 쓰기를 20개 이상의 블록 과거로 밀어낼 때 캐시 히트를 보장합니다.

캐시 중단점 비용 이해

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

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

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

캐싱 전략 및 고려 사항

캐시 제한

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

• Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, Claude Opus 4.5의 경우 4096토큰
• Claude Sonnet 4.6의 경우 2048토큰
• Claude Sonnet 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7(deprecated)의 경우 1024토큰
• Claude Haiku 4.5의 경우 4096토큰
• Claude Haiku 3.5(deprecated) 및 Claude Haiku 3의 경우 2048토큰

더 짧은 프롬프트는 cache_control로 표시되어 있어도 캐시할 수 없습니다. 이 토큰 수보다 적게 캐시하려는 모든 요청은 캐싱 없이 처리되며 오류가 반환되지 않습니다. 프롬프트가 캐시되었는지 확인하려면 응답 사용 필드를 확인합니다: 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. 각 수준의 변경 사항은 해당 수준과 모든 후속 수준을 무효화합니다.

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

캐시 성능 추적

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

• cache_creation_input_tokens: 새 항목을 생성할 때 캐시에 기록된 토큰 수입니다.
• cache_read_input_tokens: 이 요청에 대해 캐시에서 검색된 토큰 수입니다.
• input_tokens: 캐시에서 읽거나 캐시를 생성하는 데 사용되지 않은 입력 토큰 수입니다(즉, 마지막 캐시 중단점 이후의 토큰).

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

사고 블록을 사용한 캐싱

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

다른 콘텐츠와 함께 자동 캐싱: 사고 블록은 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],
사용자: [텍스트 응답, cache=True]
# 도구 결과가 아닌 사용자 블록은 새로운 어시스턴트 루프를 지정하고 모든 이전 사고 블록이 제거됩니다
# 이 요청은 사고 블록이 존재하지 않았던 것처럼 처리됩니다

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

자세한 내용은 확장 사고 문서를 참조하세요.

캐시 저장 및 공유

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

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

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

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

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

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

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

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

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

일반적인 문제 해결

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

• 캐시된 섹션이 호출 전체에서 동일한지 확인하세요. 명시적 중단점의 경우 cache_control 마커가 동일한 위치에 있는지 확인하세요
• 호출이 캐시 수명(기본값 5분) 내에 이루어지는지 확인하세요
• tool_choice 및 이미지 사용이 호출 간에 일관성이 있는지 확인하세요
• 사용 중인 모델에 대해 최소 토큰 수를 캐싱하고 있는지 확인하세요(캐시 제한 참조). 길이 기반 캐싱 실패는 자동으로 처리됩니다: 요청은 성공하지만 cache_creation_input_tokens 및 cache_read_input_tokens 모두 0이 됩니다
• 중단점이 요청 전체에서 동일하게 유지되는 블록에 있는지 확인하세요. 캐시 쓰기는 중단점에서만 발생하며, 해당 블록이 변경되면(타임스탬프, 요청별 컨텍스트, 들어오는 메시지), 접두사 해시가 일치하지 않습니다. 룩백은 중단점 뒤의 안정적인 콘텐츠를 찾지 않습니다. 이전 요청이 자신의 중단점에서 작성한 항목만 찾습니다
• tool_use 콘텐츠 블록의 키가 안정적인 순서를 가지고 있는지 확인하세요. 일부 언어(예: Swift, Go)는 JSON 변환 중에 키 순서를 무작위로 지정하여 캐시를 손상시킵니다

1시간 캐시 지속 시간

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

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

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

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

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

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

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

1시간 캐시를 사용할 때

정기적인 주기로 사용되는 프롬프트가 있다면(즉, 5분마다 더 자주 사용되는 시스템 프롬프트), 5분 캐시를 계속 사용하세요. 이는 추가 비용 없이 계속 새로 고쳐집니다.

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

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

다양한 TTL 혼합

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

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

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

청구 대상:

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

다음은 3가지 예제입니다. 이는 각각 다양한 캐시 히트 및 캐시 미스를 가진 3개의 요청의 입력 토큰을 나타냅니다. 각각은 색상이 지정된 상자에 표시된 다양한 계산된 가격을 가집니다.

프롬프트 캐싱 예제

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

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

데이터 보관

프롬프트 캐싱(자동 및 명시적 모두)은 ZDR 적격입니다. Anthropic은 프롬프트의 원본 텍스트나 Claude의 응답을 저장하지 않습니다.

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

ZDR 적격성을 모든 기능에 걸쳐 확인하려면 API 및 데이터 보관을 참조하세요.

FAQ