클로드 API 프롬프트 캐싱으로 비용 줄이기: 원리와 적용 예

API 요금 계산법에서 긴 문서를 다루면 입력 토큰 비용이 대부분을 차지한다고 했습니다. 그런데 이 입력의 상당 부분은 매번 똑같습니다. 같은 시스템 프롬프트, 같은 매뉴얼, 같은 문서. 이 반복 부분을 재사용하는 기능이 프롬프트 캐싱(Prompt Caching)입니다.

캐싱의 원리: 앞부분이 같으면 재사용

클로드 API는 요청을 앞에서부터 순서대로 처리합니다(도구 정의 → 시스템 프롬프트 → 대화). 캐싱을 켜면, 이전 요청과 앞부분이 글자 하나까지 똑같은 구간을 다시 계산하지 않고 저장된 결과를 씁니다.

요청 1: [시스템 프롬프트 + 매뉴얼 50쪽] + 질문 A   → 앞부분을 캐시에 저장
요청 2: [시스템 프롬프트 + 매뉴얼 50쪽] + 질문 B   → 앞부분은 캐시에서 읽기
요청 3: [시스템 프롬프트 + 매뉴얼 50쪽] + 질문 C   → 앞부분은 캐시에서 읽기

비용이 얼마나 줄어드나

공식 문서 기준으로 캐시 관련 단가는 일반 입력 단가 대비 다음과 같습니다.

처음 한 번은 조금 더 비싸지만, 그 뒤 재사용할 때마다 해당 부분 비용이 약 10분의 1로 줄어듭니다. 같은 문서로 질문을 여러 번 한다면 두 번째 요청부터 이득입니다.

계산 예시

매뉴얼 40,000토큰에 질문을 하루 300번 하는 사내 Q&A 봇(Sonnet 5, 입력 $2/1M 기준)이라면:

캐싱 없음: 40,000 × 300 = 12M 토큰 × $2 = 하루 약 $24
캐싱 적용: 대부분 캐시 읽기 → 12M × $0.2 = 하루 약 $2.4 (+ 캐시 쓰기 비용 소량)

캐시 유지 시간 안에 요청이 계속 들어온다는 가정이지만, 차이가 매우 큽니다.

파이썬 적용 예시

가장 간단한 방법: 자동 캐싱

요청 최상위에 cache_control을 넣으면 캐싱 가능한 마지막 블록까지 자동으로 캐싱합니다.

import anthropic

client = anthropic.Anthropic()
MANUAL = open("manual.txt", encoding="utf-8").read()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=f"너는 사내 매뉴얼 Q&A 도우미다. 아래 매뉴얼에 근거해서만 답해.\n\n{MANUAL}",
    messages=[{"role": "user", "content": "연차 신청은 며칠 전까지 해야 해?"}],
)

위치를 직접 지정하는 방법

어디까지 캐싱할지 정확히 지정하려면 해당 블록에 cache_control을 붙입니다.

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": f"너는 사내 매뉴얼 Q&A 도우미다.\n\n{MANUAL}",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": question}],
)

캐시가 걸렸는지 확인하기

응답의 usage에서 확인합니다.

print(response.usage.cache_creation_input_tokens)  # 캐시에 새로 쓴 토큰
print(response.usage.cache_read_input_tokens)      # 캐시에서 읽은 토큰
print(response.usage.input_tokens)                 # 캐시 없이 처리한 토큰

두 번째 요청부터 cache_read_input_tokens가 0보다 크면 성공입니다.

캐시가 안 걸리는 흔한 실수

핵심 원칙은 하나입니다. 변하지 않는 것은 앞에, 변하는 것은 뒤에.

캐시가 안 걸렸던 이유

캐싱을 처음 적용했을 때 cache_read_input_tokens가 계속 0이어서 한참 헤맸습니다. 원인은 시스템 프롬프트 첫 줄에 넣어 둔 "오늘 날짜: 2026-09-09 09:08"이었습니다. 분 단위로 바뀌는 값 하나가 매번 캐시를 깨고 있었던 거죠. 날짜를 사용자 메시지 쪽으로 옮기자 바로 캐시가 걸렸습니다. 캐싱이 안 된다면 앞부분에 바뀌는 값이 없는지부터 확인하세요.

📌 3줄 요약

1. 프롬프트 캐싱은 앞부분이 똑같은 반복 입력을 재사용해 비용을 약 10분의 1로 줄입니다.
2. 최상위 cache_control 자동 캐싱이 가장 간단하고, 위치 지정도 가능합니다.
3. 바뀌는 값은 뒤로 보내고, usage의 캐시 읽기 토큰으로 효과를 확인하세요.

출처·참고 링크

• 프롬프트 캐싱 (Anthropic 공식 문서)
• Claude API 요금 (공식)