프롬프트 캐싱으로 비용 줄이기

앞 글에서 대화 이력과 시스템 프롬프트가 매 요청마다 입력 토큰으로 다시 과금된다고 했습니다. 프롬프트 캐싱은 그 반복되는 앞부분을 한 번 처리해 두고 다음 요청부터 싼값에 다시 쓰는 기능입니다. 읽고 나면 어떤 요청에 효과가 큰지 판단하고, cache_control을 올바른 위치에 넣고, usage로 적중 여부를 확인할 수 있습니다. 수치는 모두 공식 문서 값입니다.

핵심 요약

• 캐시 읽기는 기본 입력 가격의 0.1배, 쓰기는 5분 캐시가 1.25배, 1시간 캐시가 2배입니다.
• 캐시 접두부는 tools → system → messages 순서로 만들어지며, 앞쪽이 바뀌면 뒤쪽 캐시도 무효가 됩니다.
• 최소 캐시 길이는 Opus 5와 Fable 5가 512토큰, Sonnet 5가 1,024토큰, Haiku 4.5가 4,096토큰입니다.
• 적중 여부는 usage의 cache_read_input_tokens로 확인합니다.

언제 효과가 큰가

같은 앞부분을 짧은 간격으로 반복해서 보낼 때입니다. BizPlan CRM의 사업계획서 생성기처럼 긴 작성 지침과 양식 예시를 system에 넣고 고객사 정보만 바꿔 여러 번 부르는 경우, 상담 메모 수십 건을 같은 규칙으로 보고서로 바꾸는 배치, 턴이 쌓이는 긴 대화가 해당합니다. 매번 내용이 전부 다른 단발 요청이나 최소 길이에 못 미치는 짧은 프롬프트에는 효과가 없고, 짧으면 오류 없이 캐시 없이 처리됩니다.

어떻게 동작하나

방법은 두 가지입니다. 자동 캐싱은 요청 최상위에 cache_control 하나만 두면 시스템이 마지막 캐시 가능 블록에 브레이크포인트를 잡습니다. 다중 턴 대화에 권장되는 출발점입니다.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": "사업계획서 작성 지침 전문 ...",
  "messages": [{"role": "user", "content": "제조업, 매출 8억, 시설자금 목적"}]
}

명시적 브레이크포인트는 개별 콘텐츠 블록에 cache_control을 붙이는 방식으로, 요청당 최대 4개까지 둘 수 있습니다.

"system": [
  {
    "type": "text",
    "text": "사업계획서 작성 지침 전문 ...",
    "cache_control": {"type": "ephemeral"}
  }
]

캐시는 브레이크포인트 위치에서만 기록되고, 다음 요청에서는 브레이크포인트로부터 최대 20블록까지 거슬러 올라가며 이전에 기록된 캐시를 찾습니다. 그래서 요청마다 동일하게 유지되는 마지막 블록에 브레이크포인트를 둡니다. 지원 타입은 ephemeral 하나이며 활성 상태인 모든 Claude 모델에서 쓸 수 있습니다.

가장 중요한 원칙: 고정된 것은 앞에

캐시 접두부는 tools, system, messages 순서로 쌓입니다. 도구 정의를 바꾸면 전체가, system을 바꾸면 system과 messages가, 이미지나 thinking 설정을 바꾸면 messages만 무효가 됩니다. 그래서 요청 구조를 이렇게 짭니다.

1. 도구 정의: 거의 안 바뀌는 것. 맨 앞.
2. 시스템 프롬프트: 작성 지침, 양식, 예시처럼 고정된 긴 텍스트. 그다음.
3. 메시지: 고객사 정보처럼 매번 바뀌는 것. 맨 뒤.

고객명이나 날짜처럼 매번 다른 값을 system 앞부분에 섞으면 캐시가 매번 깨집니다. 우리 CRM 생성기에서 처음 겪은 실수가 이것이었고, 가변 값을 마지막 user 메시지로 옮긴 뒤 적중률이 올라갔습니다. 웹 검색 토글, 속도 설정, tool_choice, effort 변경도 각각 무효 범위가 있으니 운영 중 설정을 바꿀 때 공식 무효화 표를 확인합니다.

비용 계산

가격 페이지의 배수는 세 가지입니다. 5분 캐시 쓰기 1.25배, 1시간 캐시 쓰기 2배, 읽기 0.1배(기본 입력 가격 기준). 5분 캐시는 읽기 한 번, 1시간 캐시는 읽기 두 번이면 본전이 됩니다.

(100만 토큰당 미국 달러)

Sonnet 5에서 2만 토큰짜리 작성 지침을 하루 100번, 5분 간격 이내로 부른다고 합시다. 캐시 없이는 200만 토큰 × 2달러 = 4달러입니다. 5분 캐시를 쓰면 첫 쓰기 2만 토큰 × 2.50달러 = 0.05달러, 나머지 99회 읽기 198만 토큰 × 0.20달러 = 0.396달러로 합계 약 0.45달러입니다. 출력 토큰은 캐싱과 무관하고, 배치 API 50% 할인은 캐싱 배수와 겹쳐 적용됩니다.

유효 기간

기본은 5분이며, 캐시를 읽을 때마다 다시 5분이 연장됩니다. 호출 간격이 그보다 길면 ttl을 "1h"로 지정해 1시간 캐시를 씁니다.

"cache_control": {"type": "ephemeral", "ttl": "1h"}

유효 기간은 응답 끝이 아니라 요청 시작 시점부터 잽니다. 스트리밍에 4분이 걸렸다면 다음 요청은 약 1분 안에 시작해야 5분 캐시를 다시 씁니다. 간격이 긴 예약 잡은 1시간 캐시가 맞고, 쓰기가 2배이므로 두 번 이상 읽을 때만 이득입니다.

적중 여부 확인

응답 usage의 네 값으로 봅니다.

"usage": {
  "input_tokens": 248,
  "cache_creation_input_tokens": 5120,
  "cache_read_input_tokens": 1800,
  "cache_creation": {
    "ephemeral_5m_input_tokens": 148,
    "ephemeral_1h_input_tokens": 100
  }
}

cache_read_input_tokens가 0보다 크면 적중입니다. cache_creation_input_tokens는 새로 기록한 양, input_tokens는 마지막 브레이크포인트 뒤의 캐시되지 않은 양이며 총 입력은 세 값의 합입니다. 두 번째 요청부터 읽기가 계속 0이라면 앞부분 어딘가가 매번 바뀌고 있다는 증거입니다. "캐싱을 넣었다"가 아니라 이 숫자가 검증의 근거입니다.

체크리스트

• 반복되는 앞부분이 모델별 최소 길이 이상인가
• 도구 → 시스템 → 메시지 순서로 고정된 것이 앞에 있는가
• 가변 값이 마지막 메시지에만 있는가
• 호출 간격에 맞춰 5분과 1시간 중 하나를 골랐는가
• 브레이크포인트가 매번 동일한 마지막 블록에 있고 4개 이하인가
• 로그에 cache_read_input_tokens를 남기고 있는가

정리

• 캐싱은 반복되는 앞부분을 0.1배 가격으로 다시 쓰며, 5분 캐시는 읽기 한 번이면 본전입니다.
• 고정된 것을 앞에, 가변 값을 뒤에 두는 것이 원칙의 전부입니다.
• 적중은 cache_read_input_tokens로 확인합니다.

자주 묻는 질문