Prompt Caching

API 요청 시 프롬프트의 반복되는 접두사(prefix)를 캐싱하여 처리 시간과 비용을 줄이는 기능. 같은 내용을 반복 전송할 때 전체를 다시 처리하지 않고 캐시된 부분을 재사용한다.

해당 개념이 필요한 이유

• 비용 절감: 캐시 히트 시 해당 토큰의 비용이 기본 입력 비용의 **10%**로 줄어듦 (90% 절감)
• 응답 속도 향상: 캐시된 프롬프트는 재처리가 불필요하여 time-to-first-token이 개선됨
• 반복 작업에 최적: system prompt, tool 정의, 긴 문서 컨텍스트 등 매 요청마다 동일한 내용을 보내는 경우에 효과적

AS-IS

sequenceDiagram
    autonumber
    participant Client as API Client
    participant API as Claude API

    Client->>API: 요청 1: System(10만 토큰) + User("Mars 설명해줘")
    Note over API: 10만 토큰 전체 처리
    API-->>Client: 응답

    Client->>API: 요청 2: System(10만 토큰) + User("Jupiter 설명해줘")
    Note over API: 10만 토큰 전체 다시 처리
    API-->>Client: 응답

    Note over Client,API: 매 요청마다 동일한 System 10만 토큰을<br/>반복 처리 → 비용 + 지연시간 낭비

TO-BE

sequenceDiagram
    autonumber
    participant Client as API Client
    participant Cache as Prompt Cache
    participant API as Claude API

    Client->>API: 요청 1: System(10만 토큰, cache_control) + User("Mars 설명해줘")
    API->>Cache: System 10만 토큰 캐시 저장 (cache write)
    Note over API: 전체 처리 (최초 1회)
    API-->>Client: 응답

    Client->>API: 요청 2: System(10만 토큰, cache_control) + User("Jupiter 설명해줘")
    API->>Cache: 캐시 확인 → 히트!
    Note over API: System 10만 토큰은 캐시에서 읽기 (10% 비용)<br/>User 메시지만 새로 처리
    API-->>Client: 응답

    Note over Client,API: 10만 토큰 × $3/MTok = $0.30 → $0.03로 절감 (Sonnet 기준)

동작 원리

1. cache_control 파라미터가 포함된 요청을 보냄
2. 시스템이 해당 프롬프트 접두사(prefix)가 이미 캐시에 있는지 확인
3. 캐시 히트: 캐시된 버전을 재사용 → 비용 절감 + 속도 향상
4. 캐시 미스: 전체 프롬프트를 처리하고, 응답 시작 시 접두사를 캐시에 저장

캐시는 접두사 기반이다. tools → system → messages 순서로 처음부터 cache_control 지점까지의 모든 내용이 캐시 단위가 된다.

비용 구조

	기본 입력	5분 캐시 Write	1시간 캐시 Write	캐시 Hit (Read)
배율	1x	1.25x	2x	0.1x
Sonnet 기준	$3/MTok	$3.75/MTok	$6/MTok	$0.30/MTok
Haiku 기준	$1/MTok	$1.25/MTok	$2/MTok	$0.10/MTok

• 첫 요청: cache write 비용 발생 (기본의 1.25배)
• 이후 요청: cache hit 시 기본의 10% 비용만 발생
• 캐시 갱신: 캐시된 내용을 사용할 때마다 TTL이 무료로 갱신됨

캐시 수명 (TTL)

TTL	비용	용도
5분 (기본)	1.25x write	빈번한 요청 (5분 이내 반복)
1시간	2x write	간헐적 요청 (5분~1시간 간격)

캐시는 사용할 때마다 무료로 갱신된다. 5분 TTL 캐시를 4분마다 사용하면 영원히 유지.

2가지 캐싱 방법

1. Automatic Caching (권장, 간단)

요청 body의 최상위에 cache_control을 추가. 시스템이 마지막 캐시 가능 블록에 자동으로 breakpoint를 설정한다:

{
  "model": "claude-opus-4-6",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": "You are a helpful assistant.",
  "messages": [...]
}

멀티턴 대화에서 캐시 포인트가 자동으로 이동:

요청	캐시 동작
요청 1: System + User:A + Asst:B + User:C	전체 캐시 저장
요청 2: … + Asst:D + User:E	System~User:C는 캐시 읽기, Asst:D+User:E는 새로 저장
요청 3: … + Asst:F + User:G	System~User:E는 캐시 읽기, Asst:F+User:G는 새로 저장

2. Explicit Cache Breakpoints (세밀한 제어)

개별 content block에 cache_control을 직접 배치. 최대 4개 breakpoint 사용 가능:

{
  "tools": [
    {"name": "search", "...", "cache_control": {"type": "ephemeral"}}
  ],
  "system": [
    {"type": "text", "text": "지침...", "cache_control": {"type": "ephemeral"}},
    {"type": "text", "text": "문서...", "cache_control": {"type": "ephemeral"}}
  ],
  "messages": [
    {"role": "user", "content": [
      {"type": "text", "text": "질문", "cache_control": {"type": "ephemeral"}}
    ]}
  ]
}

변경 빈도가 다른 섹션을 독립적으로 캐싱할 때 유용:

• Breakpoint 1: Tool 정의 (거의 안 변함)
• Breakpoint 2: System 지침 (거의 안 변함)
• Breakpoint 3: RAG 문서 (매일 변경)
• Breakpoint 4: 대화 히스토리 (매 턴 변경)

캐시 무효화 조건

캐시는 tools → system → messages 계층 구조를 따른다. 상위 레벨 변경 시 하위 레벨 캐시도 무효화된다:

변경 사항	Tools 캐시	System 캐시	Messages 캐시
Tool 정의 변경	무효	무효	무효
Web search 토글	유지	무효	무효
Tool choice 변경	유지	유지	무효
이미지 추가/제거	유지	유지	무효

최소 캐시 토큰 수

모델별로 캐싱 가능한 최소 토큰 수가 다르다. 이보다 짧으면 cache_control을 설정해도 캐싱되지 않는다:

모델	최소 토큰
Claude Opus 4.6 / 4.5	4,096
Claude Sonnet 4.6 / 4.5 / 4.1 / 4	1,024
Claude Haiku 4.5	4,096
Claude Haiku 3.5 / 3	2,048

Claude Code에서의 Prompt Caching

Claude Code는 모든 배포 옵션(Anthropic 직접, Bedrock, Vertex AI, Foundry)에서 Prompt Caching이 기본 활성화되어 있다.

• 별도 설정 불필요 (기본 활성화)
• 비활성화가 필요한 경우: export DISABLE_PROMPT_CACHING=1
• 일부 리전에서 사용 불가능할 수 있음

참고 문서

• Anthropic Prompt Caching
• Prompt Caching Cookbook
• Anthropic Pricing