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

같은 문서를 매 요청마다 다시 보내고 있다면, 매번 그 값을 지불하고 있는 것입니다. 프롬프트 캐싱은 이 반복분을 재사용합니다.

언제 효과가 큰가

• 긴 시스템 프롬프트나 지침을 매 요청에 포함할 때
• 같은 문서·코드베이스에 대해 여러 질문을 할 때
• 도구 정의가 많을 때
• 대화가 길어져 이력이 누적될 때

어떻게 동작하나

프롬프트의 앞에서부터 지정한 지점까지가 캐시 단위가 됩니다. 다음 요청에서 그 부분이 한 글자도 다르지 않으면 캐시가 적중합니다.

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": long_manual,          # 매번 같은 긴 문서
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": question}],  # 매번 달라지는 부분
)

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

캐시는 접두사 단위로 동작합니다. 앞부분이 조금이라도 바뀌면 그 뒤 전부가 무효화됩니다.

흔한 실수는 시스템 프롬프트 첫 줄에 타임스탬프를 넣는 것입니다. 그 순간 캐시는 절대 적중하지 않습니다.

비용 계산

• 캐시 쓰기 — 일반 입력보다 비쌉니다 (최초 1회)
• 캐시 읽기 — 일반 입력보다 훨씬 쌉니다

즉 두 번 이상 재사용되어야 이득입니다. 한 번 쓰고 버릴 프롬프트에 캐싱을 걸면 오히려 손해입니다.

유효 기간

캐시는 일정 시간 동안만 유지되며, 그 안에 다시 쓰이면 갱신됩니다. 요청 간격이 길어 매번 만료된다면 캐싱 효과가 없습니다. 이럴 땐 요청을 묶어서 처리하는 편이 낫습니다.

적중 여부 확인

응답의 사용량 정보로 확인합니다.

print(message.usage.cache_creation_input_tokens)  # 이번에 캐시에 쓴 양
print(message.usage.cache_read_input_tokens)      # 캐시에서 읽은 양

cache_read가 계속 0이면 어딘가에서 접두사가 깨지고 있다는 뜻입니다. 매 요청의 프롬프트를 그대로 덤프해 앞부분을 비교해 보세요.

체크리스트

• [ ] 고정 콘텐츠가 프롬프트 맨 앞에 있는가
• [ ] 앞부분에 매번 바뀌는 값(시각, 랜덤 ID)이 섞이지 않았는가
• [ ] 재사용 횟수가 2회 이상인가
• [ ] cache_read_input_tokens가 실제로 올라가는가