Claude API 프롬프트 캐싱으로 비용 줄이기거는 위치와 유지 시간

캐시는 앞부분부터 맞춰 봅니다

캐시(자주 쓰는 내용을 가까운 데 잠시 올려 두는 자리)는 요청을 앞부분부터 비교합니다. 표시한 지점까지 한 글자도 다르지 않아야 저장본을 꺼내 씁니다. 이 표시를 캐시 중단점(breakpoint)이라고 부릅니다.

비교하는 순서는 도구 정의(tools), 시스템 지시문(system), 대화 내용(messages) 차례입니다. 앞쪽 한 군데가 바뀌면 그 뒤는 모두 새로 읽습니다. 책의 1장을 고쳤다면 2장 메모도 다시 써야 하는 이치와 같습니다.

표시는 어디에 다나

원칙은 하나입니다. 매번 바뀌는 내용 바로 앞, 마지막으로 변하지 않는 부분에 표시를 답니다. 요청 시각처럼 매번 달라지는 내용에 표시를 달면 저장본과 영영 맞지 않습니다.

규정집을 붙여 두고 질문만 바꿔 묻는 요청이라면 시스템 지시문에 직접 표시를 다세요. system을 아래처럼 블록 목록으로 쓰고, 그 안에 cache_control을 넣습니다. 이런 표시는 한 요청에 최대 4개까지 달 수 있습니다.

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "(매번 똑같이 보내는 긴 지시문과 자료)",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [
    {"role": "user", "content": "(이번에 물어볼 질문)"}
  ]
}

시스템 지시문 블록 안의 cache_control이 캐싱을 켜는 부분입니다. ephemeral은 "잠깐 보관"이라는 뜻의 이름표로 보면 됩니다. 질문이 바뀌어도 표시까지는 그대로라 두 번째 요청부터 저장본을 읽습니다.

요청 맨 위에 "cache_control": {"type": "ephemeral"} 한 줄만 넣는 자동 캐싱도 있습니다. 캐시할 수 있는 마지막 부분에 표시가 저절로 붙고, 대화가 길어지면 뒤로 따라 옮겨 갑니다. 앞선 대화가 그대로 쌓이는 여러 턴 대화에 맞는 방식이며, 4개 중 한 자리를 씁니다.

질문 하나만 매번 바뀌는 위 예시에는 자동 캐싱이 맞지 않습니다. 저장은 표시한 자리에서만 일어나는데, 표시가 바뀌는 질문 위에 붙기 때문입니다. 질문마다 1.25배 저장 값만 내고 읽기는 한 번도 적중하지 않아, 문서도 이 구조를 흔한 실수로 꼽습니다.

얼마나 유지되나

기본 유지 시간은 5분입니다. 시간은 저장하거나 꺼내 쓴 요청이 시작된 시점부터 셉니다. 5분 안에 다시 쓰면 유지 시간이 새로 채워지고, 여기에 추가 요금은 붙지 않습니다.

요청 간격이 5분을 넘는다면 1시간짜리를 고를 수 있습니다. 문서는 5분보다는 드물고 1시간보다는 잦게 쓰는 프롬프트에 이쪽을 권합니다. 표시에 ttl 값을 더하면 됩니다.

"cache_control": {"type": "ephemeral", "ttl": "1h"}

유지 시간이 지나면 저장본은 사라집니다. 그다음 요청은 처음처럼 전체를 읽고 저장 값을 다시 냅니다. 점심을 먹고 와서 보낸 첫 요청이 비싸게 나오는 이유가 여기 있습니다.

값은 얼마나 달라지나

값은 평소 입력 단가에 배율을 곱해 정합니다. 저장할 때 조금 더 내고, 꺼내 쓸 때 크게 아끼는 구조입니다. 아래 단가는 Sonnet 4.5 기준, 100만 토큰당 값입니다.

캐시 읽기 배율은 모델마다 조금씩 다릅니다. Opus 5.5와 Sonnet 5.5는 0.05배, Fable 5.1과 Mythos 5.1은 0.025배입니다. 그 밖의 모델은 0.1배입니다.

직접 셈해 보면 차이가 드러납니다. 10만 토큰짜리 자료를 5분 안에 10번 보낸다고 해 봅시다. 질문과 답 부분은 빼고, 위 표의 단가로 자료 부분만 계산했습니다.

• 캐싱 없이: 10번 모두 평소 단가로 읽어 3달러
• 5분 캐싱: 첫 저장 0.375달러, 나머지 9번 읽기 0.27달러, 합계 0.645달러

원래 값의 5분의 1 남짓입니다. 거꾸로 한 번 보내고 끝나는 자료라면 저장 배율 1.25배만큼 더 낸 셈이 됩니다.

적중했는지 확인하기

캐시가 맞았는지는 응답의 usage 항목에 숫자로 나옵니다. 볼 칸은 셋입니다. 세 값을 더하면 이번 요청의 입력 토큰 전체가 됩니다.

• cache_creation_input_tokens: 이번에 새로 저장한 토큰 수입니다. 첫 요청에서 숫자가 찹니다.
• cache_read_input_tokens: 저장본에서 꺼내 읽은 토큰 수입니다. 5분 안에 다시 보내면 여기에 숫자가 뜹니다.
• input_tokens: 마지막 표시 뒤에 붙어 캐시 없이 읽은 토큰 수입니다. 보통 새 질문 부분입니다.

같은 요청을 5분 넘게 쉬었다가 보내 보세요. 읽기 칸은 0이 되고 저장 칸에 다시 숫자가 찹니다. 저장본이 사라져 처음부터 다시 저장했다는 신호입니다.

두 칸이 모두 0이라면 캐싱이 아예 일어나지 않았습니다. 문서는 이럴 때 최소 길이에 못 미쳤을 가능성이 크다고 설명합니다. 짧은 프롬프트는 오류 없이 캐시 없이 처리되므로 숫자로만 알 수 있습니다.

언제 쓰고 언제 안 쓰나

캐싱이 잘 맞는 경우는 같은 앞부분을 짧은 간격으로 여러 번 보낼 때입니다.

• 회사 규정집이나 제품 설명서를 붙여 두고 질문을 연달아 할 때
• 같은 지시문과 예시로 문서 수십 건을 차례로 처리할 때
• 한 사람과 길게 이어지는 대화를 주고받을 때

반대로 아래 경우에는 효과가 없거나 오히려 손해입니다. 켜기 전에 한 번 따져 보세요.

• 프롬프트가 짧을 때. Opus 5.5, Sonnet 5.5, Haiku 5.5는 512토큰, Sonnet 4.5는 1,024토큰, Haiku 4.5는 4,096토큰이 최소 길이입니다. 이보다 짧으면 저장되지 않습니다. Opus 4.7 등은 2,048토큰이니 쓰는 모델의 값은 문서 표에서 확인하세요.
• 한 번 보내고 끝날 때. 다시 꺼내 쓸 일이 없으니 저장 값만 더 냅니다.
• 간격이 유지 시간보다 길 때. 매번 저장본이 사라진 뒤라 저장 값만 거듭 냅니다. 1시간짜리로도 모자라면 끄는 편이 낫습니다.
• 앞부분이 자주 바뀔 때. 표시까지 100% 같아야 맞으므로, 자료를 조금씩 고치며 보내면 계속 빗나갑니다.
• 같은 요청을 동시에 여러 개 보낼 때. 저장본은 첫 응답이 시작된 뒤에야 쓸 수 있습니다. 첫 응답을 기다린 다음 나머지를 보내야 적중합니다.

회사 자료를 올려도 괜찮을지 걱정된다면 하나만 기억해 두세요. 저장본은 조직마다 나뉘어 다른 회사와 공유되지 않습니다. Claude API에서는 같은 조직 안에서도 작업공간(workspace)마다 따로 둡니다.

오늘 해 볼 첫걸음

지금 쓰고 있는 긴 요청 하나를 고르세요. 시스템 지시문 블록에 "cache_control": {"type": "ephemeral"}을 넣고, 질문만 바꿔 1분 간격으로 두 번 보냅니다.

두 번째 응답의 cache_read_input_tokens에 숫자가 뜨면 성공입니다. 질문을 바꿔 보내야 실제로 쓸 때와 같은 조건에서 시험할 수 있습니다. 0이 나온다면 프롬프트 길이와 표시 위치부터 확인해 보세요.

이상으로 글 마치겠습니다.

참고한 공식 문서

• Prompt caching, Claude 공식 문서
• Pricing, Claude 공식 문서