프롬프트 캐싱

프롬프트 캐싱은 프롬프트의 특정 프리픽스(prefix)부터 재개할 수 있도록 하여 API 사용을 최적화합니다. 이를 통해 반복적인 작업이나 일관된 요소를 포함한 프롬프트에서 처리 시간과 비용을 크게 줄일 수 있습니다.

이 기능은 Zero Data Retention(ZDR) 대상입니다. 조직에 ZDR 계약이 적용되어 있다면, 이 기능을 통해 전송된 데이터는 API 응답이 반환된 후 저장되지 않습니다.

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

• 자동 캐싱(Automatic caching): 요청의 최상위 레벨에 cache_control 필드를 하나만 추가합니다. 시스템이 자동으로 마지막 캐시 가능 블록에 캐시 브레이크포인트(breakpoint)를 적용하고, 대화가 길어질수록 브레이크포인트를 앞으로 이동시킵니다. 늘어나는 메시지 기록을 자동으로 캐시하고자 하는 멀티턴 대화에 가장 적합합니다.
• 명시적 캐시 브레이크포인트(Explicit cache breakpoints): 개별 콘텐츠 블록에 cache_control을 직접 지정하여, 무엇을 캐시할지 정밀하게 제어합니다.

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

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-8",
    "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."
      }
    ]
  }'

client = anthropic.Anthropic()

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

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-opus-4-8",
  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'."
    }
  ]
});
console.log(response.usage);

자동 캐싱을 사용하면 시스템이 마지막 캐시 가능 블록까지의 모든 콘텐츠를 캐시합니다. 동일한 프리픽스를 사용하는 이후 요청에서는 캐시된 콘텐츠가 자동으로 재사용됩니다.

프롬프트 캐싱의 동작 방식

프롬프트 캐싱이 활성화된 요청을 보내면 다음과 같이 처리됩니다.

1. 시스템은 지정된 캐시 브레이크포인트까지의 프롬프트 프리픽스가 최근 쿼리에서 이미 캐시되어 있는지 확인합니다.
2. 캐시된 프리픽스가 있으면 캐시된 버전을 사용하여 처리 시간과 비용을 줄입니다.
3. 없으면 전체 프롬프트를 처리하고, 응답이 시작되는 시점에 프리픽스를 캐시합니다.

이 기능은 특히 다음과 같은 경우에 유용합니다.

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

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

5분이 너무 짧다면 Anthropic은 추가 비용으로 1시간 캐시 수명도 제공합니다. 자세한 내용은 1시간 캐시 수명 문서를 참고하세요.

프롬프트 캐싱은 전체 프리픽스를 캐시합니다

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

가격

프롬프트 캐싱에는 새로운 가격 체계가 적용됩니다. 아래 표는 지원되는 각 모델의 100만 토큰당 가격을 보여줍니다.

위 표에는 프롬프트 캐싱에 적용되는 다음과 같은 가격 배수가 반영되어 있습니다.

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

이 배수는 Batch API 할인이나 데이터 레지던시(data residency) 같은 다른 가격 조정 요소와 중첩 적용됩니다. 자세한 내용은 가격 문서를 참고하세요.

지원 모델

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

자동 캐싱

자동 캐싱은 프롬프트 캐싱을 활성화하는 가장 간단한 방법입니다. 개별 콘텐츠 블록에 cache_control을 지정하는 대신, 요청 본문의 최상위 레벨에 cache_control 필드를 하나만 추가합니다. 그러면 시스템이 마지막 캐시 가능 블록에 자동으로 캐시 브레이크포인트를 적용합니다.

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-8",
    "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?"}
    ]
  }'

client = anthropic.Anthropic()

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

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-opus-4-8",
  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?" }
  ]
});
console.log(response.usage);

멀티턴 대화에서 자동 캐싱이 동작하는 방식

자동 캐싱에서는 대화가 길어질수록 캐시 지점이 자동으로 앞으로 이동합니다. 새 요청마다 마지막 캐시 가능 블록까지의 모든 내용을 캐시하고, 이전 콘텐츠는 캐시에서 읽어 옵니다.

캐시 브레이크포인트가 각 요청의 마지막 캐시 가능 블록으로 자동 이동하므로, 대화가 길어져도 cache_control 마커를 직접 갱신할 필요가 없습니다.

TTL 지원

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

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

블록 단위 캐싱과 함께 사용하기

자동 캐싱은 명시적 캐시 브레이크포인트와 호환됩니다. 두 방식을 함께 사용하면 자동 캐시 브레이크포인트가 사용 가능한 4개 브레이크포인트 슬롯 중 하나를 차지합니다.

이를 통해 두 방식을 결합할 수 있습니다. 예를 들어 명시적 브레이크포인트로 시스템 프롬프트를 캐시하면서, 대화 부분은 자동 캐싱이 처리하도록 할 수 있습니다.

{
  "model": "claude-opus-4-8",
  "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이 있으면, 자동 캐싱은 아무 동작도 하지 않습니다(no-op).
• 마지막 블록에 다른 TTL의 명시적 cache_control이 있으면, API가 400 오류를 반환합니다.
• 이미 4개의 명시적 블록 단위 브레이크포인트가 존재하면(자동 캐싱에 쓸 슬롯이 없으므로), API가 400 오류를 반환합니다.
• 마지막 블록이 자동 캐시 브레이크포인트 대상으로 부적격이면, 시스템이 뒤로 거슬러 올라가며 가장 가까운 적격 블록을 찾습니다. 찾지 못하면 캐싱을 건너뜁니다.

자동 캐싱은 Claude API, AWS의 Claude Platform, Microsoft Foundry(베타)에서 사용할 수 있습니다. Bedrock과 Google Cloud는 자동 캐싱을 지원하지 않습니다.

명시적 캐시 브레이크포인트

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

프롬프트 구조화하기

정적인 콘텐츠(도구 정의, 시스템 지침, 컨텍스트, 예시)를 프롬프트의 앞부분에 배치하세요. 그리고 캐싱할 재사용 콘텐츠의 끝을 cache_control 파라미터로 표시합니다.

캐시 프리픽스는 tools, system, messages 순서로 생성됩니다. 이 순서는 각 레벨이 이전 레벨 위에 쌓이는 계층 구조를 형성합니다.

자동 프리픽스 확인이 동작하는 방식

정적 콘텐츠의 끝에 캐시 브레이크포인트를 하나만 두면, 시스템이 이전 요청이 이미 캐시에 기록한 가장 긴 프리픽스를 자동으로 찾아냅니다. 이 동작 방식을 이해하면 캐싱 전략을 최적화하는 데 도움이 됩니다.

핵심 원칙은 세 가지입니다.

1. 캐시 쓰기는 브레이크포인트에서만 일어납니다. 어떤 블록에 cache_control을 표시하면 정확히 하나의 캐시 엔트리, 즉 그 블록에서 끝나는 프리픽스의 해시(hash)가 기록됩니다. 시스템은 그보다 앞선 어떤 위치에도 엔트리를 기록하지 않습니다. 이 해시는 브레이크포인트까지의 모든 내용을 포함하는 누적 해시이므로, 브레이크포인트 또는 그 이전의 블록을 하나라도 변경하면 다음 요청에서 다른 해시가 생성됩니다.
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)를 확인하지만 아무것도 찾지 못합니다. 블록 15의 턴 2 엔트리는 윈도 밖으로 한 칸 벗어나 있어 캐시 히트가 없습니다. 블록 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블록 이상 뒤로 밀려난 상황에서도 캐시 히트를 보장하려는 경우

중요한 제약: 룩백은 이전 요청이 이미 기록한 엔트리만 찾을 수 있습니다. 길어지는 대화로 인해 브레이크포인트가 마지막 쓰기보다 20블록 이상 밀려나면 룩백 윈도가 이를 놓칩니다. 처음부터 해당 위치에 가까운 곳에 두 번째 브레이크포인트를 추가하여, 필요해지기 전에 그 지점에 쓰기가 쌓이도록 하세요.

캐시 브레이크포인트 비용 이해하기

캐시 브레이크포인트 자체에는 비용이 추가되지 않습니다. 비용이 청구되는 항목은 다음뿐입니다.

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

cache_control 브레이크포인트를 더 추가해도 비용이 늘어나지 않습니다. 실제로 캐시되고 읽힌 콘텐츠를 기준으로 동일한 금액을 지불합니다. 브레이크포인트는 단지 어떤 섹션을 독립적으로 캐시할 수 있는지를 제어할 뿐입니다.

캐싱 전략과 고려사항

캐시 제약

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

• Claude Fable 5 및 Claude Mythos 5: 512 토큰
• Claude Mythos Preview 및 Claude Opus 4.7: 2,048 토큰
• Claude Opus 4.6 및 Claude Opus 4.5: 4,096 토큰
• Claude Opus 4.8, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Opus 4.1(지원 중단 예정), Claude Opus 4(지원 종료, Google Cloud 제외), Claude Sonnet 4(지원 종료, Bedrock·Google Cloud 제외): 1,024 토큰
• Claude Haiku 4.5: 4,096 토큰
• Claude Haiku 3.5(지원 종료, Google Cloud 제외): 2,048 토큰

모델 가용성은 플랫폼마다 다르며, 새로 출시된 모델의 최소 길이 역시 다를 수 있습니다. 예를 들어 Amazon Bedrock에서 Claude Fable 5와 Claude Mythos 5의 캐시 가능 최소 프롬프트 길이는 1,024 토큰입니다.

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

프롬프트가 해당 모델·플랫폼의 최소 길이에 약간 못 미친다면, 캐시 콘텐츠를 늘려 임계값을 채우는 것이 대개 이득입니다. 캐시 읽기는 캐시되지 않은 입력 토큰보다 훨씬 저렴하므로, 최소 길이에 도달하면 자주 재사용되는 프롬프트의 비용을 줄일 수 있습니다.

Bedrock은 AWS가 운영하는 플랫폼입니다. Bedrock에서의 모델별 최소 길이, 실패 동작, usage 필드 이름은 Bedrock 프롬프트 캐싱 문서를 참고하세요.

동시 요청의 경우, 캐시 엔트리는 첫 응답이 시작된 후에야 사용 가능해진다는 점에 유의하세요. 병렬 요청에서 캐시 히트가 필요하다면, 첫 응답을 기다린 뒤 이후 요청을 보내세요.

현재 지원되는 캐시 타입은 "ephemeral"뿐이며, 기본 수명은 5분입니다.

캐시할 수 있는 항목

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

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

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

캐시할 수 없는 항목

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

• 사고(thinking) 블록은 cache_control로 직접 캐시할 수 없습니다. 다만 이전 assistant 턴에 나타날 때는 다른 콘텐츠와 함께 캐시될 수 있습니다. 이렇게 캐시된 경우, 캐시에서 읽을 때 입력 토큰으로 계산됩니다.

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

  인용의 경우, 인용의 원본이 되는 최상위 문서 콘텐츠 블록은 캐시할 수 있습니다. 따라서 인용이 참조할 문서를 캐시하면 프롬프트 캐싱을 인용과 함께 효과적으로 사용할 수 있습니다.

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

캐시를 무효화하는 요인

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

프롬프트 구조화하기에서 설명했듯이, 캐시는 tools → system → messages 계층을 따릅니다. 각 레벨의 변경은 해당 레벨과 그 이후의 모든 레벨을 무효화합니다.

다음 표는 변경 유형에 따라 캐시의 어떤 부분이 무효화되는지를 보여줍니다. ✘는 캐시가 무효화됨을, ✓는 캐시가 유효하게 유지됨을 의미합니다.

Claude Opus 4.8에서는 대화 도중에 새 시스템 지침을 추가해도 시스템 캐시나 메시지 캐시가 무효화되지 않습니다. 최상위 system 필드를 수정하는 대신 messages에 {"role": "system"} 메시지를 추가하면, 캐시된 프리픽스가 그대로 유지됩니다. 자세한 내용은 대화 중간 시스템 메시지 문서를 참고하세요.

캐시 성능 추적

다음 API 응답 필드로 캐시 성능을 모니터링할 수 있습니다. 이 필드들은 응답의 usage 안에 있습니다(스트리밍 시에는 message_start 이벤트).

• cache_creation_input_tokens: 새 엔트리를 생성할 때 캐시에 기록된 토큰 수
• cache_read_input_tokens: 이번 요청에서 캐시에서 가져온 토큰 수
• input_tokens: 캐시에서 읽지도, 캐시 생성에 쓰이지도 않은 입력 토큰 수