Claude 프롬프트 캐싱 완전 가이드: API 비용 90% 절감하기

프롬프트 캐싱(Prompt Caching)이란 시스템 프롬프트나 대용량 문서를 Anthropic 서버에 저장해 두고, 동일 콘텐츠가 반복 사용될 때 90% 할인된 요금으로 재사용하는 기능이다. 캐시 읽기 단가는 Claude 3.5 Haiku 기준 $0.08/100만 토큰으로, 기본 입력 단가($0.80/M)의 10분의 1이다. 시스템 프롬프트가 길고 호출 빈도가 높은 서비스라면 단 1.28회 캐시 히트만으로 손익분기점을 넘는다. RAG 파이프라인, 긴 시스템 프롬프트, 멀티턴 대화 모두에 적용 가능하며, API 호출 코드에 cache_control: {"type": "ephemeral"} 한 줄을 추가하는 것으로 즉시 활성화된다.

프롬프트 캐싱 동작 방식

캐싱은 두 단계로 작동한다.

1단계 — 캐시 쓰기 (Cache Write) 최초 API 호출 시 cache_control이 붙은 콘텐츠 블록을 Anthropic 서버가 저장한다. 이때 비용은 일반 입력 단가의 1.25배다. 즉, 처음 한 번은 약간 더 비싸게 처리되지만 이후 모든 재사용에서 비용이 급감한다.

2단계 — 캐시 읽기 (Cache Read) 5분 이내에 동일한 캐시 블록을 포함한 요청이 들어오면 서버가 저장된 처리 결과를 그대로 반환한다. 재처리 없이 캐시에서 읽으므로 비용이 90% 절감된다. 캐시 히트가 발생할 때마다 TTL이 5분 리셋된다.

첫 번째 호출:  [시스템 프롬프트 10,000토큰] → 캐시 저장 (쓰기 요금 적용)
두 번째 호출:  [동일 시스템 프롬프트]       → 캐시에서 읽기 (90% 할인)
세 번째 호출:  [동일 시스템 프롬프트]       → 캐시에서 읽기 (90% 할인)
...
5분 후 미사용: 캐시 만료 → 다음 호출에서 재저장

캐싱이 적용되는 대상은 다음과 같다:

시스템 프롬프트 — 긴 지침, 페르소나, 도메인 지식
대용량 문서 — RAG에서 검색된 문서 덩어리, PDF 내용
대화 히스토리 — 멀티턴 세션의 누적된 맥락

API 사용법: cache_control 설정

cache_control: {"type": "ephemeral"} 속성을 콘텐츠 블록에 추가하면 된다. 현재 지원되는 유일한 타입은 "ephemeral"이다.

기본 시스템 프롬프트 캐싱

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-haiku-3-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": """당신은 전문 법률 자문 AI입니다.
            
다음 지침을 항상 따르십시오:
1. 한국 법률 기준으로 답변합니다.
2. 불확실한 사항은 반드시 전문가 상담을 권고합니다.
3. 답변은 명확하고 간결하게 유지합니다.

[여기에 수천 토큰 분량의 법률 도메인 지식...]
""",
            "cache_control": {"type": "ephemeral"}  # 이 블록을 캐시에 저장
        }
    ],
    messages=[
        {"role": "user", "content": "근로계약서 작성 시 필수 항목은 무엇인가요?"}
    ]
)

# 캐시 사용 여부 확인
usage = response.usage
print(f"캐시 생성 토큰: {usage.cache_creation_input_tokens}")  # 첫 호출: 양수
print(f"캐시 읽기 토큰: {usage.cache_read_input_tokens}")      # 이후 호출: 양수
print(f"일반 입력 토큰: {usage.input_tokens}")

RAG 문서 캐싱

검색된 문서를 캐시에 올려두고 여러 질문에 재사용하는 패턴이다.

import anthropic

client = anthropic.Anthropic()

# 검색된 문서 (예: 제품 매뉴얼 30페이지)
retrieved_document = """
[제품명: CloudSuite Pro 기술 문서]
버전 3.2.1 — 2026년 1월 기준

1. 시스템 요구 사항
   - OS: Ubuntu 22.04 LTS 이상 / Windows Server 2022
   - RAM: 최소 16GB, 권장 32GB
   ...
[이하 대용량 문서 내용 약 20,000토큰]
"""

def ask_about_document(question: str) -> str:
    """동일 문서에 대해 여러 질문 — 문서는 캐시에서 재사용"""
    response = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=512,
        system=[
            {
                "type": "text",
                "text": retrieved_document,
                "cache_control": {"type": "ephemeral"}  # 문서를 캐시에 고정
            }
        ],
        messages=[
            {"role": "user", "content": question}
        ]
    )
    return response.content[0].text

# 첫 번째 질문: 문서 캐시 저장 (쓰기 비용)
answer1 = ask_about_document("최소 RAM 요구 사항은?")

# 두 번째 질문: 문서 캐시에서 읽기 (90% 할인)
answer2 = ask_about_document("지원되는 운영체제 목록은?")

# 세 번째 질문: 동일하게 캐시 히트
answer3 = ask_about_document("버전 3.2.1의 주요 변경 사항은?")

멀티턴 대화 캐싱

대화가 길어질수록 히스토리 토큰이 쌓인다. cache_control을 마지막 사용자 메시지 직전 어시스턴트 응답에 붙이면 히스토리 전체가 캐시된다.

import anthropic

client = anthropic.Anthropic()

def chat_with_caching(conversation_history: list, new_message: str) -> str:
    """대화 히스토리를 캐시해 누적 비용 절감"""
    
    # 히스토리의 마지막 메시지에 cache_control 적용
    cached_history = []
    for i, msg in enumerate(conversation_history):
        if i == len(conversation_history) - 1:
            # 마지막 히스토리 항목에 캐시 마킹
            cached_msg = {
                "role": msg["role"],
                "content": [
                    {
                        "type": "text",
                        "text": msg["content"],
                        "cache_control": {"type": "ephemeral"}
                    }
                ]
            }
        else:
            cached_msg = msg
        cached_history.append(cached_msg)
    
    # 새 사용자 메시지 추가
    cached_history.append({"role": "user", "content": new_message})
    
    response = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        messages=cached_history
    )
    
    return response.content[0].text

비용 계산 예시: 적용 전 vs 적용 후

실제 프로덕션 시나리오를 기준으로 비교한다.

시나리오: 고객 지원 챗봇

조건

시스템 프롬프트: 8,000토큰 (상품 정보, 응대 지침, FAQ)
사용자 메시지: 평균 300토큰
Claude 응답: 평균 400토큰
일 호출 수: 2,000회
모델: Claude Sonnet 4.5 (입력 $3.00/M, 출력 $15.00/M)

캐싱 미적용

입력 토큰/호출: 8,000 + 300 = 8,300토큰
일 입력 비용: $3.00/M × (8,300 × 2,000) / 1,000,000
            = $3.00 × 16.6 = $49.80

일 출력 비용: $15.00/M × (400 × 2,000) / 1,000,000
            = $15.00 × 0.8 = $12.00

일 합계: $61.80
월 합계: $61.80 × 30 = $1,854.00 (약 259만원)

캐싱 적용

캐시 쓰기 1회/일: $3.75/M × 8,000 / 1,000,000 = $0.03

캐시 읽기 1,999회: $0.30/M × (8,000 × 1,999) / 1,000,000
                  = $0.30 × 15.992 = $4.80

일반 입력 (사용자 메시지): $3.00/M × (300 × 2,000) / 1,000,000
                         = $3.00 × 0.6 = $1.80

일 출력 비용 (동일): $12.00

일 합계: $0.03 + $4.80 + $1.80 + $12.00 = $18.63
월 합계: $18.63 × 30 = $558.90 (약 78만원)

항목	캐싱 미적용	캐싱 적용	절감율
일 비용	$61.80	$18.63	69.8%
월 비용	$1,854	$558.90	69.8%
연 비용	$22,248	$6,706	약 1,570만원 절감

입력 토큰에서만 보면 시스템 프롬프트 8,000토큰이 $3.00/M → $0.30/M으로 90% 절감되고, 출력 비용은 변하지 않는다. 출력 비중이 높을수록 전체 절감율은 낮아지지만, 시스템 프롬프트가 길수록 절감 효과는 커진다.

최적 사용 케이스

케이스 1: 긴 시스템 프롬프트

가장 즉각적인 효과를 내는 케이스다. 5,000토큰 이상의 시스템 프롬프트를 사용하는 서비스라면 캐싱을 즉시 적용해야 한다. 법률, 의료, 금융 도메인 챗봇처럼 상세한 지침과 도메인 지식을 시스템 프롬프트에 담는 서비스에 최적이다.

케이스 2: RAG 파이프라인

검색 결과로 가져온 문서를 캐시에 올려두고 여러 질문에 재사용한다. 동일 사용자가 하나의 문서에 대해 여러 질문을 하는 패턴(예: PDF 분석 도구, 기술 문서 Q&A)에서 효과가 극대화된다. 문서당 처음 한 번만 캐시 쓰기 비용을 내고 이후 질문은 모두 90% 할인 요금이 적용된다.

케이스 3: 멀티턴 대화

대화가 길어질수록 히스토리 토큰이 누적된다. 10턴 대화면 이미 수천 토큰의 히스토리가 쌓인다. 이전 대화 히스토리에 캐시를 적용하면 각 턴마다 반복되는 히스토리 비용을 90% 절감할 수 있다. 콜센터 자동화, 장기 컨설팅 봇처럼 대화가 길어지는 서비스에 적합하다.

케이스 4: Claude 3.5 Haiku 기반 서비스

Haiku는 이미 저렴하지만($0.80/M), 캐싱 적용 시 캐시 읽기 단가가 $0.08/M으로 떨어진다. 대량 호출 서비스에서 Haiku + 캐싱 조합은 사실상 토큰당 비용을 극한으로 낮추는 전략이다. Haiku로 처리 가능한 반복 작업(분류, 요약, 추출)에 캐싱까지 더하면 운영 비용이 경쟁 모델 대비 수십 배 저렴해진다.

손익분기점 계산

캐싱 적용 비용이 미적용보다 이득이 되는 최소 캐시 히트 횟수는 1.28회다.

계산 근거:

캐시 쓰기 비용: 입력 단가 × 1.25
캐시 읽기 비용: 입력 단가 × 0.10 (90% 할인)
미캐싱 기준 비용: 입력 단가 × N (N = 총 호출 횟수)

손익분기점 수식:
(1.25 × 캐시_토큰) + (0.10 × 캐시_토큰 × (N-1)) = 1.00 × 캐시_토큰 × N
1.25 + 0.10(N-1) = N
1.25 + 0.10N - 0.10 = N
1.15 = 0.90N
N = 1.15 / 0.90 ≈ 1.28

즉, 동일 캐시 블록이 2회 이상 사용되면 무조건 이득이다. 1.28회가 손익분기이므로 사실상 캐시 가능한 모든 콘텐츠에 적용해도 손해가 없다.

단, 캐시 TTL은 5분이다. 5분 내에 동일 캐시 블록을 재사용하지 않으면 캐시가 만료되고 다음 호출에서 다시 쓰기 비용이 발생한다. 따라서 호출 빈도가 낮은 서비스(5분에 1회 미만)에서는 실질적인 절감 효과가 제한적일 수 있다.

서비스별 캐싱 효과 추정:

호출 빈도	일 캐시 히트 횟수 (8시간 운영)	캐싱 권장 여부
분당 1회 이상	480회 이상	강력 권장
5분당 1회	96회	권장
시간당 1회	8회	적용 가능
하루 1~2회	1~2회	미적용과 거의 동일

API 비용 전반에 대한 더 깊은 분석이 필요하다면 Claude API 비용 완전 가이드를 참고하라. 모델별 요금, Batch API 50% 할인, 80/15/5 모델 라우팅 전략을 상세히 다루고 있다.

고급 캐싱 패턴

다중 캐시 포인트 설정

하나의 요청에 여러 개의 cache_control 블록을 설정할 수 있다. 정적 콘텐츠와 세미-정적 콘텐츠를 계층적으로 캐시한다.

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "불변 시스템 지침 (수천 토큰)...",
            "cache_control": {"type": "ephemeral"}  # 첫 번째 캐시 포인트
        },
        {
            "type": "text",
            "text": "오늘의 프로모션 정보 (자주 바뀜)...",
            # cache_control 없음: 동적 콘텐츠는 캐시하지 않음
        }
    ],
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "대용량 참조 문서...",
                    "cache_control": {"type": "ephemeral"}  # 두 번째 캐시 포인트
                },
                {
                    "type": "text",
                    "text": "실제 사용자 질문"
                    # 동적 부분: 캐시 안 함
                }
            ]
        }
    ]
)

캐시 포인트는 콘텐츠 블록 순서대로 적용된다. 앞 블록이 캐시에 없으면 이후 블록도 캐시에서 읽히지 않는다. 캐시 히트율을 높이려면 변하지 않는 콘텐츠를 앞에 배치하고, 동적 콘텐츠를 뒤에 배치해야 한다.

캐시 히트율 모니터링

import anthropic
from collections import defaultdict

client = anthropic.Anthropic()

# 누적 통계 추적
stats = defaultdict(int)

def tracked_request(system_prompt: str, user_message: str) -> str:
    response = client.messages.create(
        model="claude-haiku-3-5",
        max_tokens=512,
        system=[{"type": "text", "text": system_prompt,
                 "cache_control": {"type": "ephemeral"}}],
        messages=[{"role": "user", "content": user_message}]
    )
    
    usage = response.usage
    stats["cache_writes"]  += usage.cache_creation_input_tokens or 0
    stats["cache_reads"]   += usage.cache_read_input_tokens or 0
    stats["normal_inputs"] += usage.input_tokens
    
    total_cache_tokens = stats["cache_writes"] + stats["cache_reads"]
    if total_cache_tokens > 0:
        hit_rate = stats["cache_reads"] / total_cache_tokens * 100
        print(f"캐시 히트율: {hit_rate:.1f}% "
              f"(쓰기: {stats['cache_writes']:,} / 읽기: {stats['cache_reads']:,}토큰)")
    
    return response.content[0].text

캐시 히트율이 80% 미만이라면 시스템 프롬프트 구조를 재검토해야 한다. 주요 원인은 캐시 TTL 초과(호출 간격 > 5분), 캐시 블록 콘텐츠가 호출마다 달라지는 경우, cache_control 위치가 동적 콘텐츠 뒤에 있는 경우다.

Extended Thinking과 캐싱을 함께 사용하는 심화 패턴은 Claude Extended Thinking 한국어 가이드에서 다룬다.

비용 최적화를 더 체계적으로 배우고 싶다면 **P5 Claude API 비용 최적화 마스터클래스**를 확인하라. 프롬프트 캐싱부터 Batch API, 모델 라우팅, 실시간 비용 대시보드 구축까지 실제 프로덕션에서 검증된 전략을 단계별로 다룬다.

Frequently Asked Questions

프롬프트 캐싱은 모든 Claude 모델에서 지원되나요?

Claude 3 Haiku, Claude 3 Sonnet, Claude 3 Opus, Claude 3.5 Haiku, Claude Sonnet 4.5, Claude Opus 4.5에서 모두 지원됩니다. 캐시 읽기 단가는 모델에 따라 다르며(Haiku $0.08/M, Sonnet $0.30/M, Opus $1.50/M), 모두 기본 입력 단가의 10%입니다. 즉, 어느 모델을 사용하든 캐시 히트 시 90% 절감이 적용됩니다.

캐시 TTL 5분이 너무 짧지 않나요?

실시간 서비스(API 요청이 분당 1회 이상)라면 5분 TTL은 충분합니다. 캐시 히트가 발생할 때마다 TTL이 5분 리셋되므로, 지속적으로 트래픽이 있는 서비스에서는 캐시가 사실상 영구 유지됩니다. 단, 야간처럼 트래픽이 멈추는 시간대에는 캐시가 만료되어 다음 날 첫 호출에서 다시 쓰기 비용이 발생합니다.

cache_control을 붙이면 항상 캐싱이 되나요?

캐시 블록의 최소 크기가 있습니다. 너무 짧은 텍스트(수십 토큰 수준)는 캐시 효율이 없어 실제로 캐시되지 않을 수 있습니다. 실무적으로는 1,000토큰 이상의 블록에 적용하는 것이 효과적입니다. usage.cache_creation_input_tokens 값이 0이 아닌지 확인해 실제 캐시 저장 여부를 검증하세요.

동시 다발적 요청에서도 캐시가 공유되나요?

동일 API 키 아래에서 동일한 캐시 블록 콘텐츠를 사용하는 요청이면 캐시가 공유됩니다. 서버리스 환경에서 여러 인스턴스가 동시에 실행되더라도 Anthropic 서버 측 캐시를 공유하므로 절감 효과가 그대로 적용됩니다. 단, 테넌트가 다른 경우(서로 다른 API 키)는 캐시가 분리됩니다.

프롬프트 캐싱과 Batch API를 함께 사용할 수 있나요?

현재 Batch API와 프롬프트 캐싱을 동시에 적용하는 것은 공식 지원되지 않습니다. 실시간 API에서만 cache_control이 작동합니다. 비용 절감 목표가 있다면 실시간 처리는 캐싱을 적용하고, 비실시간 배치 처리는 Batch API를 적용하는 방식으로 분리해 운영하세요. 두 기능을 각각의 적합한 워크플로우에 적용하면 전체 비용을 최대 90~95%까지 절감할 수 있습니다.