Claude 프롬프트 캐싱 — 요금, usage 객체, 게이트웨이 뒤에서 적중률이 떨어지는 이유

프롬프트 캐싱은 에이전트 청구액을 조정하는 가장 큰 단일 수단이며, 아무런 알림 없이 작동하지 않을 가능성이 가장 큰 요소입니다. 올바르게 표시하면 요청의 반복되는 부분에 입력 요금의 10분의 1이 청구됩니다. 잘못 표시했거나 접두사를 다시 작성하는 무언가를 통해 라우팅하면, 아무것도 읽지 않는 캐시 항목을 쓰는 데 비용을 지불하므로 일반 요금보다 더 많이 청구됩니다.

메커니즘 자체는 다른 곳에 잘 문서화되어 있습니다. 어디에도 문서화되지 않은 것은 요청이 게이트웨이를 통과할 때 무엇이 달라지는지이며, 이 문서를 읽는 대부분의 사람이 처한 상황이 바로 이것입니다. 두 내용 모두 아래에 설명합니다.

메커니즘 요약

안정적인 접두사(시스템 프롬프트, 도구 스키마, 문서 등)를 지정하면 제공업체가 처리된 형태를 저장합니다. 접두사가 정확히 일치하는 다음 요청은 이를 다시 처리하지 않고 읽어 옵니다.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<your long, stable instructions>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "..." }]
}

모든 작업을 수행하면서 모든 문제를 일으키는 속성은 두 가지입니다. 일치는 접두사에 대해 이루어지므로 초반에 변경되는 항목 하나만 있어도 그 뒤의 모든 항목이 무효화됩니다. 또한 항목에는 수명이 있으므로, 턴 사이의 간격이 긴 대화는 읽는 대신 다시 생성합니다.

비용

세 번째 열은 표준 비율입니다. 읽기 비용은 입력 비용의 10분의 1입니다. 네 번째 열도 표준입니다. 캐시 쓰기 비용은 입력 비용의 1.25배이며, 이는 Anthropic이 5분 항목에 대해 제시하는 배수입니다. 두 비율 모두 Kunavo의 입력 가격에 적용되므로 각각 모델 입력 가격과 동일한 할인율이 Anthropic 정가에 적용됩니다. Kunavo가 Anthropic과 다른 점은 1시간 항목입니다. Anthropic은 해당 쓰기를 입력 비용의 2배로 제시하지만 Kunavo는 동일한 1.25배를 청구합니다. 이는 자주 다시 생성되는 워크로드, 즉 장시간 실행되는 에이전트, 느린 대화, 접두사가 계속 바뀌는 모든 작업에서 특히 중요합니다. 이러한 워크로드에서는 캐시 청구액에서 읽기보다 쓰기가 지배적이기 때문입니다.

두 수치는 모두 렌더링 시 카탈로그에서 읽으며, 가격표와 Claude 계산기가 읽는 것과 동일한 출처입니다. 이 페이지에 수동으로 입력한 요율은 없습니다.

사용량 객체 읽기

청구서로 캐시 동작을 추론하지 마세요. 모든 응답이 이를 직접 알려 주며, 세 가지 토큰 수가 전체 진단 정보입니다.

// The four numbers that tell you whether caching is working.
// Read them from every response before you tune anything.
"usage": {
  "input_tokens": 312,                     // billed at the input rate
  "cache_creation_input_tokens": 0,        // billed at the write rate
  "cache_read_input_tokens": 24106,        // billed at the read rate
  "output_tokens": 890
}

// A healthy cached agent turn looks like the above: a small
// input_tokens, a large cache_read, and a zero creation.
// If cache_creation is large on EVERY turn, the cache is being
// rebuilt each time and you are paying more, not less.

게이트웨이 뒤에서 적중률이 떨어지는 이유

캐시는 이를 생성한 업스트림에 존재하며 접두사 일치는 정확해야 합니다. 이 두 가지 사실이 함께 작용하면 하나의 제공업체를 직접 호출할 때는 발생하지 않는 세 가지 실패 모드가 생깁니다.

라우팅이 변경되었습니다. 연속된 요청이 서로 다른 업스트림에 도착하면 두 번째 요청은 캐시를 찾지 못합니다. 첫 번째 요청이 작성한 항목은 두 번째 요청이 실행된 위치에서는 보이지 않기 때문입니다. 이는 자체 로그에는 드러나지 않고, 읽기였어야 할 캐시 생성 수로만 나타납니다. 가장 흔한 원인이며, 업스트림 간에 자유롭게 재라우팅하는 게이트웨이가 토큰당 비용은 낮추고 세션당 비용은 높일 수 있는 이유이기도 합니다.

접두사 앞에 무언가 삽입되었습니다. 시스템 메시지를 다시 작성하거나, 도구 정의를 정규화하거나, 필드 순서를 변경하는 계층은 다른 접두사를 만듭니다. 다른 접두사는 캐시 미스입니다. 오류는 발생하지 않고 청구액만 증가합니다.

간격이 항목의 수명을 초과했습니다. 턴 사이에 몇 분 동안 생각하는 에이전트는 매번 다시 생성할 수 있습니다. 이는 게이트웨이보다는 워크로드의 속성이지만 첫 번째 문제와 상호작용이 좋지 않습니다. 다시 생성하는 과정은 재라우팅 기회이기도 하기 때문입니다.

세 가지 모두에 대한 진단 방법은 동일합니다. 세션 전체에서 cache_creation_input_tokens를 관찰하세요. 크고 평평하면 계속 다시 생성하고 있는 것입니다. 한 번 크고 이후 0이면 정상적으로 작동하는 것입니다. Kunavo에서는 요청 수준 비용과 캐시된 토큰 수를 사용량 보기에서 확인할 수 있으며, 캐싱 참조 문서에는 엔드포인트 수준의 세부 정보가 있습니다.

대처 방법

캐시된 접두사를 실제로 안정적으로 유지하세요. 요청마다 변경되는 항목은 표시된 블록의 뒤에 두고, 그 앞에는 절대 두지 마세요. 짧은 수명의 항목에서는 유휴 시간이 적이므로 가능한 경우 에이전트의 턴을 더 가깝게 묶으세요. 또한 요청이 아니라 세션 전체를 측정하세요. 캐싱은 시퀀스의 속성이며 요청별 추정치는 이를 볼 수 없습니다. Claude 토큰 비용 계산기에 캐시된 토큰 필드가 있는 이유가 바로 이것입니다. 실제로 반복되는 프롬프트의 비율을 입력하면 월별 수치가 더 이상 허구가 되지 않습니다.

자주 묻는 질문