Claude 프롬프트 캐싱, 캐시 경계와 비용을 설계하는 법
AI를 활용하여 생성한 이미지입니다.
긴 시스템 지침이나 문서 묶음을 매 요청마다 Claude API에 함께 보내면 입력 토큰 비용과 지연 시간이 커질 수 있어요. 프롬프트 캐싱은 자주 반복되는 입력 일부를 캐시에 저장해 다음 요청에서 다시 계산하는 양을 줄이는 방식입니다. 중요한 건 기능을 켜는 한 줄보다 어떤 내용을 캐시할지와 캐시 경계를 어디에 둘지예요.[1]
캐시할 내용과 매번 바꿀 내용을 나눠요
| 블록 | 캐시 적합성 | 이유 |
|---|---|---|
| 역할·출력 규칙 | 높음 | 여러 요청에서 내용이 거의 같아요 |
| 제품 설명서·내부 문서 | 높음 | 문서가 바뀔 때만 캐시를 갱신하면 돼요 |
| 사용자 질문 | 낮음 | 호출마다 달라져 재사용률이 낮아요 |
| 현재 시각·요청 ID | 낮음 | 앞쪽에 넣으면 매번 캐시가 깨질 수 있어요 |
고정 지침과 문서가 프롬프트 앞부분에 있고, 질문과 현재 상태가 뒤에 오도록 배열하는 편이 일반적으로 유리해요. 매 요청마다 바뀌는 값을 고정 블록 안에 섞으면 캐시 적중률을 스스로 낮출 수 있습니다.
캐시 경계는 메시지 구조로 설계해요
Claude의 프롬프트 캐싱은 메시지 내용의 특정 지점에 캐시 제어를 두는 방식으로 사용합니다. 문서 전체를 한 덩어리로 넣기보다 시스템 지침, 참고 문서, 대화 맥락을 구분하고 어느 블록까지 재사용할지 명시하는 편이 관리하기 쉬워요.[1]
예를 들어 시스템 지침과 제품 매뉴얼은 캐시 대상으로 두고, 사용자 질문은 매번 새로 보냅니다. 문서가 수정되면 문서 버전이나 해시를 애플리케이션에서 관리해 변경 시 새 캐시가 만들어지는지 확인해야 해요. “캐시가 있을 것”이라고 추정하지 말고 응답 사용량 필드에서 읽기와 쓰기 토큰을 구분해 관찰하세요.
첫 호출과 반복 호출의 비용을 따로 봐요
캐시를 처음 만드는 호출에는 캐시 쓰기 입력이 발생하고, 이후 적중한 요청에는 캐시 읽기 입력이 발생해요. 따라서 호출이 한두 번뿐인 작업은 캐시가 오히려 이득이 없을 수 있습니다. 같은 고정 문맥을 얼마나 자주 재사용하는지, 문맥이 얼마나 큰지, 캐시 유지 시간이 충분한지를 함께 계산해야 해요.[1]
| 호출 패턴 | 설계 판단 | 측정할 값 |
|---|---|---|
| 긴 문서 1회 요약 | 캐시보다 일반 요청 비교 | 전체 입력 토큰과 지연 |
| 짧은 시간에 반복 질의 | 캐시 후보 | 캐시 읽기 비율과 총비용 |
| 문서가 자주 변경 | 캐시 경계를 작게 설정 | 재캐시 빈도와 문서 버전 |
| 여러 사용자 공용 지침 | 고정 지침을 앞에 배치 | 동시 호출의 적중률 |
호출 순서가 적중률을 좌우해요
- 고정 시스템 지침과 거의 변하지 않는 참고 자료를 준비해요.
- 캐시할 마지막 블록에 캐시 제어를 넣어요.
- 사용자 질문과 요청별 변수는 캐시 경계 뒤에 둬요.
- 첫 요청의 사용량에서 캐시 쓰기가 발생했는지 확인해요.
- 같은 문맥으로 두 번째 요청을 보내 캐시 읽기가 증가하는지 확인해요.
- 문서 버전을 바꾼 뒤 이전 캐시가 계속 재사용되지 않는지 확인해요.
테스트에서는 질문 내용만 바꾸고 고정 문서와 시스템 지침은 그대로 두는 것이 좋아요. 모델, 주요 파라미터, 메시지 순서까지 바꾸면 캐시 효과와 다른 변수를 구분하기 어려워집니다.
짧은 문맥에 캐시를 붙이지 않는 이유
캐시에는 최소 입력 길이와 만료 조건이 있고, 캐시 쓰기와 읽기에는 일반 입력과 다른 과금 규칙이 적용될 수 있어요. 짧은 프롬프트는 저장할 이점보다 제어 복잡도가 커질 수 있습니다. Anthropic은 프롬프트 캐싱 문서에서 지원 조건과 캐시 유지 시간을 모델·기능 기준으로 안내하므로, 모델을 바꿀 때 같은 비용 가정을 그대로 복사하면 안 돼요.[1]
또한 캐시를 쓴다고 출력 토큰 비용이나 모델 추론 비용 전체가 사라지는 것은 아니에요. 비용표를 볼 때 입력 캐시 쓰기, 캐시 읽기, 일반 입력, 출력 토큰을 분리해서 계산하세요. 공식 가격이 바뀔 수 있는 서비스라면 운영 대시보드에 단가를 하드코딩하지 않는 편이 안전합니다.
실패할 때 점검할 로그
| 관찰 결과 | 가능한 원인 | 다음 행동 |
|---|---|---|
| 캐시 읽기가 계속 0 | 경계 앞 내용이 매번 달라짐 | 동적 값의 위치와 메시지 순서 비교 |
| 캐시 쓰기만 반복 | TTL 만료 또는 문서 변경 | 호출 간격·문서 버전 기록 |
| 비용이 줄지 않음 | 고정 문맥이 짧거나 호출 횟수 부족 | 캐시 적용 전후 총비용 비교 |
| 답변이 달라짐 | 문맥·모델·도구 설정 변화 | 캐시와 품질 평가를 별도로 비교 |
캐시 적중 여부만 보면 안 돼요. 같은 평가 질문 세트를 만들어 답변 품질, 지연, 입력 비용을 함께 비교해야 실제로 이득인지 알 수 있습니다. 특히 문서 버전이 바뀌었는데도 오래된 내용이 답에 반영된다면 캐시보다 애플리케이션의 문서 교체 로직을 먼저 의심하세요.
되돌리는 방법과 비추천 상황
문제 원인을 찾는 동안에는 캐시 제어를 제거하거나 캐시하지 않는 짧은 문맥으로 요청을 보내 기준값을 만들 수 있어요. 이후 같은 입력을 캐시한 요청과 비교하면 품질 차이와 비용 차이를 분리할 수 있습니다. 실시간 데이터가 매번 크게 바뀌거나 호출량이 적고, 요청마다 민감한 문서가 달라지는 작업이라면 캐싱을 억지로 넣지 않는 편이 낫습니다.
AI API 요청이 거절될 때의 재시도 규칙은 캐시와 별개예요. rate limit과 429 재시도 확인법처럼 실패 요청을 무한 반복하지 않도록 백오프와 최대 재시도 횟수도 따로 정해 두세요.
판단 기준
프롬프트 캐싱은 “항상 켜면 좋은 최적화”가 아니에요. 긴 고정 문맥을 짧은 시간에 여러 번 재사용하고, 호출 사용량에서 실제 캐시 읽기가 확인될 때 효과를 기대할 수 있습니다. 캐시 경계를 고정 지침과 문서 뒤에 두고 동적 질문을 뒤로 보내는 설계부터 시작한 뒤, 모델별 공식 조건과 실제 사용량을 기준으로 유지 여부를 결정하세요.[1]
