프롬프트 캐싱

매번 똑같이 보내는 긴 프롬프트 앞부분(시스템 프롬프트, 문서, 코드베이스)을 서버가 잠시 저장해 두고, 다음 요청에서 다시 계산하지 않고 꺼내 쓰는 기능이다. 같은 컨텍스트를 반복해서 보내는 챗봇·코딩 에이전트에서 입력 비용과 첫 응답 지연을 크게 줄일 때 쓴다.

앞부분이 길고 자주 반복될수록 효과가 커진다. 한 번만 보내거나 매번 내용이 다른 요청에는 이득이 없다.

앞부분이 똑같아야 캐시된다

캐시는 프롬프트 맨 앞부터 완전히 같은 부분에만 적용된다. 중간에 한 글자라도 바뀌면 그 뒤는 모두 다시 계산한다.

그래서 순서가 핵심이다. 바뀌지 않는 내용을 앞에, 자주 바뀌는 내용을 뒤에 둔다.

시스템 프롬프트 앞쪽에 현재 시각처럼 매번 바뀌는 값을 넣으면 캐시가 매번 깨진다.

Claude는 직접 표시, OpenAI는 자동

Claude API는 캐시할 위치를 직접 정한다. 캐시하고 싶은 블록에 cache_control: {"type": "ephemeral"}를 붙이면 그 지점까지 저장된다. 너무 짧은 프롬프트는 캐시되지 않으며, 최소 길이는 모델에 따라 1,024토큰 이상이다.

OpenAI API는 일정 길이 이상의 프롬프트를 자동으로 캐싱하므로 코드를 고칠 필요가 없다. 다만 앞부분을 고정하는 순서 규칙은 똑같이 지켜야 효과가 난다.

적중 여부는 응답의 usage 항목에서 확인한다.

5분 안에 다시 써야 이득

캐시는 짧게만 유지된다. Claude의 기본 캐시는 약 5분이고, 그 안에 다시 쓰면 유지 시간이 다시 늘어난다. 요청 간격이 길면 캐시가 사라져 저장 비용만 내고 끝날 수 있다.

Claude는 처음 저장할 때 입력 비용을 조금 더 받는다. 그래서 같은 앞부분을 짧은 간격으로 여러 번 다시 보낼 때 붙이고, 한 번만 보내는 요청이나 매번 내용이 다른 일괄 처리에는 붙이지 않는다.

이럴 때 붙인다

적용한 뒤에는 usage에서 캐시 적중 토큰이 실제로 잡히는지 꼭 확인한다. 0으로 나오면 앞부분 어딘가가 요청마다 바뀌고 있다는 뜻이다.