핵심 요약
Anthropic Prompt Caching은 같은 시스템 프롬프트·코드베이스·문서를 반복 호출할 때 입력 비용을 정가의 10%로 줄임. 챗봇·RAG·코드 리뷰에서 가장 큰 효과. 운영 도입의 첫 번째 비용 최적화 카드.
- Cache hit: 정가의 10% (입력만)
- Cache write: 정가의 1.25배 (한 번)
- TTL: 5분 (default) 또는 1시간
- Multi-block 캐싱 (4개까지)
1. 기본 사용
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
system=[
{
"type": "text",
"text": LARGE_SYSTEM_PROMPT, # 100K tokens
"cache_control": {"type": "ephemeral"}
}
],
messages=[{
"role": "user",
"content": "질문..."
}]
)
print(response.usage)
# input_tokens, cache_creation_input_tokens, cache_read_input_tokens, output_tokens2. 비용 모델
| 유형 | 가격 |
|---|---|
| 일반 입력 | 1.0x ($15/1M for Opus) |
| Cache write (5분 TTL) | 1.25x |
| Cache write (1시간 TTL) | 2.0x |
| Cache hit | 0.1x |
| 출력 | 1.0x |
3. 캐시 적용 효과 (실측)
# 100K 토큰 시스템 프롬프트, 10번 호출
# 캐시 없이
총 비용 = 100K * 10 * $15/1M = $15.00
# 캐시 5분 TTL
첫 호출: 100K * $15 * 1.25 / 1M = $1.875 (write)
2~10번: 100K * $15 * 0.1 / 1M * 9 = $1.35 (hit)
총 = $3.225 (78% 절감)
# 캐시 1시간 TTL (1시간 내 200번 호출)
첫: 100K * $15 * 2.0 / 1M = $3.00
2~200: 100K * $15 * 0.1 / 1M * 199 = $29.85
총 = $32.85
캐시 없으면 200 * $1.5 = $300
89% 절감4. 1시간 TTL 선택 기준
1시간 캐시는 write 비용이 2배. 단 hit가 충분히 많으면 5분보다 유리.
# 손익분기점
# 1시간 캐시: write = 2.0x, hit = 0.1x
# 5분 캐시: write = 1.25x, hit = 0.1x
# 1시간 안에 N번 호출 시:
# 1시간: 2.0x + 0.1x*(N-1) = 1.9 + 0.1N
# 5분 만료 후 재write: (1.25 + 0.1*M)*K (M개씩 K번 재시작)
# 1시간 안에 5분 캐시 12회 재write 가능 → 12 * 1.25 = 15x
# 1시간 캐시 한 번 = 2x
# → 1시간 안에 6+ write 발생 가능성이면 1시간 캐시 유리5. Multi-block 캐싱
여러 부분에 cache_control. 자주 변하는 부분 따로 분리.
messages = [{
"role": "user",
"content": [
{
"type": "text",
"text": COMPANY_HANDBOOK, # 거의 안 변함
"cache_control": {"type": "ephemeral", "ttl": "1h"}
},
{
"type": "text",
"text": TODAY_NEWS, # 매일 변함
"cache_control": {"type": "ephemeral"} # 5분만 캐시
},
{
"type": "text",
"text": user_question # 매 호출 다름, 캐시 안 함
}
]
}]6. 도구·이미지 캐싱
# tool definitions도 캐시 가능
response = client.messages.create(
...,
tools=[
{
"name": "search_db",
"description": "...",
...
},
# ... 50개 tool spec ...
# 마지막 tool에 cache_control 붙이면 그 이전 모두 캐시
]
)7. 활용 사례
1) RAG 시스템
# 시스템 프롬프트 (지침) + 검색된 문서 → cache 가능
system=[
{"type": "text", "text": RAG_INSTRUCTIONS, "cache_control": ...}
]
messages=[{
"role": "user",
"content": f"검색 결과: {retrieved_chunks}\n\n질문: {question}"
}]
# 단점: 검색 결과가 매번 다르면 캐시 효과 적음
# 보완: 자주 검색되는 chunk만 별도 캐시2) 코드 분석
system=[
{"type": "text", "text": codebase_300k_tokens, "cache_control": ...}
]
# 같은 코드베이스에 대한 여러 질문 → 압도적 절감3) 챗봇
# 시스템 프롬프트 + 회사 FAQ → 모든 사용자 공유 캐시
system=[
{"type": "text", "text": SYSTEM, "cache_control": {"type": "ephemeral", "ttl": "1h"}}
]
# 사용자별 conversation은 캐시 안 함8. Cache Hit 모니터링
response = client.messages.create(...)
usage = response.usage
cache_hit_rate = usage.cache_read_input_tokens / (
usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens
)
# 0.6 이상이면 좋은 운영
# 0.3 미만이면 캐시 키·TTL 재검토
# Datadog·Prometheus로 metric 발송
stats.gauge('claude.cache_hit_rate', cache_hit_rate)
stats.increment('claude.cache_read_tokens', usage.cache_read_input_tokens)9. 캐시 invalidation 전략
- 회사 정책 변경 → 새 system 프롬프트 → 자동 새 캐시
- 기존 캐시는 5분/1시간 후 자동 만료
- 강제 invalidate API는 없음 (TTL 만료 대기)
10. 흔한 실수
- cache_control을 너무 많은 블록에 (4개 한도)
- 매번 다른 system 프롬프트 (텍스트 한 글자라도 다르면 새 캐시)
- 1시간 TTL을 짧은 작업에 (5분이면 충분)
- cache hit 모니터링 안 함
11. 비용 추정 도구
def estimate_cost(system_size, requests, ttl_minutes):
sys_tokens = system_size
write_cost = sys_tokens * 0.000015 * (1.25 if ttl_minutes == 5 else 2.0)
hit_cost = sys_tokens * 0.000015 * 0.1
cycles = max(1, requests * 5 / ttl_minutes)
writes = cycles
hits = requests - writes
return writes * write_cost + max(0, hits) * hit_cost
print(estimate_cost(100_000, 100, 5)) # $0.30
print(estimate_cost(100_000, 100, 60)) # $1.83
# 100회는 5분 캐시 유리
print(estimate_cost(100_000, 1000, 5)) # $3
print(estimate_cost(100_000, 1000, 60)) # $4.5
# 1000회도 5분이 약간 유리실측 — 사례
| 워크로드 | before | after | 절감 |
|---|---|---|---|
| 코드 리뷰 (1000 PR/월) | $1,800 | $240 | 87% |
| RAG 챗봇 (10K 쿼리/일) | $4,500 | $650 | 86% |
| 문서 분석 자동화 | $3,200 | $380 | 88% |
댓글 0