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

요청마다 똑같이 보내는 긴 지시문과 문서를 캐시해 두면 그 부분의 입력 요금이 크게 줄어듭니다. 상담 매뉴얼을 쓰는 챗봇을 예로, 캐시 지점을 정하고 효과를 확인하는 법을 정리했습니다.

단계별 따라하기

1. 1

   캐싱이 줄여 주는 것

   상담 챗봇처럼 긴 지시문과 매뉴얼을 질문마다 함께 보내면, 매번 같은 내용에 입력 요금을 다시 냅니다. 프롬프트 캐싱은 요청의 앞부분을 잠시 저장해 두었다가, 다음 요청의 앞부분이 똑같으면 저장한 것을 다시 씁니다.

   처음 저장할 때(캐시 쓰기)는 기본 입력보다 조금 비싸고, 다시 쓸 때(캐시 읽기)는 훨씬 쌉니다. 출력 요금과 답의 내용은 캐싱을 써도 그대로입니다.

   claude-opus-5-5의 캐싱 관련 가격 (100만 토큰당, 2026년 10월 기준)

   항목	가격	기본 입력 대비
   기본 입력	$4	1배
   캐시 쓰기 (수명 5분)	$5	1.25배
   캐시 쓰기 (수명 1시간)	$8	2배
   캐시 읽기	$0.20	0.05배
   출력	$20	캐싱과 무관

   확인해 보기

   • 캐시 읽기 배율은 모델마다 다릅니다(대부분은 기본 입력의 0.1배). 쓰는 모델의 가격표부터 확인하세요.
2. 2

   바뀌지 않는 내용을 앞에, 바뀌는 내용을 뒤에

   캐시는 요청의 맨 앞부터 한 글자도 다르지 않은 부분만 다시 씁니다. 요청은 tools(도구 정의), system, messages 순서로 이어 붙여 처리되므로, 매뉴얼처럼 바뀌지 않는 내용은 앞에, 고객 질문처럼 매번 바뀌는 내용은 뒤에 둬야 합니다.

   cache_control 표시는 요청마다 똑같은 마지막 블록, 즉 매뉴얼 끝에 붙입니다. 매번 바뀌는 질문에 붙이면 요청마다 새로 저장만 하고 한 번도 다시 쓰지 못합니다.

   흔한 실수는 시스템 프롬프트 맨 앞에 현재 시각이나 사용자 이름을 넣는 것입니다. 앞부분이 매번 달라져 그 뒤의 매뉴얼까지 캐시가 맞지 않습니다.

   상담 챗봇 요청의 구성과 캐시 지점 (예시)

   순서	들어가는 것	캐시
   1. tools	도구 정의 (이 예에서는 없음)	바뀌지 않으면 함께 캐시됨
   2. system	역할 지시 한 줄 + 상담 매뉴얼 (약 2만 토큰)	매뉴얼 블록 끝에 cache_control
   3. messages	고객 질문 (매번 바뀜)	캐시하지 않음

3. 3

   cache_control 붙이기

   system을 문자열 대신 블록 목록으로 쓰면 블록마다 cache_control을 붙일 수 있습니다. 매뉴얼 블록에 {"type": "ephemeral"}을 붙이면 그 블록까지의 앞부분이 캐시됩니다.

   캐시의 기본 수명은 5분이고, 캐시를 읽을 때마다 추가 비용 없이 다시 5분으로 늘어납니다. 요청 간격이 5분보다 길고 1시간보다 짧다면 "ttl": "1h"로 수명을 1시간으로 늘릴 수 있지만, 그때는 쓰기 요금이 기본 입력의 2배라는 점을 함께 따져 보세요.

   상담 매뉴얼(약 2만 토큰)을 system에 넣고 고객 질문에 답하는 Python 코드를 쓰고 있어. 매뉴얼은 바뀌지 않고 질문만 매번 바뀌어.
   매뉴얼 부분을 프롬프트 캐싱으로 다시 쓰도록 anthropic SDK 코드를 짜 줘. 모델은 claude-opus-5-5야.

   매뉴얼 블록 끝에 캐시 지점을 두고, 매번 바뀌는 질문은 그 뒤의 messages에 넣습니다.

   코드 예시복사

   import anthropic client = anthropic.Anthropic() with open("manual.txt", encoding="utf-8") as f: manual = f.read() # 바뀌지 않는 상담 매뉴얼 def ask(question): return client.messages.create( model="claude-opus-5-5", max_tokens=1024, system=[ {"type": "text", "text": "너는 쇼핑몰 상담원이야. 아래 매뉴얼에 근거해서만 답해."}, {"type": "text", "text": manual, "cache_control": {"type": "ephemeral"}}, ], messages=[{"role": "user", "content": question}], )

   system=[{...}, {...}]

   system을 블록 목록으로 쓰면 블록마다 캐시 표시를 붙일 수 있습니다.

   "cache_control": {"type": "ephemeral"}

   도구 정의부터 이 블록까지를 캐시합니다. 기본 수명은 5분입니다.

   messages=[{"role": "user", "content": question}]

   매번 바뀌는 질문은 캐시 지점 뒤에 둡니다.

   확인해 보기

   • 매뉴얼이 몇 토큰인지 client.messages.count_tokens로 미리 재 보세요(토큰 계산은 무료입니다). claude-opus-5-5는 512토큰보다 짧은 앞부분은 캐시하지 않습니다.
4. 4

   usage로 캐시가 맞았는지 확인하기

   캐싱을 쓰면 응답의 usage에서 세 값을 함께 봅니다. cache_creation_input_tokens는 이번에 새로 캐시에 쓴 토큰, cache_read_input_tokens는 캐시에서 읽은 토큰, input_tokens는 마지막 캐시 지점 뒤에 있어 캐시 없이 처리한 토큰입니다.

   세 값을 더하면 실제로 보낸 입력 전체가 됩니다. 아래는 같은 매뉴얼로 질문 세 개를 보낸 예입니다. 세 번째는 10분 뒤에 보내서 캐시 수명이 지나 다시 썼습니다.

   질문 세 개의 usage (예시)

   요청	캐시 쓰기 (creation)	캐시 읽기 (read)	나머지 입력 (input)
   1번째	20,000	0	200
   2번째 (1분 뒤)	0	20,000	180
   3번째 (10분 뒤)	20,000	0	210

   캐싱을 넣었는데 요청할 때마다 cache_creation_input_tokens가 2만쯤 나오고 cache_read_input_tokens는 계속 0이야. 요청은 1분에 몇 번씩 보내고 있어.
   system 첫 블록 맨 앞에는 '현재 시각: 2026-10-20 14:03:12'처럼 요청 시각을 넣고 있어. 원인이 뭘까?

   원인은 첫 블록의 시각입니다. 캐시는 앞에서부터 완전히 같은 부분만 다시 쓰는데, 시각이 요청마다 바뀌어 그 뒤의 매뉴얼까지 매번 다른 앞부분이 됩니다. 그래서 매번 새로 쓰기만 하고 읽지는 못합니다.

   시각은 캐시 지점 뒤, 고객 질문과 같은 메시지로 옮기세요. 그러면 지시문과 매뉴얼이 매번 같아져서 두 번째 요청부터 cache_read_input_tokens에 2만 토큰쯤이 찍힙니다.

   확인해 보기

   • 같은 매뉴얼로 5분 안에 두 번 요청해 두 번째 응답의 cache_read_input_tokens가 0보다 큰지 보세요.
   • creation과 read가 둘 다 0이면 캐시가 아예 일어나지 않은 것으로, 앞부분이 최소 길이보다 짧거나 cache_control이 빠진 경우가 많습니다. creation만 매번 찍히고 read가 0이면 캐시 지점 앞의 내용이 요청마다 달라지는 것입니다.
5. 5

   얼마나 아끼는지 계산하기

   캐시 쓰기는 기본 입력보다 25% 비싸지만, claude-opus-5-5에서는 한 번만 다시 읽어도 그 차이를 넘어섭니다. 같은 앞부분을 자주 다시 보낼수록 아끼는 돈이 커집니다.

   다만 요청 간격이 캐시 수명보다 길면 요청마다 다시 쓰게 되어 오히려 25% 더 냅니다. 드물게 호출되는 기능에는 캐싱이 도움이 안 될 수 있습니다.

   1시간에 100번 요청할 때 (매뉴얼 2만, 질문 200, 답 400토큰, claude-opus-5-5)

   항목	캐싱 없이	캐싱 사용
   매뉴얼 2만 토큰	100번 × $0.08 = $8.00	쓰기 1번 $0.10 + 읽기 99번 × $0.004 = $0.496
   질문 200토큰	$0.08	$0.08
   답 400토큰	$0.80	$0.80
   합계	$8.88	$1.376

   매뉴얼 2만 토큰, 질문 200토큰, 답 400토큰짜리 요청을 1시간에 100번 보내. 요청 간격은 늘 5분보다 짧아.
   claude-opus-5-5 가격(100만 토큰당 입력 $4, 5분 캐시 쓰기 $5, 캐시 읽기 $0.20, 출력 $20)으로 캐싱을 쓸 때와 안 쓸 때의 비용을 계산 과정과 함께 비교해 줘.

   캐싱 없이: 1번에 입력 20,200토큰 × $4 ÷ 1,000,000 = $0.0808, 출력 400토큰 × $20 ÷ 1,000,000 = $0.008로 $0.0888이고, 100번이면 $8.88입니다.

   캐싱 사용: 매뉴얼은 첫 요청에서 한 번 쓰고(20,000 × $5 ÷ 1,000,000 = $0.10) 나머지 99번은 읽습니다(20,000 × $0.20 ÷ 1,000,000 = $0.004씩, 모두 $0.396). 여기에 질문 $0.08과 출력 $0.80을 더하면 $1.376입니다.

   100번 기준 약 84.5% 줄어듭니다. 줄어든 것은 매뉴얼 부분의 입력 요금뿐이고 출력 요금은 그대로입니다.

   확인해 보기

   • 며칠 운영한 뒤 usage 기록에서 cache_read_input_tokens의 합계를 입력 전체와 비교해 보세요. 캐시에서 읽은 비율이 낮다면 2단계의 순서와 요청 간격부터 다시 확인합니다.