핵심 요약

Claude API는 cache_control 파라미터로 프롬프트의 특정 구간을 재사용할 수 있다. 캐시 히트 시 입력 토큰 비용이 약 10%까지 떨어진다.

최소 캐시 토큰: 1024 (Haiku), 2048 (Sonnet/Opus)
TTL: 기본 5분 (연장 가능)
캐시 쓰기: 기준가의 약 1.25배
캐시 히트 읽기: 기준가의 약 0.1배

기본 사용법

from anthropic import Anthropic
client = Anthropic()
client.messages.create(
    model="claude-opus-4-7",
    system=[
        {"type": "text", "text": "짧은 규칙"},
        {
          "type": "text",
          "text": LONG_CONTEXT,   # 긴 문서 or 도구 설명
          "cache_control": {"type": "ephemeral"}
        },
    ],
    messages=[{"role": "user", "content": "질문"}],
)

cache_control이 붙은 블록은 해당 지점까지를 캐시 경계(prefix)로 저장한다. 다음 요청이 같은 prefix로 시작하면 자동 재사용.

실전 패턴 6가지

1) 시스템 프롬프트 + 도구 정의 캐싱

가장 흔한 케이스. 대부분의 에이전트는 시스템 프롬프트와 tools 배열이 요청마다 동일하다. 맨 뒤 블록에 cache_control을 달면 끝.

2) 대용량 문서 QA

같은 PDF·코드베이스에 여러 질문을 던질 때. 문서를 첫 user 메시지로 넣고 캐시 경계를 설정.

messages=[
  {"role":"user","content":[
    {"type":"text","text": BIG_DOC,
     "cache_control":{"type":"ephemeral"}},
    {"type":"text","text":"요약해줘"}
  ]}
]

3) Few-shot 예제 캐싱

프롬프트에 10~50개 예제를 박아두는 경우. 예제 묶음 끝에 캐시 마커.

4) 멀티턴 대화 누적 캐싱

대화가 길어질수록 비용이 n² 비례로 증가. 매 턴마다 마지막 어시스턴트 메시지에 cache_control을 달면 누적 캐시.

5) 에이전트 툴 호출 결과 캐싱

도구 실행 결과가 큰 텍스트(로그·스키마)일 때. 결과 블록 뒤에 캐시 경계.

6) 코드 리뷰 봇 — 레포 스냅샷 캐싱

저장소 전체를 매번 넘기는 대신, 스냅샷을 캐시하고 변경 diff만 추가로 전달.

캐시 적중 확인

응답의 usage에 다음 필드가 포함된다.

{
  "cache_creation_input_tokens": 12350,
  "cache_read_input_tokens": 12350,
  "input_tokens": 87,
  "output_tokens": 423
}

cache_read_input_tokens가 0이 아니면 히트. 이 값이 전체 input의 대부분이어야 이상적이다.

비용 절감 체크리스트

시스템 프롬프트가 2k 토큰 이상인가? → 즉시 캐시
같은 문서에 여러 질문을 던지는가? → 문서 블록 캐시
에이전트 루프에서 tools가 고정인가? → tools 끝에 캐시
TTL 5분 내 요청 빈도가 충분한가? → 낮으면 캐시 쓰기 비용만 나옴

자주 묻는 질문

캐시 경계가 바뀌면?

앞 블록이 단 1 토큰이라도 다르면 prefix 불일치로 캐시 미스. "고정 앞 + 가변 뒤" 순서로 구성해야 한다.

TTL 연장이 가능한가?

확장 TTL(1시간) 옵션이 있지만 쓰기 비용이 올라간다. 트래픽 밀도가 충분할 때만 유리.

복수 cache_control 동시 사용?

최대 4개 캐시 경계를 지원한다. 여러 단계로 부분 캐시 가능.

Claude API 프롬프트 캐싱 완벽 활용 — 비용 90% 절감 실전 패턴 6가지