Claude 프롬프트 캐싱

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}

​

프롬프트 캐싱의 작동 방식

1. 시스템이 지정된 캐시 중단점까지의 프롬프트 접두사가 최근 쿼리에서 이미 캐시되어 있는지 확인합니다.
2. 캐시가 존재하면, 해당 캐시를 사용하여 처리 시간과 비용을 줄입니다.
3. 없다면 전체 프롬프트를 처리하고, 응답이 시작되면 접두사를 캐시에 저장합니다. 프롬프트 캐싱은 특히 다음과 같은 경우에 유용합니다:

• 예시가 많은 프롬프트
• 대량의 컨텍스트 또는 배경 정보가 포함된 경우
• 일관된 지침이 반복되는 작업
• 긴 다중 턴 대화

​

흔한 실수: 캐시를 “쓰기만 하고 읽지 못하는” 경우

​

❌ 잘못된 방식: 매 턴 바뀌는 질문을 중단점 앞에 두는 경우

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "请总结这份资料的核心观点。" },                          // ← 每轮会变,却放在断点前
        { "type": "text", "text": "<大文档>", "cache_control": { "type": "ephemeral" } }   // 断点
      ]
    }
  ]
}

​

✅ 올바른 방식: 대용량 문서를 맨 앞에 + 중단점 + 질문을 맨 뒤에

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "<固定不变的大文档/参考资料，≥4096 token>", "cache_control": { "type": "ephemeral" } },  // 断点;前缀恒定
        { "type": "text", "text": "请总结这份资料的核心观点。" }                                                          // ← 每轮变化的问题,放在断点之后
      ]
    }
  ]
}

​

실측 비교(claude-opus-4-6, 동일 채널 고정, 두 호출 간격 수 초)

1. 고정 불변의 대용량 블록(참조 문서, 긴 컨텍스트)을 messages 사용자 메시지의 맨 앞에 배치하고, cache_control을 그 끝에 찍습니다. 이 콘텐츠는 한 글자도 바뀌어서는 안 됩니다.
2. 매 턴 바뀌는 질문/지시는 중단점 뒤에 배치합니다(같은 user 메시지 내 대용량 문서 뒤, 또는 후속 메시지). 다중 턴 대화는 뒤로만 추가하고, 이전 메시지를 거슬러 올라가 수정하지 마세요.
3. thinking을 켤 때는 이전 어시스턴트 턴의 thinking 블록을 원본 그대로 회신해야 합니다. 그렇지 않으면 접두사가 똑같이 끊어집니다(아래 「캐싱 불가 항목」 참고).
4. 블록이 최소 캐시 임계값(Opus 4.5/4.6, Haiku 4.5는 4096 토큰)보다 작으면 cache_control을 표시하더라도 캐시에 기록되지 않습니다. 이는 예상된 동작이며, 아래 「캐시 제한 사항」을 참고하세요.

​

요금 안내

• 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

​

프롬프트 구성 방법

​

캐시 제한 사항

• 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 토큰

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

​

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

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시간 캐시가 적합한 상황

• 배치 처리: 동일한 접두사를 가진 대량 요청 처리
• 장시간 세션: 오랜 시간 동안 컨텍스트 유지를 필요로 하는 대화
• 대용량 문서 분석: 하나의 문서에 대해 다양한 유형의 분석을 반복 수행
• 코드베이스 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"
      }
    }
  ]
}

​

캐싱 가능한 항목

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

​

캐싱 불가 항목

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

​

캐시 성능 추적

• 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 파라미터를 사용해 이전 구간의 캐시 조회를 보장할 수 있습니다.

​

캐시 저장 및 공유 정책

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

​

클라이언트 / 플랫폼에서 Claude 캐싱 활성화하기

​

Dify(Aihubmix 플러그인 경유)

1. 캐싱할 프롬프트(고정 불변의 시스템 프롬프트 / 긴 컨텍스트)를 <cache>…</cache>로 감싸면, 플러그인이 해당 위치에서 자동으로 cache_control 중단점으로 변환합니다.
2. 모델 파라미터에서 「대용량 메시지 자동 캐시 임계값」을 양의 정수로 설정합니다. 콘텐츠가 해당 토큰 임계값에 도달해야 실제로 캐시에 기록됩니다(아래 「캐시 제한 사항」의 최소 캐시 제약은 여전히 적용되며, Opus 4.5/4.6, Haiku 4.5는 4096 토큰). 0으로 설정하거나 비워 두면 비활성화됩니다.

​

Cherry Studio

1. Aihubmix 공급자 이름 오른쪽의 톱니바퀴를 클릭해 「API 설정」(API Settings)을 엽니다:

2. 다음 세 항목을 구성하면, 클라이언트가 이를 기준으로 Claude에 cache_control을 자동 주입합니다:

• 캐시 토큰 임계값(Cache Token Threshold): 콘텐츠가 해당 토큰 수를 초과할 때만 캐시 중단점을 주입합니다(양수로 설정하면 켜짐, 0 또는 비워 두면 꺼짐).
• 시스템 메시지 캐싱(Cache System Message): 켜면 system 메시지에 캐시 중단점을 찍습니다(고정된 긴 시스템 프롬프트 캐싱에 적합).
• 최근 N개 메시지 캐싱(Cache Last N Messages): 최근 N개 메시지에 캐시 중단점을 찍습니다(다중 턴 대화의 롤링 캐싱에 적합).

​

자주 묻는 질문(FAQ)

​

캐시를 쓰는데(cache_creation_input_tokens는 큰데) 왜 계속 읽지 못하나요(cache_read_input_tokens가 0)?

​

캐시에는 최소 몇 토큰이 필요한가요?

​

캐시 유효기간은 얼마나 되나요? 1시간으로 바꿀 수 있나요?

​

Dify / Cherry Studio에서는 캐싱을 어떻게 켜나요?

​

다양한 모델별 지원 현황

• 프롬프트 캐싱 지원 여부는 모델 자체에 따라 다릅니다.
• 모델이 별도의 파라미터 선언 없이 기본적으로 캐싱을 지원하는 경우, 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 동영상 전처리 캐시만 암시적 캐싱 대상입니다.