프롬프트 캐싱
입력 요금의 일부만으로 고정된 접두사를 다시 읽으세요 — 캐시할 대상과 제외할 대상, 작동 여부를 확인하는 방법.
프롬프트 캐싱은 요청의 접두 부분을 저장하여 같은 접두 부분을 공유하는 후속 호출에 더 낮은 입력 요금을 적용합니다. 시스템 프롬프트, 도구 스키마, 질문 대상 문서처럼 길고 고정된 도입부가 있는 경우 비용 대비 효과가 가장 큰 변경입니다.
좋은 캐시 대상의 조건
| 적합 | 이유 |
|---|---|
| 시스템 프롬프트 | 세션 내 모든 호출에서 바이트 단위로 동일함 |
| 도구 / 함수 정의 | 에이전트 실행 전체에 걸쳐 일정하며 대개 분량이 큼 |
| 반복해서 질문하는 대상 문서 | 한 번 업로드하고 여러 번 질문 |
| 퓨샷 예시 | 고정되어 있으며 대개 김 |
| 부적합 | 이유 |
|---|---|
| 사용자의 최신 메시지 | 매번 달라 캐시 적중이 발생하지 않음 |
| 앞부분에 타임스탬프나 요청 ID가 있는 콘텐츠 | 접두 부분의 앞쪽에서 바이트 하나만 바뀌어도 그 뒤의 모든 내용이 무효화됨 |
| 짧은 프롬프트 | 캐시 가능한 최소 길이보다 짧아 얻을 이점이 없음 |
접두 부분 표시
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"system": [{
"type": "text",
"text": "<long stable instructions...>",
"cache_control": {"type": "ephemeral"}
}],
"messages": [{"role": "user", "content": "Question that changes every call"}]
}표시된 블록까지의 모든 내용이 해당 블록을 포함하여 캐시되는 접두 부분이 됩니다. 순서가 중요합니다. 고정된 콘텐츠를 앞에, 자주 바뀌는 콘텐츠를 뒤에 배치하세요.
작동 여부 확인
다음 항목을 확인하세요 usage 객체. 캐시가 적중하면 토큰은 일반 입력이 아닌 캐시 읽기 항목에 보고됩니다. 반복 호출에서도 캐시 읽기가 계속 0이라면 접두 부분이 실제로 동일하지 않은 것입니다. 흔한 원인은 도입부에 있는 타임스탬프, 세션 ID, 또는 비결정적인 JSON 키 순서입니다.
캐시할 콘텐츠를 결정적인 방식으로 직렬화하세요.
json.dumps(obj) 없이 sort_keys=True 실행할 때마다 키 순서를 바꿀 수 있어 바이트가 달라지고, 그 결과 매번 캐시 적중 기회를 알게 모르게 잃게 됩니다.가장 중요한 활용 사례
에이전트 도구는 매 턴마다 동일한 시스템 프롬프트와 동일한 도구 스키마를 다시 전송합니다. 50턴 세션에서는 캐싱을 사용하지 않으면 이 서두에 대해 50번 비용을 지불하지만, 캐싱을 사용하면 대략 한 번만 지불합니다.