프롬프트 캐싱 실전 — cache_control로 API에서 제어하기
프롬프트 캐싱 실전
프롬프트 캐싱은 별도 설정 없이 자동으로는 켜지지 않아요. cache_control 블록으로 어디를 캐시할지 직접 표시해야 해요. 시스템 프롬프트·도구 정의·문서 컨텍스트처럼 반복되는 부분을 캐시 브레이크포인트로 지정해요.
기본 패턴
import anthropic
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
system=[
{"type": "text", "text": "You are an AI assistant.", "cache_control": {"type": "ephemeral"}},
{"type": "text", "text": "Here is the full document: [bulk content]", "cache_control": {"type": "ephemeral"}},
],
messages=[{"role": "user", "content": "Summarize key points."}],
)
도구(tool) 정의도 캐시 가능
도구 정의가 크고 매 요청 반복된다면 마지막 도구 블록에 cache_control을 달아 캐시하면 비용이 크게 줄어요.
주의사항
- 캐시 브레이크포인트는 리스트의 마지막이 아닌 원소에 지정해야 동작해요.
- 캐시된 내용이 변경되면 캐시가 무효화되고 다시 처리돼요.
- 응답 헤더에서 캐시 히트 여부를 확인할 수 있어요.