프롬프트 캐싱 (베타)

프롬프트 캐싱은 프롬프트의 특정 접두사에서 재개할 수 있도록 하여 API 사용을 최적화하는 강력한 기능입니다. 이 접근 방식은 반복적인 작업이나 일관된 요소가 있는 프롬프트의 처리 시간과 비용을 크게 줄여줍니다.

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

이 예시에서는 cache_control 매개변수를 사용하여 “오만과 편견”의 전체 텍스트가 캐시됩니다. 이를 통해 매번 재처리할 필요 없이 이 대용량 텍스트를 여러 API 호출에서 재사용할 수 있습니다. 사용자 메시지만 변경하면 캐시된 콘텐츠를 활용하면서 책에 대한 다양한 질문을 할 수 있어 더 빠른 응답과 향상된 효율성을 얻을 수 있습니다.

---

​

프롬프트 캐싱의 작동 방식

프롬프트 캐싱이 활성화된 요청을 보낼 때:

1. 시스템은 최근 쿼리에서 프롬프트 접두사가 이미 캐시되어 있는지 확인합니다.
2. 발견되면 캐시된 버전을 사용하여 처리 시간과 비용을 줄입니다.
3. 그렇지 않으면 전체 프롬프트를 처리하고 향후 사용을 위해 접두사를 캐시합니다.

이는 다음과 같은 경우에 특히 유용합니다:

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

캐시는 5분의 수명을 가지며, 캐시된 콘텐츠가 사용될 때마다 갱신됩니다.

---

​

가격 책정

프롬프트 캐싱은 새로운 가격 구조를 도입합니다. 아래 표는 지원되는 각 모델의 토큰당 가격을 보여줍니다:

모델	기본 입력 토큰	캐시 쓰기	캐시 히트	출력 토큰
Claude 3.5 Sonnet	$3 / MTok	$3.75 / MTok	$0.30 / MTok	$15 / MTok
Claude 3.5 Haiku	$1 / MTok	$1.25 / MTok	$0.10 / MTok	$5 / MTok
Claude 3 Haiku	$0.25 / MTok	$0.30 / MTok	$0.03 / MTok	$1.25 / MTok
Claude 3 Opus	$15 / MTok	$18.75 / MTok	$1.50 / MTok	$75 / MTok

참고:

• 캐시 쓰기 토큰은 기본 입력 토큰보다 25% 더 비쌉니다
• 캐시 읽기 토큰은 기본 입력 토큰보다 90% 더 저렴합니다
• 일반 입력 및 출력 토큰은 표준 요금으로 책정됩니다

---

​

프롬프트 캐싱 구현 방법

​

지원되는 모델

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

• Claude 3.5 Sonnet
• Claude 3.5 Haiku
• Claude 3 Haiku
• Claude 3 Opus

​

프롬프트 구조화

프롬프트의 시작 부분에 정적 콘텐츠(도구 정의, 시스템 지침, 컨텍스트, 예시)를 배치하세요. cache_control 매개변수를 사용하여 캐싱을 위한 재사용 가능한 콘텐츠의 끝을 표시하세요.

캐시 접두사는 다음 순서로 생성됩니다: tools, system, 그리고 messages.

cache_control 매개변수를 사용하여 최대 4개의 캐시 중단점을 정의할 수 있어, 서로 다른 재사용 가능한 섹션을 별도로 캐시할 수 있습니다.

​

캐시 제한사항

최소 캐시 가능한 프롬프트 길이는:

• Claude 3.5 Sonnet과 Claude 3 Opus의 경우 1024 토큰
• Claude 3.5 Haiku와 Claude 3 Haiku의 경우 2048 토큰

이보다 짧은 프롬프트는 cache_control로 표시되어 있더라도 캐시될 수 없습니다. 이 토큰 수보다 적은 토큰을 캐시하려는 요청은 캐싱 없이 처리됩니다. 프롬프트가 캐시되었는지 확인하려면 응답 사용량 필드를 참조하세요.

캐시는 5분의 TTL(Time To Live)을 가집니다. 현재 “ephemeral”만이 지원되는 캐시 유형이며, 이는 이 5분의 수명에 해당합니다.

​

캐시 가능한 항목

요청의 모든 블록은 cache_control로 캐싱을 위해 지정될 수 있습니다. 여기에는 다음이 포함됩니다:

• 도구: tools 배열의 도구 정의
• 시스템 메시지: system 배열의 콘텐츠 블록
• 메시지: 사용자와 어시스턴트 턴 모두에서 messages.content 배열의 콘텐츠 블록
• 이미지: 사용자 턴의 messages.content 배열의 콘텐츠 블록
• 도구 사용 및 도구 결과: 사용자와 어시스턴트 턴 모두에서 messages.content 배열의 콘텐츠 블록

이러한 요소들은 각각 cache_control로 표시되어 요청의 해당 부분에 대한 캐싱을 활성화할 수 있습니다.

​

캐시 성능 추적

응답의 usage 내에서 (또는 스트리밍하는 경우 message_start 이벤트에서) 다음 API 응답 필드를 사용하여 캐시 성능을 모니터링하세요:

• cache_creation_input_tokens: 새 항목을 생성할 때 캐시에 쓰여진 토큰 수
• cache_read_input_tokens: 이 요청에 대해 캐시에서 검색된 토큰 수
• input_tokens: 캐시에서 읽거나 캐시를 생성하는 데 사용되지 않은 입력 토큰 수

​

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

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

• 시스템 지침, 배경 정보, 대용량 컨텍스트 또는 자주 사용하는 도구 정의와 같은 안정적이고 재사용 가능한 콘텐츠를 캐시하세요.
• 최상의 성능을 위해 캐시된 콘텐츠를 프롬프트의 시작 부분에 배치하세요.
• 서로 다른 캐시 가능한 접두사 섹션을 분리하기 위해 캐시 중단점을 전략적으로 사용하세요.
• 정기적으로 캐시 히트율을 분석하고 필요에 따라 전략을 조정하세요.

​

다양한 사용 사례에 대한 최적화

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

• 대화형 에이전트: 긴 지침이나 업로드된 문서가 있는 경우 특히 확장된 대화의 비용과 지연 시간을 줄입니다.
• 코딩 어시스턴트: 코드베이스의 관련 섹션이나 요약된 버전을 프롬프트에 유지하여 자동 완성 및 코드베이스 Q&A를 개선합니다.
• 대용량 문서 처리: 이미지를 포함한 완전한 장문의 자료를 응답 지연 시간을 증가시키지 않고 프롬프트에 통합합니다.
• 상세한 지침 세트: Claude의 응답을 미세 조정하기 위해 광범위한 지침, 절차 및 예시 목록을 공유합니다. 개발자들은 종종 프롬프트에 한두 개의 예시를 포함시키지만, 프롬프트 캐싱을 사용하면 20개 이상의 다양한 고품질 답변 예시를 포함시켜 더 나은 성능을 얻을 수 있습니다.
• 에이전트 도구 사용: 각 단계가 일반적으로 새로운 API 호출을 필요로 하는 여러 도구 호출과 반복적인 코드 변경이 포함된 시나리오의 성능을 향상시킵니다.
• 책, 논문, 문서, 팟캐스트 대본 및 기타 장문 콘텐츠와 대화: 전체 문서를 프롬프트에 포함시키고 사용자가 질문할 수 있도록 하여 모든 지식 기반을 활성화합니다.

​

일반적인 문제 해결

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

• 캐시된 섹션이 동일하고 호출 간에 동일한 위치에 cache_control로 표시되어 있는지 확인하세요
• 호출이 5분의 캐시 수명 내에 이루어졌는지 확인하세요
• tool_choice와 이미지 사용이 호출 간에 일관되게 유지되는지 확인하세요
• 최소 토큰 수 이상을 캐시하고 있는지 확인하세요

프롬프트 어디에서든 tool_choice를 변경하거나 이미지의 존재/부재를 변경하면 캐시가 무효화되어 새로운 캐시 항목을 생성해야 합니다.

---

​

캐시 저장 및 공유

• 조직 격리: 캐시는 조직 간에 격리됩니다. 동일한 프롬프트를 사용하더라도 서로 다른 조직은 절대 캐시를 공유하지 않습니다.

• 정확한 매칭: 캐시 히트는 cache control로 표시된 블록까지 모든 텍스트와 이미지를 포함하여 100% 동일한 프롬프트 세그먼트가 필요합니다. 캐시 읽기와 생성 시 동일한 블록이 cache_control로 표시되어 있어야 합니다.

• 출력 토큰 생성: 프롬프트 캐싱은 출력 토큰 생성에 영향을 미치지 않습니다. 프롬프트 캐싱을 사용하지 않았을 때와 동일한 응답을 받게 됩니다.

---

​

프롬프트 캐싱 예시

프롬프트 캐싱을 시작하는 데 도움이 되도록 자세한 예시와 모범 사례가 포함된 프롬프트 캐싱 쿡북을 준비했습니다.

아래에는 다양한 프롬프트 캐싱 패턴을 보여주는 여러 코드 스니펫을 포함했습니다. 이 예시들은 이 기능의 실제 적용을 이해하는 데 도움이 되도록 다양한 시나리오에서 캐싱을 구현하는 방법을 보여줍니다:

---

​

FAQ