Anthropic의 프롬프트 캐싱(Prompt Caching)은 같은 컨텍스트를 반복 사용하는 요청에서 입력 토큰 비용을 최대 90%, 응답 지연을 최대 85%까지 낮춰줍니다. RAG, 에이전트, 문서 분석처럼 긴 시스템 프롬프트를 반복 사용하는 워크로드에서 특히 효과적입니다.
Claude API를 호출할 때마다 전체 프롬프트를 처음부터 처리하면 긴 시스템 프롬프트나 문서를 반복해서 토큰 비용을 내야 합니다. 프롬프트 캐싱은 한 번 처리한 프롬프트의 앞부분을 서버에 보관해두고, 다음 요청에서 그 지점부터 이어서 처리하는 기능입니다.
결과적으로 캐시된 토큰에 대해서는 훨씬 낮은 단가가 적용되고, 이미 처리한 부분을 건너뛰기 때문에 응답도 빨라집니다.
프롬프트 캐싱 = 긴 프롬프트의 공통 앞부분을 서버에 저장해 반복 비용을 없애는 Anthropic 기능
프롬프트는 시스템 프롬프트 → 이전 대화 → 새 사용자 메시지 순서로 구성됩니다. 캐싱은 이 중 앞에서부터 연속된 고정 구간에만 적용됩니다.
cache_control: {"type": "ephemeral"}을 표시한 지점까지 처리하고 캐시에 저장합니다. 이 요청은 일반 입력 토큰 단가에 25% 추가 요금이 붙습니다.캐시 히트 여부는 응답의 usage 필드에서 cache_read_input_tokens와 cache_creation_input_tokens로 확인할 수 있습니다.
Claude Sonnet 4.6 기준으로 캐싱 적용 전후를 비교하면 다음과 같습니다.
| 항목 | 일반 입력 토큰 | 캐시 쓰기 | 캐시 읽기 |
|---|---|---|---|
| 단가 (MTok 당) | $3.00 | $3.75 (+25%) | $0.30 (−90%) |
| 지연시간 | 기준 | 기준 이상 | 최대 85% 단축 |
| 적용 조건 | 항상 | cache_control 지정 시 | 동일 접두사 캐시 존재 시 |
캐시 쓰기 비용(+25%)을 캐시 읽기 절감(−90%)이 상쇄하려면 같은 캐시를 약 1.2회 이상 재사용하면 됩니다. 2회 이상이면 즉시 이득입니다.
실제 워크로드에서는 문서 분석, 코드 리뷰, 멀티턴 대화처럼 긴 공통 컨텍스트를 반복 사용하는 경우가 많아, 실전 절감율은 흔히 50~90% 범위에 들어옵니다.
cache_control은 시스템 프롬프트, 사용자/어시스턴트 메시지, 도구 정의의 마지막 콘텐츠 블록에 붙일 수 있습니다. 현재 지원되는 유일한 타입은 "ephemeral"입니다.
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
system=[{
"type": "text",
"text": "당신은 전문 코드 리뷰어입니다. [여기에 긴 가이드라인...]",
"cache_control": {"type": "ephemeral"}
}],
messages=[{"role": "user", "content": "이 코드를 리뷰해줘: ..."}]
)
시스템 프롬프트 블록 마지막에 cache_control을 붙이면 해당 블록까지의 모든 토큰이 캐시 대상이 됩니다. 같은 시스템 프롬프트로 두 번째 요청을 보내면 캐시 히트가 발생합니다.
긴 대화 이력을 매번 전달하는 경우, 직전 어시스턴트 메시지에 cache_control을 붙이면 그 이전 대화 전체가 캐시됩니다.
messages = [
{"role": "user", "content": "첫 번째 질문..."},
{"role": "assistant", "content": [{"type": "text", "text": "답변...", "cache_control": {"type": "ephemeral"}}]},
{"role": "user", "content": "두 번째 질문..."},
]
가장 단순하고 효과적인 패턴입니다. 수천 토큰짜리 페르소나·가이드라인·도메인 지식을 시스템 프롬프트에 담고 cache_control을 붙입니다. 이후 모든 요청에서 시스템 프롬프트 비용이 90% 절감됩니다.
적합한 경우: 챗봇, 고객 지원 AI, 전문 어시스턴트
PDF, 법률 문서, 코드베이스 등 수만 토큰짜리 문서를 첫 번째 사용자 메시지에 붙이고 cache_control을 달아 캐시합니다. "이 문서에서 A를 찾아줘", "이 문서에서 B를 요약해줘" 등 다수의 후속 쿼리를 저렴하게 처리할 수 있습니다.
적합한 경우: 문서 Q&A, 계약서 분석, 코드 리뷰 파이프라인
에이전트가 많은 도구(Tool)를 사용할 때 도구 정의 목록은 매 요청마다 동일합니다. 마지막 도구 정의에 cache_control을 붙이면 도구 정의 전체가 캐시되어 에이전트 루프 비용을 크게 줄입니다.
적합한 경우: 자율 에이전트, MCP 기반 워크플로
고품질 few-shot 예시를 시스템 프롬프트나 초기 메시지에 포함시키고 캐시합니다. 일관된 출력 형식이 필요한 파이프라인에서 품질과 비용을 동시에 잡을 수 있습니다.
적합한 경우: 구조화된 데이터 추출, 일정한 포맷 생성
cache_control 지점을 지정할 수 있습니다.프롬프트 캐싱을 도입하기 전 아래 항목을 순서대로 확인하세요.
"cache_control": {"type": "ephemeral"}을 붙입니다.cache_read_input_tokens가 증가하는지 확인해 캐시 히트율을 측정합니다.긴 프롬프트일수록 캐싱 효과가 커집니다
RAG 파이프라인, 자율 에이전트, 대용량 문서 분석처럼 동일한 컨텍스트를 반복 사용하는 워크로드라면 cache_control 한 줄 추가로 API 비용을 대폭 줄일 수 있습니다. Anthropic SDK를 사용 중이라면 오늘 바로 적용해 보세요.