Quick Reference

Prompt caching은 이전 응답을 저장하는 기능이 아니라, 여러 API 요청 앞에 반복되는 같은 prefix를 다시 처리하지 않게 하는 기능입니다. 긴 system instruction, tool 정의, 고정 문서, few-shot 예시가 계속 같고 뒤의 질문만 바뀔 때 비용과 지연을 낮춥니다. 기본 TTL은 5분이며, 필요하면 비용을 비교한 뒤 1시간 TTL을 선택합니다.

response = client.messages.create(
    model="지원 모델 ID",
    max_tokens=1_024,
    cache_control={"type": "ephemeral"},
    system="변하지 않는 검토 정책과 용어집",
    messages=[{"role": "user", "content": "이번 변경의 위험만 요약해 줘."}],
)

cache 범위와 breakpoint

캐시는 tools, system, messages 순서로 구성된 요청의 처음부터 breakpoint까지를 참조합니다. 중간 일부만 독립적으로 캐시하는 기능이 아니므로, 앞쪽에 자주 바뀌는 timestamp·사용자별 설정·질문을 넣으면 그 뒤의 긴 문서도 재사용하지 못합니다. 고정 내용은 앞에, 매 요청 달라지는 질문과 결과는 뒤에 둡니다.

자동 caching은 요청 최상위의 cache_control 하나로 마지막 cacheable block까지의 breakpoint를 시스템이 관리합니다. 대화 이력이 길어지는 흐름에 먼저 고릅니다. 명시적 breakpoint는 서로 다른 주기로 바뀌는 긴 정책·문서·예시 경계를 직접 지정할 때 맞습니다.

{
  "type": "text",
  "text": "여러 요청에서 바뀌지 않는 긴 정책 문서",
  "cache_control": {
    "type": "ephemeral",
    "ttl": "1h"
  }
}

캐시는 write 또는 hit 요청의 시작 시점부터 TTL을 계산합니다. 긴 응답을 4분 동안 생성했다면, 5분 TTL cache를 이어 쓰는 다음 요청은 응답 종료 뒤 약 1분 안에 시작해야 할 수 있습니다. 응답 생성이 끝난 시각부터 새로 5분이 시작된다고 설계하면 hit가 끊깁니다.

비용과 관찰

cache hit는 입력 전체가 동일하다는 막연한 판단이 아니라 breakpoint 이전 prefix가 같을 때 발생합니다. tool description·input schema, system prompt, 메시지 순서, effort 같은 요청 설정을 바꾸면 기대한 hit가 사라질 수 있습니다. 특히 cache를 쓰는 대화에서 output_config.effort를 바꾸면 렌더링된 prefix가 달라질 수 있습니다.

5분 write, 1시간 write, hit는 모델의 일반 input token과 다른 가격 배수를 가집니다. 고정 가격을 카드에 박아 두기보다 현재 가격표와 실제 usage를 함께 보며, 단발 요청의 write 비용보다 반복 hit 이득이 큰지 평가합니다.

자주 틀리는 부분

피해야 할 배치
tools -> 매번 달라지는 사용자 설정 -> 긴 정책 문서 -> 질문

권장 배치
tools -> 고정 system instruction -> 고정 정책·예시 -> 이번 질문

확인 순서
1. usage에서 creation/read token을 기록한다.
2. breakpoint 앞의 변경점을 비교한다.
3. 재사용 빈도와 TTL write 비용을 함께 평가한다.