다음은 Messages API에서 cache_control 블록을 사용하여 프롬프트 캐싱을 구현하는 예시입니다:

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "stream": true,
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style."
      },
      {
        "type": "text",
        "text": "Pride and Prejudice by Jane Austen... [Place complete text content here]",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 16000
    },
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

응답 예시:

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

이 예시에서는 “Pride and Prejudice” 전체 텍스트가 cache_control 파라미터를 통해 캐싱됩니다. 이를 통해 이 대용량 텍스트를 여러 API 호출에서 반복 처리하지 않고 재사용할 수 있습니다. 사용자 메시지만 변경하면 캐시된 내용을 활용하여 책에 대한 다양한 질문을 빠르게 할 수 있어 응답 속도와 효율이 크게 향상됩니다.

​
프롬프트 캐싱의 작동 방식

프롬프트 캐싱이 활성화된 상태로 요청을 보내면:

  1. 시스템이 지정된 캐시 중단점까지의 프롬프트 접두사가 최근 쿼리에서 이미 캐시되어 있는지 확인합니다.
  2. 캐시가 존재하면, 해당 캐시를 사용하여 처리 시간과 비용을 줄입니다.
  3. 없다면 전체 프롬프트를 처리하고, 응답이 시작되면 접두사를 캐시에 저장합니다. 프롬프트 캐싱은 특히 다음과 같은 경우에 유용합니다:
  • 예시가 많은 프롬프트
  • 대량의 컨텍스트 또는 배경 정보가 포함된 경우
  • 일관된 지침이 반복되는 작업
  • 긴 다중 턴 대화

기본적으로 캐시의 유효 기간은 5분입니다. 캐시된 내용이 사용될 때마다 추가 비용 없이 캐시가 새로고침됩니다. 더 긴 캐시 유지가 필요한 경우를 위해 **1시간 캐시 버전(베타)**도 지원합니다.

​
프롬프트 캐싱은 전체 접두사를 캐싱합니다

프롬프트 캐싱은 프롬프트의 전체 접두사, 즉 tools, system, 그리고 messages(이 순서대로) 중에서 cache_control이 지정된 블록까지 모두 참조하여 캐싱합니다.

​
요금 안내

프롬프트 캐싱은 새로운 요금 체계를 도입합니다. 아래 표는 각 지원 모델별 백만 토큰당 가격을 보여줍니다:

모델기본 입력 토큰5분 캐시 쓰기1시간 캐시 쓰기캐시 히트 및 새로고침출력 토큰
Claude Opus 4플랫폼 요금기본가의 1.25배기본가의 2배기본가의 0.1배플랫폼 요금
Claude Sonnet 4플랫폼 요금기본가의 1.25배기본가의 2배기본가의 0.1배플랫폼 요금
Claude Sonnet 3.7플랫폼 요금기본가의 1.25배기본가의 2배기본가의 0.1배플랫폼 요금
Claude Sonnet 3.5플랫폼 요금기본가의 1.25배기본가의 2배기본가의 0.1배플랫폼 요금
Claude Haiku 3.5플랫폼 요금기본가의 1.25배기본가의 2배기본가의 0.1배플랫폼 요금
Claude Opus 3플랫폼 요금기본가의 1.25배기본가의 2배기본가의 0.1배플랫폼 요금
Claude Haiku 3플랫폼 요금기본가의 1.25배기본가의 2배기본가의 0.1배플랫폼 요금

참고:

  • 5분 캐시 쓰기 토큰은 기본 입력 토큰 가격의 1.25배입니다.
  • 1시간 캐시 쓰기 토큰은 기본 입력 토큰 가격의 2배입니다.
  • 캐시 읽기 토큰은 기본 입력 토큰 가격의 0.1배입니다.
  • 일반 입력 및 출력 토큰은 플랫폼 표준 요금이 적용됩니다.

​
프롬프트 캐싱 구현 방법

​
지원되는 모델

프롬프트 캐싱은 현재 다음 모델에서 지원됩니다:

  • Claude Opus 4
  • Claude Sonnet 4
  • Claude Sonnet 3.7
  • Claude Sonnet 3.5
  • Claude Haiku 3.5
  • Claude Haiku 3
  • Claude Opus 3

​
프롬프트 구성 방법

프롬프트의 시작 부분에 정적 콘텐츠(툴 정의, 시스템 지침, 컨텍스트, 예시 등)를 배치하세요. 재사용 가능한 콘텐츠의 끝에 cache_control 파라미터를 사용해 캐싱 대상을 표시합니다.

캐시 접두사는 다음 순서로 생성됩니다: tools → system → messages

cache_control 파라미터를 사용하면 최대 4개의 캐시 중단점을 지정할 수 있으며, 각각의 재사용 가능한 섹션을 개별적으로 캐싱할 수 있습니다. 각 중단점마다 시스템이 이전 위치의 캐시 히트를 자동으로 확인하고, 가장 긴 일치 접두사를 사용합니다.

​
캐시 제한 사항

캐싱 가능한 프롬프트의 최소 길이는 다음과 같습니다:

  • Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5, Claude Opus 3: 1024 토큰
  • Claude Haiku 3.5, Claude Haiku 3: 2048 토큰

이보다 짧은 프롬프트는 cache_control로 표시하더라도 캐싱되지 않습니다. 이 기준 미만의 토큰 수로 캐시를 요청하면 일반 처리만 되고 캐싱이 적용되지 않습니다. 프롬프트가 캐시되었는지 확인하려면 응답 usage의 필드를 참고하세요.

동시 요청의 경우, 첫 번째 응답이 시작된 이후에만 캐시 항목이 사용 가능합니다. 병렬 요청에서 캐시 히트를 원한다면, 첫 번째 응답을 받은 후 다음 요청을 보내야 합니다.

현재 두 가지 캐시 유형을 지원합니다:

  • “ephemeral”: 기본 5분 유효기간
  • 1시간 캐시(베타): 더 긴 캐시 유지가 필요한 경우

​
1시간 캐시 유효기간(베타)

더 긴 캐시 유지가 필요한 경우 1시간 캐시 옵션을 제공합니다.

확장된 캐시를 사용하려면 요청 헤더에 extended-cache-ttl-2025-04-11을 베타 헤더로 추가하고, cache_control 정의에 ttl을 포함시키세요:

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: extended-cache-ttl-2025-04-11" \
  -d '{
    "model": "claude-opus-4-20250514",
    "system": [
      {
        "type": "text",
        "text": "Long-term instructions...",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "1h"
        }
      }
    ],
    "messages": [...]
  }'

{
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
  }
}

​
1시간 캐시가 적합한 상황

1시간 캐시는 다음과 같은 경우에 특히 적합합니다:

  • 배치 처리: 동일한 접두사를 가진 대량 요청 처리
  • 장시간 세션: 오랜 시간 동안 컨텍스트 유지를 필요로 하는 대화
  • 대용량 문서 분석: 하나의 문서에 대해 다양한 유형의 분석을 반복 수행
  • 코드베이스 Q&A: 동일 코드베이스에 대해 여러 질의를 장기간 수행

​
서로 다른 TTL 혼합 사용

하나의 요청 내에서 서로 다른 캐시 만료 시간을 혼합하여 사용할 수 있습니다:

{
  "system": [
    {
      "type": "text", 
      "text": "Long-term instructions...",
      "cache_control": {
        "type": "ephemeral",
        "ttl": "1h"
      }
    },
    {
      "type": "text",
      "text": "Short-term context...", 
      "cache_control": {
        "type": "ephemeral",
        "ttl": "5m"
      }
    }
  ]
}

​
캐싱 가능한 항목

요청의 모든 블록은 cache_control을 통해 캐싱 대상으로 지정할 수 있습니다. 다음이 포함됩니다:

  • Tools: tools 배열 내 툴 정의
  • 시스템 메시지: system 배열의 콘텐츠 블록
  • 메시지: messages.content 배열의 사용자 및 어시스턴트 턴의 콘텐츠 블록
  • 이미지 & 문서: 사용자 턴의 messages.content 배열 내 콘텐츠 블록
  • 툴 사용 및 툴 결과: 사용자 및 어시스턴트 턴의 messages.content 배열 내 콘텐츠 블록

각 요소에 cache_control을 지정해 해당 요청 부분을 캐싱할 수 있습니다.

​
캐싱 불가 항목

대부분의 요청 블록은 캐싱할 수 있으나, 예외도 있습니다:

  • Thinking 블록은 cache_control로 직접 캐싱할 수 없습니다. 그러나 이전 어시스턴트 턴에 다른 콘텐츠와 함께 등장하면 캐싱이 가능합니다. 이 경우 캐시에서 읽을 때 입력 토큰으로 계산됩니다.
  • 서브 콘텐츠 블록(예: 인용 등)은 직접 캐싱할 수 없습니다. 대신 상위 블록을 캐싱하세요.
  • 빈 텍스트 블록은 캐싱할 수 없습니다.

​
캐시 성능 추적

캐시 성능은 응답의 usage 내 다음 API 필드(또는 스트리밍이라면 message_start 이벤트)로 모니터링할 수 있습니다:

  • cache_creation_input_tokens: 새 캐시 엔트리 생성 시 캐시에 기록된 토큰 수
  • cache_read_input_tokens: 해당 요청에서 캐시에서 읽은 토큰 수
  • input_tokens: 캐시에서 읽거나 생성하지 않은 입력 토큰 수

​
효과적인 캐싱을 위한 모범 사례

프롬프트 캐싱 성능을 최적화하려면:

  • 시스템 지침, 배경 정보, 대용량 컨텍스트, 자주 사용되는 툴 정의 등 안정적이고 재사용 가능한 콘텐츠를 캐싱하세요.
  • 캐싱할 콘텐츠는 프롬프트의 시작 부분에 배치하는 것이 가장 효율적입니다.
  • 캐시 중단점을 전략적으로 설정해 여러 개의 캐시 가능한 접두사 구간을 분리하세요.
  • 정기적으로 캐시 히트율을 분석하고 전략을 조정하세요.
  • 장기 콘텐츠는 1시간 캐시를 활용해 비용 효율을 높이세요.

​
다양한 사용 사례별 최적화

프롬프트 캐싱 전략을 시나리오에 맞게 조정하세요:

  • 대화형 에이전트: 긴 지침이나 업로드 문서가 포함된 장기 대화의 비용과 지연을 줄입니다.
  • 코딩 어시스턴트: 관련 코드 섹션이나 요약본을 프롬프트에 포함해 자동완성 및 코드 Q&A 효율을 높입니다.
  • 대용량 문서 처리: 이미지 포함 장문 자료 전체를 프롬프트에 넣어도 응답 지연 없이 처리할 수 있습니다.
  • 상세 지침 세트: 광범위한 지침, 절차, 예시를 공유해 Claude의 응답 품질을 미세 조정하세요. 개발자들은 프롬프트에 1~2개의 예시만 포함하는 경우가 많지만, 프롬프트 캐싱을 사용하면 20개 이상의 다양한 고품질 예시를 넣어도 성능 저하 없이 더 좋은 결과를 얻을 수 있습니다.
  • 에이전트형 툴 사용: 여러 번의 툴 호출과 반복 코드 변경이 필요한 시나리오에서 각 단계마다 새로운 API 호출이 필요할 때 성능을 크게 향상시킵니다.
  • 책, 논문, 문서, 팟캐스트 필사 등 장문 콘텐츠 질의: 전체 문서(들)를 프롬프트에 삽입해 언제든 질문할 수 있는 지식베이스로 활용하세요.

​
자주 발생하는 문제 해결

예상치 못한 동작이 발생할 경우:

  • 캐시된 구간이 동일하게 유지되고, 각 호출에서 동일 위치에 cache_control이 표시되어 있는지 확인하세요.
  • 호출이 캐시 유효기간(5분 또는 1시간) 내에 이루어지는지 확인하세요.
  • tool_choice 및 이미지 사용이 호출 간 일관되는지 점검하세요.
  • 최소 토큰 수 이상을 캐싱하고 있는지 검증하세요.
  • 시스템은 캐시 중단점 이전 위치의 기존 캐시 콘텐츠를 사용하려 시도하지만, 매우 긴 콘텐츠 블록 목록이 포함된 질의에는 추가 cache_control 파라미터를 사용해 이전 구간의 캐시 조회를 보장할 수 있습니다.

프롬프트 내 어디서든 tool_choice 변경 또는 이미지의 유무가 바뀌면 캐시가 무효화되어 새 캐시 엔트리가 생성됩니다.

​
캐시 저장 및 공유 정책

  • 조직 격리: 캐시는 조직별로 완전히 분리됩니다. 서로 다른 조직은 동일한 프롬프트를 사용하더라도 캐시를 공유하지 않습니다.
  • 정확한 일치: 캐시 히트는 cache_control로 표시된 블록까지의 모든 텍스트와 이미지를 포함해 100% 동일한 프롬프트 구간이 필요합니다. 캐시 생성 및 조회 시 동일한 블록에 cache_control이 표시되어야 합니다.
  • 출력 토큰 생성: 프롬프트 캐싱은 출력 토큰 생성에 영향을 주지 않습니다. 캐싱을 사용하지 않은 경우와 동일한 응답을 받게 됩니다.

​
다양한 모델별 지원 현황

  • 프롬프트 캐싱 지원 여부는 모델 자체에 따라 다릅니다.
  • 모델이 별도의 파라미터 선언 없이 기본적으로 캐싱을 지원하는 경우, OpenAI 호환 프록시를 통해서도 지원될 수 있습니다.
  • OpenAI는 프롬프트 캐싱을 기본 지원합니다. 캐시된 프롬프트는 요금이 청구되지 않으며, 캐시 토큰 조회 비용은 정상의 절반, 비활성 5~10분 후 자동 삭제됩니다. 자세히 보기
  • Claude는 반드시 cache_control: { type: "ephemeral" } 네이티브 선언이 필요합니다. 캐싱 요금은 입력 기준 5분 캐시 1.25배, 1시간 캐시 2배, 캐시 읽기는 0.1배, 유효기간은 5분 또는 1시간입니다. 자세히 보기
  • Deepseek V3 및 R1은 캐싱을 기본 지원합니다. 캐싱 요금은 입력과 동일, 캐시 조회 비용은 0.1배입니다. 자세히 보기
  • Gemini 암시적(implicit) 캐싱 지원:
    • 암시적 캐싱: Gemini 2.5 모델에서 기본 활성화되어 있습니다. 요청이 캐시에 적중하면 비용 절감이 자동 적용됩니다. 2025년 5월 8일부터 적용되며, 컨텍스트 캐싱 최소 입력 토큰은 Gemini 2.5 Flash는 1,024, Gemini 2.5 Pro는 2,048입니다.
    • 암시적 캐시 히트율을 높이는 팁:
      • 자주 재사용되는 대용량 콘텐츠를 프롬프트 앞부분에 배치해 보세요.
      • 유사한 접두사의 요청을 짧은 시간 내에 여러 번 보내보세요.
    • 응답 객체의 usage_metadata 필드에서 캐시 히트 토큰 수를 확인할 수 있습니다.
    • 비용 절감은 prefill 캐시 히트 기준으로 산정되며, prefill 캐시와 YouTube 동영상 전처리 캐시만 암시적 캐싱 대상입니다.