Claude API 프롬프트 캐싱으로 반복 요청 비용을 줄인 방법 - 공식 문서 기준으로 정리한 기록
Claude API 프롬프트 캐싱으로 반복 요청 비용을 줄인 방법 - 공식 문서 기준으로 정리한 기록
AI API 활용
공식 문서와 실제 사용 경험을 기준으로 정리했습니다.
핵심 원리 — 앞부분이 같아야 재사용된다(접두어 매칭)
프롬프트 캐싱을 이해하는 가장 중요한 한 문장은 "캐싱은 접두어(prefix) 매칭"이라는 점입니다. 캐시는 프롬프트의 앞부분이 바이트 단위로 똑같을 때만 재사용됩니다. 앞쪽 어딘가에서 한 글자라도 달라지면, 그 지점 이후는 전부 새로 계산합니다.
요청이 조립되는 순서는 공식 문서 기준으로 tools → system → messages 입니다. 그래서 바뀌지 않는 내용을 앞에, 매번 달라지는 내용을 뒤에 두는 것이 캐싱 설계의 기본입니다. 예를 들어 고정된 시스템 지침·긴 참고 문서는 앞에 두고, 사용자마다 달라지는 질문은 맨 뒤에 두는 식입니다.
어떻게 켜는가 — cache_control
캐싱은 캐시하고 싶은 블록에 cache_control: {"type": "ephemeral"}를 붙여서 켭니다. 가장 간단한 방법은 요청 최상위에 한 번 지정해 "캐시 가능한 마지막 블록"을 자동으로 캐시하게 하는 것입니다.
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
cache_control={"type": "ephemeral"},
system="이 긴 문서에 대한 전문가로서...",
messages=[{"role": "user", "content": "핵심만 요약해줘"}],
)
더 세밀하게 두고 싶으면 특정 블록에 직접 cache_control을 붙일 수 있습니다. 아래는 시스템 프롬프트의 긴 문서 블록만 캐시하는 예입니다.
system=[{
"type": "text",
"text": 긴_문서_텍스트,
"cache_control": {"type": "ephemeral"} # 기본 유지 5분
}]
기본 캐시 유지 시간은 5분이고, {"type": "ephemeral", "ttl": "1h"}처럼 1시간짜리로 둘 수도 있습니다. 유지 시간 안에 같은 앞부분으로 요청이 다시 오면 캐시를 재사용합니다.
캐시가 되는 최소 크기와 개수
앞부분이 너무 짧으면 캐시 표시를 붙여도 캐시되지 않습니다. 오류가 나는 게 아니라 조용히 캐시가 안 되는 것이라, 최소 크기를 알아 두는 편이 좋습니다. 공식 문서 기준 모델별 최소 접두어 길이는 다음과 같습니다.
즉 3천 토큰짜리 접두어는 Sonnet 4.6에서는 캐시되지만 Opus 4.8에서는 조용히 캐시되지 않습니다. 또 한 요청에 붙일 수 있는 캐시 지점(브레이크포인트)은 최대 4개입니다.
비용 구조 — 읽기는 싸고, 쓰기는 조금 비싸다
캐시는 공짜가 아니라, "처음 한 번 쓰는 값"과 "이후 읽는 값"이 다릅니다. 공식 문서 기준으로 정리하면 이렇습니다.
- 캐시 읽기: 기본 입력 가격의 약 0.1배 — 재사용될 때는 매우 저렴합니다.
- 캐시 쓰기: 5분 유지는 약 1.25배, 1시간 유지는 약 2배 — 처음 담을 때 조금 더 냅니다.
그래서 "몇 번 재사용해야 이득인지"가 생깁니다. 문서 기준 손익분기는 5분 유지면 약 2회, 1시간 유지면 약 3회 요청부터입니다. 같은 앞부분으로 여러 번 부를수록 캐싱이 유리하고, 딱 한 번만 부르는 프롬프트라면 오히려 쓰기 비용만 더 내게 됩니다.
캐시가 자꾸 깨지는 흔한 실수
캐싱을 켰는데도 효과가 없다면, 대개 앞부분이 매 요청 조금씩 바뀌고 있어서입니다. "접두어가 바이트 단위로 같아야 한다"는 규칙을 조용히 어기는 대표적인 경우들입니다.
- 시스템 프롬프트에 현재 시각·랜덤 값 —
datetime.now()나uuid4()를 앞부분에 넣으면 매 요청 접두어가 달라져 캐시가 매번 새로 만들어집니다. - 정렬 안 된 JSON 직렬화 —
json.dumps()에서 키 순서가 들쭉날쭉하면 같은 데이터라도 바이트가 달라집니다(sort_keys=True등으로 고정). - 요청마다 바뀌는 툴 목록 — 도구 정의는 맨 앞(
tools)에 렌더링되므로, 순서를 바꾸거나 사용자마다 다른 도구를 넣으면 그 뒤 전부가 무효화됩니다. - 모델 교체 — 캐시는 모델별로 따로라, 대화 중간에 모델을 바꾸면 캐시를 새로 써야 합니다.
진짜 캐시가 됐는지 확인하는 법
캐시가 실제로 적중했는지는 응답의 usage에서 확인할 수 있습니다.
같은 앞부분으로 여러 번 요청했는데도 cache_read_input_tokens가 계속 0이라면, 앞의 "흔한 실수" 중 하나로 접두어가 매번 달라지고 있다는 신호입니다. 두 요청의 프롬프트를 나란히 비교해 어디서부터 바이트가 달라지는지 찾으면 됩니다.
언제 쓰면 좋고, 언제 안 좋은가
- 잘 맞는 경우 — 긴 시스템 지침이나 참고 문서를 여러 질문에 걸쳐 재사용할 때, 대화가 길게 이어질 때(이전 대화 전체가 접두어로 재사용됨).
- 안 맞는 경우 — 요청마다 앞부분이 처음부터 달라질 때. 재사용할 공통 접두어가 없으니 캐시 표시를 붙여도 쓰기 비용만 더 냅니다. 이럴 땐 캐싱을 끄는 편이 낫습니다.
자주 묻는 질문
Q. 캐시 표시를 붙였는데 비용이 안 줄어요.
응답의 cache_read_input_tokens를 먼저 보세요. 0이면 캐시가 적중하지 않은 것이고, 대개 시스템 프롬프트의 시각·랜덤 값, 정렬 안 된 JSON, 요청마다 바뀌는 툴 목록이 원인입니다.
Q. 5분과 1시간 중 뭘 쓰면 되나요?
요청이 촘촘하면 기본 5분으로 충분합니다. 요청 사이 간격이 5분보다 벌어지는데 계속 캐시를 살려 두고 싶으면 1시간을 고려합니다. 다만 1시간은 쓰기 비용이 더 커, 재사용 횟수가 어느 정도 될 때 이득입니다.
Q. 짧은 프롬프트도 캐시되나요?
앞부분이 모델별 최소 길이(예: Opus 4.8은 4,096토큰)에 못 미치면 오류 없이 조용히 캐시되지 않습니다. 짧은 프롬프트라면 캐싱 효과를 기대하기 어렵습니다.
마무리
정리하면, 프롬프트 캐싱은 "바뀌지 않는 앞부분을 앞에 두고 캐시 표시를 붙이는" 단순한 규칙 위에서 동작합니다. 고정된 지침·긴 문서를 앞쪽에 모으고, 매번 달라지는 질문을 뒤에 두고, usage.cache_read_input_tokens로 실제 적중을 확인하는 것 — 이 세 가지만 지켜도 같은 앞부분을 반복하는 요청에서 처리 비용을 눈에 띄게 줄일 수 있었습니다. 반대로 요청마다 처음부터 다른 프롬프트라면 캐싱은 큰 의미가 없다는 점도 함께 기억해 두면 좋습니다.
이 글의 수치와 동작 설명은 Claude API 공식 문서를 기준으로 정리했습니다. 가격·최소 크기 등 세부 사항은 모델과 시점에 따라 달라질 수 있으니, 최신 내용은 공식 문서에서 직접 확인하시길 권합니다.
- 프롬프트 캐싱 문서: platform.claude.com/docs/en/build-with-claude/prompt-caching
- 가격 문서: platform.claude.com/docs/en/pricing
※ 본 글은 공개된 공식 문서와 개인적인 사용 경험을 바탕으로 정리한 정보성 콘텐츠입니다. API의 기능·가격·수치는 모델과 시점에 따라 달라질 수 있으며, 특정 비용 절감 결과를 보장하지 않습니다.