같은 system prompt를 하루에 200번 Claude에게 보내고 있나요? 매 요청마다 모델이 전체 내용을 다시 읽고, 그 비용을 전부 다시 청구해요. Anthropic의 **프롬프트 캐싱(prompt caching)**은 요청에 키 하나만 추가하면 되고, 코드를 재작성할 필요도 없어요. 같은 블록을 재사용하는 순간부터 입력 토큰 비용이 크게 떨어져요.
지금 비용이 너무 많이 나가는 이유
내부 문서에 대한 질문에 답하는 어시스턴트에 Claude를 사용하고 있다고 가정해 봐요. system prompt가 4,000 토큰(지시사항 + 문서 발췌)이라면, 모든 대화의 모든 차례마다 API가 이 4,000 토큰을 입력으로 다시 읽어요. 이 토큰들이 전혀 바뀌지 않았어도 비용은 청구돼요.
하루 200개 요청, 한 달, 여러 명의 사용자가 동시에 사용하면 청구액이 금세 올라가요. 가장 안타까운 건 이 컨텍스트가 전혀 바뀌지 않는다는 거예요. 변하지 않는 것에 돈을 내고 있는 셈이에요.
캐시 활성화: 키 하나면 충분
현재 요청에서 캐시할 블록에 cache_control을 추가하면 끝이에요.
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
system=[
{
"type": "text",
"text": LONG_SYSTEM_PROMPT,
"cache_control": {"type": "ephemeral"}, # 캐시 활성화
}
],
messages=[
{"role": "user", "content": "사용자 질문"}
],
)system 블록(긴 프롬프트 + 문서 발췌)이 캐시 가능 상태가 돼요. 첫 번째 호출에서 Anthropic이 캐시를 작성하고 1.25x 요금을 청구해요. 5분 이내 두 번째 호출에서 같은 블록을 사용하면 캐시 히트가 되어 0.10x만 청구돼요.
tools와 변경되지 않는 user 블록에도 동일하게 적용할 수 있어요.
히트 시 실제 절감 효과
| 입력 토큰 요금 | 캐시 없음 | 캐시 있음 (히트) |
|---|---|---|
| 배율 | 1.00x | 0.10x |
| 절감 | 없음 | 90% |
| 매 차례마다 재청구 | 예 | 아니요, TTL 창 내에서는 |
구체적으로, Opus 4.7에서 4,000 토큰 system prompt의 요금이 5달러/백만 토큰이라면, 캐시 없이 호출당 0.02달러예요. 캐시 히트 시에는 0.002달러예요. 하루 200개 요청 기준으로, 이 블록 하나만으로 하루 4달러에서 0.40달러로 줄어들어요. tools와 대화 컨텍스트의 히트는 별도 계산이에요.
첫 번째 히트의 함정
대부분의 통합이 놓치는 함정이 있어요: 캐시 작성 비용은 표준 요금보다 25% 비싸요. 따라서 첫 번째 호출은 1.00x 대신 1.25x가 청구돼요. 5분 내 두 번째 히트부터 수익이 나기 시작해요.
첫 번째 호출: 캐시 작성
1.25x를 지불해요. Anthropic 캐시에 블록이 기록돼요.
5분 내 두 번째 호출: 첫 번째 히트
0.10x를 지불해요. 두 번의 호출 누적 합계는 1.35x로, 캐시 없는 두 번의 호출(2.00x)보다 이미 이득이에요.
세 번째 호출 이상: 진짜 히트
각각 0.10x로, 추가 히트가 늘어날수록 격차가 커져요. 5분 내 10번 호출이면 10.00x 대신 약 2.15x만 지불해요.
수익이 나는 경우 vs 손해를 보는 경우
| 사용 사례 | 캐싱 유리 | 이유 |
|---|---|---|
| 50명 이상 동시 사용자의 내부 문서 어시스턴트 | 예 | 병렬로 지속적인 히트 발생, TTL 창이 항상 활성 |
| 긴 컨텍스트의 지원 챗봇 | 예 | 대화마다 동일한 3,000+ 토큰 컨텍스트 사용 |
| 야간 배치 생성 | 예 | 1,000개 요청을 연속으로 전송 |
| 시간당 1번 호출하는 간단한 스크립트 | 아니요 | 호출 사이에 5분 TTL이 만료됨 |
| 짧은 프롬프트 (1024 토큰 미만) | 아니요 | API가 임계값 이하에서는 cache_control 무시 |
프로덕션에서 히트율 측정
API 응답에는 cache_creation_input_tokens와 cache_read_input_tokens 카운터가 포함돼요. 두 값을 로깅하면 실시간으로 히트율을 계산할 수 있어요.
usage = response.usage
hits = usage.cache_read_input_tokens
writes = usage.cache_creation_input_tokens
total_in = usage.input_tokens + hits + writes
hit_ratio = hits / total_in if total_in else 0
print(f"히트율: {hit_ratio:.0%}")히트율 30~40% 이상이면 명확하게 이득이에요. 그 이하라면 손익분기점에 가까운 것이고, 트래픽 패턴을 재검토하거나 일부 블록의 캐시를 비활성화할 신호예요.
프로덕션에서 히트율이 10% 미만이라면 캐시가 도움이 아닌 손해를 주고 있어요. 해당 블록의 캐시를 비활성화하세요.
코드 측면의 함정
자주 묻는 질문
캐싱이 응답 품질에 영향을 주나요?
아니요, 모델 출력에 전혀 영향이 없어요. 정확히 같은 응답이 더 빠르고 저렴하게 나와요. Anthropic은 캐시된 토큰을 다시 처리하지 않지만, 모델은 정상적으로 전송된 것처럼 토큰을 인식해요.
요청당 cache_control 블록을 몇 개까지 설정할 수 있나요?
요청당 최대 4개까지 가능해요. system prompt, tools, messages의 문서 블록, 그 외 다른 블록을 별도로 캐시할 수 있어요. Anthropic은 각각 독립적으로 히트해요.
캐시는 컨텍스트 창에 포함되나요?
네. 캐시된 토큰도 여전히 모델의 컨텍스트 창을 차지해요. 캐싱은 컨텍스트를 더 늘려주는 게 아니라 전송하는 입력 토큰 비용을 낮춰줄 뿐이에요.
캐시가 5분 전에 만료될 위험이 있나요?
활발한 프로젝트에서는 실제로 그런 일이 거의 없어요. Anthropic은 ephemeral 모드를 best-effort 캐시로 설명하지만, 실제 사용에서는 TTL 창을 잘 유지해요. 매우 산발적인 트래픽에서는 만료가 발생할 수 있어요.
더 알아보기
가장 큰 블록에 캐시를 활성화하고 48시간 동안 히트율을 측정해 보세요. 그러면 실제로 어떤 효과가 있는지 수치로 확인할 수 있어요. AI 스택 전반에 대해 이야기하고 싶다면 편하게 연락 주세요.
Blokby와 AI 스택 상담하기