1. 개요
사내 챗봇이나 에이전트를 붙여 달라는 요청을 받으면 기능 이야기보다 비용 이야기가 먼저 나올 때가 많습니다. 예전에 토큰 계산 스크립트를 정리한 글에서 캐싱 부분은 슬쩍 넘겼던 기억이 있어서, 이번에는 한 번 제대로 적어 두려고 합니다.
결론부터 말씀드리면, 반복되는 프롬프트 앞부분에 cache_control을 달면 그 구간은 캐시 읽기 요금인 기본 입력 단가의 0.1배로 청구됩니다. 5분 캐시 쓰기가 1.25배이므로 한 번만 읽어도 이득이 나고, 1시간 캐시(2배)는 두 번 읽으면 이득이 납니다. 적용이 됐는지는 응답의 usage.cache_creation_input_tokens와 usage.cache_read_input_tokens 두 값을 함께 보고 판정합니다.
문서 검색을 붙인 챗봇이나 도구를 여러 개 물린 에이전트를 운영해 보면, 청구서에서 제일 두꺼운 항목이 출력이 아니라 입력 토큰이 되는 구간을 만나게 됩니다. 매 요청마다 똑같은 시스템 프롬프트와 똑같은 도구 스키마, 똑같은 사규 문서가 앞에 다시 붙기 때문입니다. 2만 토큰짜리 시스템 프롬프트를 붙인 챗봇에 질문을 100번 던지면 같은 2만 토큰이 100번 다시 계산되어 200만 토큰으로 청구됩니다.
진단은 응답 usage를 열어 캐시 관련 토큰이 잡히는지 보는 것에서 시작합니다. 해결은 최상위 cache_control 한 줄로 자동 캐싱을 켜는 방법과, 명시적 브레이크포인트를 최대 4개까지 직접 배치하는 방법 두 방향입니다. 아래에서 요금 구조, 브레이크포인트 배치, 최소 토큰 조건, TTL 선택, 적중 확인과 청구 절감 측정을 차례로 살펴보겠습니다.
2. 프롬프트 캐싱이란? 요금은 어떻게 매겨질까?
프롬프트 캐싱은 프롬프트의 앞부분(프리픽스)을 이미 처리한 상태로 저장해 두고, 다음 요청에서 그 부분을 다시 계산하지 않고 꺼내 쓰는 기능입니다. 저장 단위는 "내가 지정한 블록까지의 프리픽스 전체를 해시한 것" 하나입니다.
그래서 앞부분이 바이트 단위로 완전히 같아야 맞습니다. 공백 한 칸 차이도 다른 캐시로 취급됩니다.
지정 문법은 캐시하고 싶은 콘텐츠 블록에 필드를 하나 붙이는 것입니다. ttl은 캐시가 살아 있는 시간을 뜻하는 필드로 "5m"과 "1h" 두 값을 받습니다. 생략하거나 "5m"을 주면 5분, "1h"를 주면 1시간입니다.
"cache_control": {"type": "ephemeral"}
"cache_control": {"type": "ephemeral", "ttl": "1h"}
요금은 기본 입력 단가에 배수로 붙습니다. 이 배수는 Batch API 할인이나 데이터 레지던시 배수와 곱해져서 함께 적용됩니다.
- 5분 캐시 쓰기: 기본 입력 단가의 1.25배
- 1시간 캐시 쓰기: 기본 입력 단가의 2배
- 캐시 읽기(적중, 갱신): 기본 입력 단가의 0.1배
모델별 실제 단가는 이렇습니다(1M 토큰 기준).
- Claude Opus 5: 입력 $5, 5분 쓰기 $6.25, 1시간 쓰기 $10, 캐시 읽기 $0.50, 출력 $25
- Claude Sonnet 5(2026-08-31까지 도입 요금): 입력 $2, 5분 쓰기 $2.50, 1시간 쓰기 $4, 캐시 읽기 $0.20, 출력 $10. 2026-09-01부터는 입력 $3, 5분 쓰기 $3.75, 1시간 쓰기 $6, 캐시 읽기 $0.30, 출력 $15
- Claude Haiku 4.5: 입력 $1, 5분 쓰기 $1.25, 1시간 쓰기 $2, 캐시 읽기 $0.10, 출력 $5
캐시할 수 있는 대상은 tools 배열의 도구 정의, system 배열의 콘텐츠 블록, messages 안의 텍스트, 이미지, 문서, tool_use, tool_result 블록입니다. 확장 사고(thinking) 블록은 cache_control을 직접 붙일 수 없지만, 이전 어시스턴트 턴에 포함되어 있으면 다른 콘텐츠와 함께 캐시됩니다.
3. 가장 쉬운 시작은 최상위 cache_control 한 줄입니다
요청 최상위에 cache_control을 한 번 넣으면 마지막 캐시 가능 블록에 브레이크포인트가 자동으로 붙고, 대화가 길어질 때 위치도 알아서 관리됩니다. 대화형 서비스라면 여기서 시작하는 것을 추천합니다.
curl -sS https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"system": "You are an AI assistant analyzing a large document. <document>...</document>",
"messages": [{"role": "user", "content": "Summarize section 1."}]
}' | jq '.usage'
자동 캐싱도 명시적 브레이크포인트와 같은 슬롯을 하나 씁니다. 즉 최상위 cache_control을 켜면 남는 명시적 슬롯은 3개입니다.
⚠️ 주의 명시적 브레이크포인트를 이미 4개 쓴 상태에서 최상위 cache_control까지 함께 켜면 조용히 무시되지 않고 API가 400 에러를 반환합니다. 두 방식을 섞으실 때는 명시적 브레이크포인트를 3개 이하로 유지해 주세요.
4. 브레이크포인트 4개를 어디에 둘까요?
명시적 브레이크포인트는 한 요청에 최대 4개입니다. 배치를 이해하려면 세 가지 동작을 알아 두시면 좋습니다.
- 쓰기는 브레이크포인트에서만 일어납니다.
cache_control을 단 위치까지의 프리픽스 해시 하나만 저장됩니다. 그 앞 위치들에는 아무것도 기록되지 않습니다. - 읽기는 뒤로 거슬러 찾습니다. 내 브레이크포인트 위치의 해시가 없으면 한 블록씩 앞으로 물러나며 저장된 항목을 찾습니다.
- 탐색 창은 브레이크포인트당 20블록입니다(브레이크포인트 자신이 1번). 그 안에서 못 찾으면 멈춥니다.
4.1 💡 배치 원칙
캐시는 tools → system → messages 순서를 엄격히 따릅니다. 앞 단계가 바뀌면 그 뒤는 전부 무효가 됩니다. 그래서 변하지 않는 것을 앞에, 매번 바뀌는 것을 뒤에 두는 배치가 전부입니다.
실무에서 쓰는 배치는 이런 모양입니다.
- 슬롯 1:
tools배열의 마지막 도구 정의. 도구 목록은 배포 사이에 거의 안 바뀌므로 1시간 TTL 후보입니다. - 슬롯 2:
system의 고정 지시문 블록 끝. - 슬롯 3: 세션 전체가 공유하는 대용량 문서(사규, 스키마 덤프, API 명세) 블록 끝.
- 슬롯 4: 대화 히스토리에서 더 이상 바뀌지 않는 마지막 지점. 턴이 늘어나면 이 슬롯만 뒤로 옮깁니다.
1시간 TTL과 5분 TTL을 섞을 때는 긴 TTL 항목이 짧은 TTL 항목보다 앞에 와야 합니다. 위 순서가 그 제약과 자연히 맞습니다.
4.2 RAG로 검색해 온 청크는 브레이크포인트 뒤에 둡니다
여기서 한 번 걸리게 됩니다. RAG 파이프라인을 붙이면 검색 결과가 덩치가 크니 캐시하고 싶어지는데, 질문마다 검색 결과가 달라집니다.
매 요청 바뀌는 블록에 cache_control을 달면 프리픽스 해시가 매번 달라져 읽기는 0이고 쓰기만 반복됩니다. 쓰기는 1.25배이므로 캐싱을 안 켠 것보다 비싸집니다.
그래서 system에는 질문과 무관하게 고정된 지시문과 공용 문서만 넣고 여기에 브레이크포인트를 두시고, 질문별로 뽑아온 청크는 브레이크포인트 뒤인 첫 user 메시지에 넣어 보세요.
{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are a support agent. Follow the policy below.\n<policy>...</policy>",
"cache_control": {"type": "ephemeral", "ttl": "1h"}
}
],
"messages": [
{
"role": "user",
"content": "<retrieved>...검색된 청크...</retrieved>\n\nQ: 환불 규정이 어떻게 되나요?"
}
]
}
검색 코퍼스 자체가 요청 사이에 공유될 만큼 작다면(예: 문서 세트가 고정된 제품 매뉴얼 봇) 코퍼스를 system에 넣고 캐시하는 쪽이 훨씬 이득입니다. 판단 기준은 "이 블록이 다음 요청에서도 바이트 단위로 같은가" 하나입니다.
5. 최소 토큰 조건을 넘겼나요?
캐시 가능한 최소 프리픽스 길이가 모델마다 다릅니다. 이 값을 못 넘기면 cache_control을 붙였어도 캐시되지 않고, 에러도 나지 않습니다. 처음 적용할 때 자주 발견되는 원인 중 하나이니 꼭 확인해 보세요.
- Claude Opus 5: 512 토큰
- Claude Opus 4.8: 1,024 토큰
- Claude Opus 4.7: 2,048 토큰
- Claude Opus 4.6, 4.5: 4,096 토큰
- Claude Sonnet 5, Sonnet 4.6, Sonnet 4.5: 1,024 토큰
- Claude Haiku 4.5: 4,096 토큰
예를 들어 Haiku 4.5로 짧은 분류 프롬프트를 캐싱하려는 경우가 여기에 걸립니다. 4,096 토큰이 문턱이라 1,500 토큰짜리 시스템 프롬프트는 캐시 대상이 되지 않습니다. 이때는 모델을 바꾸거나, 캐싱 대신 프롬프트 자체를 줄이는 방향이 맞습니다.
⚠️ 주의 Claude 4.7 이후 모델은 새 토크나이저를 쓰고, 같은 텍스트에서 토큰이 약 30% 더 나올 수 있습니다. 정확한 증가폭은 내용에 따라 다릅니다. 모델을 갈아탈 때 최소 토큰 판정과 청구 비교를 이전 모델 기준으로 하면 어긋나니 함께 점검해 보시길 바랍니다.
6. 5분 TTL과 1시간 TTL 중 무엇을 쓸까요?
5분 TTL은 기본값이고, 갱신에 추가 비용이 없습니다. 5분 안에 계속 요청이 들어오는 트래픽이면 사실상 계속 살아 있습니다. 대화형 챗봇처럼 사용자가 연달아 질문하는 패턴은 5분으로 충분합니다.
1시간 TTL은 쓰기가 2배라서 두 번 이상 읽어야 본전입니다. 요청 간격이 5분보다 벌어지는 워크로드에 쓰시면 됩니다. 배치 처리 사이의 공백, 새벽 시간대 트래픽 공백, 몇 분에 한 번씩 도는 크론 잡 같은 경우입니다.
둘을 섞으면 청구는 위치 기준으로 계산됩니다. 적중한 가장 뒤 위치를 A, A 뒤에 있는 가장 뒤쪽 1시간 브레이크포인트를 B(없으면 A와 동일), 마지막 브레이크포인트를 C라고 하면 A까지는 캐시 읽기, B에서 A까지 구간은 1시간 쓰기, C에서 B까지 구간은 5분 쓰기로 청구됩니다.
7. usage 필드로 캐시 적중을 확인합니다
캐싱이 먹었는지 확인하는 가장 믿을 만한 방법은 응답 usage입니다. 스트리밍이면 message_start 이벤트에 실려 옵니다.
curl -sS https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data @req.json \
| jq '.usage | {input_tokens, cache_creation_input_tokens, cache_read_input_tokens, cache_creation}'
첫 요청(캐시 쓰기)의 출력은 이런 형태입니다. 토큰 숫자는 각자 프롬프트 크기에 따라 다릅니다.
{
"input_tokens": 512,
"cache_creation_input_tokens": 40960,
"cache_read_input_tokens": 0,
"cache_creation": {
"ephemeral_5m_input_tokens": 40960,
"ephemeral_1h_input_tokens": 0
}
}
같은 프리픽스로 두 번째 요청을 보내면 쓰기가 0으로 떨어지고 읽기로 옮겨갑니다.
{
"input_tokens": 528,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 40960,
"cache_creation": {
"ephemeral_5m_input_tokens": 0,
"ephemeral_1h_input_tokens": 0
}
}
읽기 토큰이 이렇게 잡히면 정상적으로 작동하고 있다는 뜻입니다!
판정할 때는 쓰기와 읽기 두 필드를 같이 보셔야 합니다. 읽기 하나만 보면 정상적인 첫 요청(쓰기만 잡히고 읽기는 0)과 최소 토큰 미달로 캐시가 아예 안 만들어진 경우(둘 다 0)를 구분할 수 없습니다. cache_creation_input_tokens와 cache_read_input_tokens가 모두 0이면 캐시 자체가 생기지 않은 것이고, 쓰기가 잡혔는데 다음 요청에서도 읽기가 계속 0이면 프리픽스가 매번 달라지고 있다는 신호입니다.
여기서 input_tokens는 마지막 브레이크포인트 이후의 토큰, 즉 캐시 대상이 아닌 부분만 센 값입니다. 전체 입력은 세 값을 더해서 구합니다.
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens
두 번째 요청에서도 읽기가 0에 머무른다면 다음 절의 진단 베타로 넘어가 보겠습니다.
8. 캐시가 안 맞을 때: cache diagnostics 베타로 원인 짚기
적중률이 0인데 원인을 못 찾겠으면 캐시 진단 베타를 켜 보세요. 앞 응답의 id를 다음 요청에 넘기면 API가 두 요청의 지문을 비교해 처음 갈라진 지점을 알려줍니다. 베타 헤더는 anthropic-beta: cache-diagnosis-2026-04-07이고, Claude API 전용입니다.
response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: cache-diagnosis-2026-04-07" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"system": "You are an AI assistant analyzing a large document. <document>...</document>",
"messages": [{"role": "user", "content": "Summarize section 1."}],
"diagnostics": {"previous_message_id": null}
}')
message_id=$(jq -r '.id' <<< "$response")
다음 턴에서 diagnostics.previous_message_id에 이 id를 넣어 보내면 응답에 진단이 붙습니다. 시스템 프롬프트에 요청 시각을 끼워 넣은 경우의 전형적인 응답 모양은 이렇습니다. 실제 응답에는 필드가 더 많고, 아래는 공식 예시에서 일부 필드만 발췌한 것입니다.
{
"id": "msg_01Xyz...",
"type": "message",
"role": "assistant",
"content": [{ "type": "text", "text": "..." }],
"usage": {
"input_tokens": 42,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 41850,
"output_tokens": 210
},
"diagnostics": {
"cache_miss_reason": {
"type": "system_changed",
"cache_missed_input_tokens": 41850
}
}
}
cache_miss_reason.type이 가리키는 원인과 대응은 이렇게 나뉩니다.
model_changed: 라우터나 폴백이 다른 모델을 골랐습니다. 캐시는 모델 단위이므로 한 대화 안에서는 모델을 고정하세요.system_changed: 시스템 프롬프트에 시각, 요청 ID 같은 값이 들어갔습니다. 시스템 프롬프트를 상수로 만들고 동적 값은 브레이크포인트 뒤user메시지로 옮기세요.tools_changed: 도구가 추가, 삭제, 재정렬되었거나input_schemaJSON 직렬화가 비결정적입니다. Go나 Swift처럼 맵 키 순서가 흔들리는 언어에서 자주 나옵니다. 키를 정렬해 직렬화하세요.messages_changed: 히스토리를 잘라내거나 고쳤습니다. 히스토리는 append-only로 다루고, 어시스턴트content와tool_result는 받은 그대로 되돌려 보내세요.previous_message_not_found: 앞 요청에 베타 헤더가 없었거나 워크스페이스가 다르거나 시간이 너무 지났습니다. 내 요청이 바뀌었다는 증거는 아닙니다.unavailable: 모델, 시스템, 도구는 같은데tool_choice,thinking,context_management,output_config,output_format, 활성 베타 헤더 집합 같은 다른 파라미터가 달라진 경우가 포함됩니다. 캐시된 대화가 사는 동안 이 파라미터들을 고정하세요.
진단 결과와 usage를 함께 읽으면 판정이 갈립니다. diagnostics가 null인데 읽기 토큰이 0에 가깝다면 내 요청은 같았고 캐시 항목이 만료된 것입니다. 이럴 때 손댈 곳은 프롬프트가 아니라 TTL입니다. 반대로 *_changed가 떴으면 내 쪽 버그입니다.
진단 없이 눈으로 잡을 수 있는 원인도 몇 개 있습니다. 이미지를 추가하거나 제거하면 메시지 캐시가 무효화되고, tool_choice를 바꾸는 것도 같습니다. 대화가 길어져 이전 브레이크포인트가 20블록 탐색 창 밖으로 밀려나는 경우에는 브레이크포인트를 여러 개 두어 해결하시면 됩니다.
9. 계산으로 절감폭을 먼저 확인해 보세요
적용 전에 산수로 크기를 가늠해 두면 측정할 때 헷갈리지 않습니다. Sonnet 5의 도입 요금(입력 $2, 5분 쓰기 $2.50, 캐시 읽기 $0.20)에서 고정 프리픽스 40,000 토큰, 요청별 질문 500 토큰, 요청 100건을 가정해 보겠습니다.
캐싱을 안 쓰면 매 요청 40,500 토큰이 기본 입력으로 청구됩니다.
100 x 40,500 x $2 / 1,000,000 = $8.10
캐싱을 켜서 첫 요청만 쓰기, 나머지 99건이 읽기로 잡히면 이렇게 쪼개집니다.
캐시 쓰기 : 40,000 x $2.50 / 1,000,000 = $0.100 캐시 읽기 : 99 x 40,000 x $0.20 / 1,000,000 = $0.792 비캐시 입력 : 100 x 500 x $2 / 1,000,000 = $0.100 합계 = $0.992
입력 비용이 $8.10에서 약 $0.99로, 88% 정도 줄어듭니다. 출력 비용은 양쪽 모두 그대로입니다. 배수 구조가 단가와 무관하게 같으므로 모델이나 요금 개정으로 절대 금액이 바뀌어도 절감 비율은 비슷하게 나옵니다.
지연도 같이 줄어듭니다. 다시 계산하지 않는 프리픽스만큼 첫 토큰까지 걸리는 시간이 짧아지는데, 감소폭은 프리픽스 크기와 모델에 따라 다릅니다. 프리픽스가 수만 토큰대라면 체감이 크고, 수천 토큰대면 미미할 수 있습니다. 실제 값은 캐시 쓰기 요청과 읽기 요청의 응답 시간을 각각 재서 비교해 보시길 바랍니다.
10. 실제 청구 절감은 Usage/Cost Admin API로 확인합니다
응답 usage는 요청 단위라서 "이번 달 청구가 실제로 줄었나"에는 답하지 못합니다. 조직 단위 집계는 Usage and Cost Admin API를 쓰시면 됩니다. 일반 API 키가 아니라 Admin API 키(sk-ant-admin01-...)가 필요합니다.
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\ starting_at=2026-07-22T00:00:00Z&\ ending_at=2026-07-29T00:00:00Z&\ group_by[]=model&\ bucket_width=1d" \ -H "anthropic-version: 2023-06-01" \ -H "x-api-key: $ANTHROPIC_ADMIN_KEY"
응답의 각 결과 항목은 토큰을 네 갈래로 나눠 줍니다. 아래는 문서에 실린 응답 예시에서 결과 항목 하나만 발췌한 것으로, 구조를 그대로 보여줍니다.
{
"cache_creation": {
"ephemeral_1h_input_tokens": 1000,
"ephemeral_5m_input_tokens": 500
},
"cache_read_input_tokens": 200,
"context_window": "0-200k",
"model": "claude-opus-4-6",
"output_tokens": 500,
"service_tier": "standard",
"uncached_input_tokens": 1500
}
여기서 캐시 적중률을 뽑습니다. 분모는 세 종류 입력 토큰의 합입니다.
curl -sS "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-07-22T00:00:00Z&ending_at=2026-07-29T00:00:00Z&\
group_by[]=model&bucket_width=1d" \
-H "anthropic-version: 2023-06-01" \
-H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
| jq -r '.data[] | .starting_at as $d | .results[]
| (.cache_creation.ephemeral_5m_input_tokens + .cache_creation.ephemeral_1h_input_tokens) as $w
| [ $d, .model,
.uncached_input_tokens, $w, .cache_read_input_tokens,
(.cache_read_input_tokens / (.uncached_input_tokens + $w + .cache_read_input_tokens) * 100 | floor)
] | @tsv'
마지막 열이 캐시 읽기 비율입니다. 적용 전후 같은 기간 길이로 뽑아 비교하면 배포 효과가 바로 보입니다. 실제 청구 금액이 필요하면 /v1/organizations/cost_report를 쓰세요. 이쪽은 일 단위(1d) 집계만 지원하고, 금액은 최소 단위(센트) 십진 문자열로 옵니다.
curl "https://api.anthropic.com/v1/organizations/cost_report?\ starting_at=2026-07-01T00:00:00Z&\ ending_at=2026-07-31T00:00:00Z&\ group_by[]=workspace_id&\ group_by[]=description" \ -H "anthropic-version: 2023-06-01" \ -H "x-api-key: $ANTHROPIC_ADMIN_KEY"
⚠️ 주의 데이터는 요청 완료 후 5분쯤 뒤에 반영되고 더 늦어질 수도 있으니 배포 직후 숫자로 판단하지 마세요. 그리고 Priority Tier 비용은 cost 엔드포인트에 포함되지 않아 usage 쪽으로 확인해야 합니다.
11. 트래픽 전에 캐시를 미리 채워두기
공유 시스템 프롬프트를 쓰는 서비스라면 첫 사용자가 캐시 쓰기 비용과 지연을 혼자 부담하게 됩니다. max_tokens: 0으로 출력 없이 캐시만 채우는 요청을 미리 던져 이걸 피할 수 있습니다.
curl -sS https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-5",
"max_tokens": 0,
"system": [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "warmup"}]
}' | jq '{stop_reason, content, usage}'
stop_reason은 "max_tokens", content는 빈 배열로 돌아오고 출력 토큰은 0으로 청구됩니다. 캐시가 아직 없었다면 쓰기 비용은 발생하니 cache_creation_input_tokens로 확인해 보세요.
💡 팁 cache_control은 공유되는 부분(시스템 프롬프트, 도구 정의)에 달아야 하고, 자리 채우기용 user 메시지에 달면 안 됩니다. 그리고 뒤이어 올 실제 요청과 thinking 설정, output_config.effort를 같게 맞춰야 프리픽스가 어긋나지 않습니다.
max_tokens: 0은 stream: true, 확장 사고 활성화, 구조화 출력 활성화, tool_choice가 "tool"이나 "any"인 경우, Message Batches 안에서는 거부됩니다.
12. 정리
적용 순서를 다시 짧게 적어 보면 이렇습니다. 대화형 서비스는 최상위 cache_control 한 줄로 시작하세요. 도구 정의와 대용량 고정 문서가 있는 에이전트나 RAG 파이프라인은 명시적 브레이크포인트로 넘어가서, 안 바뀌는 것을 앞에 몰고 매 요청 바뀌는 값은 마지막 브레이크포인트 뒤로 내리시면 됩니다. 모델별 최소 토큰을 못 넘기면 조용히 캐시되지 않으니 usage.cache_creation_input_tokens와 usage.cache_read_input_tokens를 함께 보고 반드시 확인해 보세요.
요청 간격이 5분 안이면 기본 TTL로 두고, 그보다 벌어지면 1시간 TTL을 앞쪽 슬롯에 붙이세요. 적중률이 안 오르면 cache-diagnosis-2026-04-07 베타로 갈라진 지점을 특정하고, 배포 효과는 Usage API의 cache_read_input_tokens 비율과 Cost API 금액으로 확인하시면 됩니다. 여기까지 하면 반복 프리픽스가 큰 워크로드에서 입력 비용을 몇 분의 일로 줄일 수 있습니다.
단가와 최소 토큰 값은 모델이 추가되면서 바뀔 수 있습니다. 계산 스크립트를 붙일 때는 값을 상수로 박아두지 말고 공식 요금 문서를 기준으로 갱신하는 방식을 추천합니다. 오늘 첫 브레이크포인트 하나만 제대로 꽂아도 청구서가 눈에 띄게 달라질 겁니다. 편안한 작업 되시길 바랍니다!