프롬프트 캐싱
프롬프트 캐싱은 프롬프트의 특정 접두사에서 재개할 수 있도록 하여 API 사용을 최적화하는 강력한 기능입니다. 이 접근 방식은 반복적인 작업이나 일관된 요소가 있는 프롬프트의 처리 시간과 비용을 크게 줄입니다.
다음은 cache_control 블록을 사용하여 Messages API로 프롬프트 캐싱을 구현하는 방법의 예입니다:
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-sonnet-4-5",
"max_tokens": 1024,
"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.\n"
},
{
"type": "text",
"text": "<the entire contents of Pride and Prejudice>",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{
"role": "user",
"content": "Analyze the major themes in Pride and Prejudice."
}
]
}'
# Call the model again with the same inputs up to the cache checkpoint
curl https://api.anthropic.com/v1/messages # rest of inputimport anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
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.\n",
},
{
"type": "text",
"text": "<the entire contents of 'Pride and Prejudice'>",
"cache_control": {"type": "ephemeral"}
}
],
messages=[{"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}],
)
print(response.usage.model_dump_json())
# Call the model again with the same inputs up to the cache checkpoint
response = client.messages.create(.....)
print(response.usage.model_dump_json())import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-sonnet-4-5",
max_tokens: 1024,
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.\n",
},
{
type: "text",
text: "<the entire contents of 'Pride and Prejudice'>",
cache_control: { type: "ephemeral" }
}
],
messages: [
{
role: "user",
content: "Analyze the major themes in 'Pride and Prejudice'."
}
]
});
console.log(response.usage);
// Call the model again with the same inputs up to the cache checkpoint
const new_response = await client.messages.create(...)
console.log(new_response.usage);import java.util.List;
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.CacheControlEphemeral;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.TextBlockParam;
public class PromptCachingExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_20250514)
.maxTokens(1024)
.systemOfTextBlockParams(List.of(
TextBlockParam.builder()
.text("You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n")
.build(),
TextBlockParam.builder()
.text("<the entire contents of 'Pride and Prejudice'>")
.cacheControl(CacheControlEphemeral.builder().build())
.build()
))
.addUserMessage("Analyze the major themes in 'Pride and Prejudice'.")
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}{"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 호출에서 이 큰 텍스트를 재사용할 수 있습니다. 사용자 메시지만 변경하면 책에 대한 다양한 질문을 할 수 있으면서 캐시된 콘텐츠를 활용하여 더 빠른 응답과 향상된 효율성을 얻을 수 있습니다.
프롬프트 캐싱의 작동 원리
프롬프트 캐싱이 활성화된 요청을 보낼 때:
- 시스템은 지정된 캐시 중단점까지의 프롬프트 접두사가 최근 쿼리에서 이미 캐시되어 있는지 확인합니다.
- 발견되면 캐시된 버전을 사용하여 처리 시간과 비용을 줄입니다.
- 그렇지 않으면 전체 프롬프트를 처리하고 응답이 시작되면 접두사를 캐시합니다.
이는 다음과 같은 경우에 특히 유용합니다:
- 많은 예제가 있는 프롬프트
- 많은 양의 컨텍스트 또는 배경 정보
- 일관된 지침이 있는 반복적인 작업
- 긴 다중 턴 대화
기본적으로 캐시의 수명은 5분입니다. 캐시된 콘텐츠가 사용될 때마다 추가 비용 없이 캐시가 새로 고쳐집니다.
프롬프트 캐싱은 전체 접두사를 캐시합니다
프롬프트 캐싱은 전체 프롬프트 - tools, system, messages(이 순서대로)를 cache_control로 지정된 블록까지 참조합니다.
가격 책정
프롬프트 캐싱은 새로운 가격 책정 구조를 도입합니다. 아래 표는 지원되는 각 모델에 대한 백만 토큰당 가격을 보여줍니다:
| Model | Base Input Tokens | 5m Cache Writes | 1h Cache Writes | Cache Hits & Refreshes | Output Tokens |
|---|---|---|---|---|---|
| Claude Opus 4.1 | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Opus 4 | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Sonnet 4.5 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 3.7 (deprecated) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Haiku 4.5 | $1 / MTok | $1.25 / MTok | $2 / MTok | $0.10 / MTok | $5 / MTok |
| Claude Haiku 3.5 | $0.80 / MTok | $1 / MTok | $1.6 / MTok | $0.08 / MTok | $4 / MTok |
| Claude Opus 3 (deprecated) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Haiku 3 | $0.25 / MTok | $0.30 / MTok | $0.50 / MTok | $0.03 / MTok | $1.25 / MTok |
위의 표는 프롬프트 캐싱에 대한 다음 가격 책정 배수를 반영합니다:
- 5분 캐시 쓰기 토큰은 기본 입력 토큰 가격의 1.25배입니다
- 1시간 캐시 쓰기 토큰은 기본 입력 토큰 가격의 2배입니다
- 캐시 읽기 토큰은 기본 입력 토큰 가격의 0.1배입니다
프롬프트 캐싱을 구현하는 방법
지원되는 모델
프롬프트 캐싱은 현재 다음에서 지원됩니다:
- Claude Opus 4.1
- Claude Opus 4
- Claude Sonnet 4.5
- Claude Sonnet 4
- Claude Sonnet 3.7
- Claude Haiku 4.5
- Claude Haiku 3.5
- Claude Haiku 3
- Claude Opus 3 (deprecated)
프롬프트 구조화
정적 콘텐츠(도구 정의, 시스템 지침, 컨텍스트, 예제)를 프롬프트의 시작 부분에 배치합니다. cache_control 매개변수를 사용하여 캐싱을 위한 재사용 가능한 콘텐츠의 끝을 표시합니다.
캐시 접두사는 다음 순서대로 생성됩니다: tools, system, messages. 이 순서는 각 수준이 이전 수준을 기반으로 하는 계층 구조를 형성합니다.
자동 접두사 확인이 작동하는 방식
정적 콘텐츠의 끝에 하나의 캐시 중단점만 사용할 수 있으며, 시스템은 자동으로 가장 긴 일치하는 접두사를 찾습니다. 이것이 어떻게 작동하는지 이해하면 캐싱 전략을 최적화하는 데 도움이 됩니다.
세 가지 핵심 원칙:
-
캐시 키는 누적됩니다:
cache_control로 블록을 명시적으로 캐시할 때, 캐시 해시 키는 대화에서 이전의 모든 블록을 순차적으로 해싱하여 생성됩니다. 이는 각 블록의 캐시가 그 앞의 모든 콘텐츠에 따라 달라진다는 의미입니다. -
역순 순차 확인: 시스템은 명시적 중단점에서 역순으로 작업하여 각 이전 블록을 역순으로 확인하여 캐시 히트를 확인합니다. 이는 가능한 가장 긴 캐시 히트를 얻을 수 있도록 보장합니다.
-
20블록 룩백 윈도우: 시스템은 각 명시적
cache_control중단점 전에 최대 20개의 블록만 확인합니다. 일치하는 항목 없이 20개의 블록을 확인한 후 확인을 중지하고 다음 명시적 중단점(있는 경우)으로 이동합니다.
예: 룩백 윈도우 이해하기
30개의 콘텐츠 블록이 있는 대화를 고려하고 블록 30에만 cache_control을 설정합니다:
-
이전 블록에 변경 사항이 없이 블록 31을 보내는 경우: 시스템은 블록 30을 확인합니다(일치!). 블록 30에서 캐시 히트를 얻고 블록 31만 처리하면 됩니다.
-
블록 25를 수정하고 블록 31을 보내는 경우: 시스템은 블록 30 → 29 → 28... → 25(일치 없음) → 24(일치!)에서 역순으로 확인합니다. 블록 24가 변경되지 않았으므로 블록 24에서 캐시 히트를 얻고 블록 25-30만 다시 처리하면 됩니다.
-
블록 5를 수정하고 블록 31을 보내는 경우: 시스템은 블록 30 → 29 → 28... → 11(확인 #20)에서 역순으로 확인합니다. 일치하는 항목을 찾지 못한 채 20번 확인한 후 확인을 중지합니다. 블록 5가 20블록 윈도우를 벗어났으므로 캐시 히트가 발생하지 않고 모든 블록을 다시 처리해야 합니다. 그러나 블록 5에 명시적
cache_control중단점을 설정했다면 시스템은 해당 중단점에서 계속 확인합니다: 블록 5(일치 없음) → 블록 4(일치!). 이를 통해 블록 4에서 캐시 히트를 얻을 수 있으며, 이는 편집 가능한 콘텐츠 전에 중단점을 배치해야 하는 이유를 보여줍니다.
핵심 요점: 캐시 히트 확률을 최대화하려면 항상 대화의 끝에 명시적 캐시 중단점을 설정하세요. 또한 편집 가능한 콘텐츠 블록 바로 앞에 중단점을 설정하여 해당 섹션을 독립적으로 캐시할 수 있도록 하세요.
여러 중단점을 사용하는 경우
다음을 원하는 경우 최대 4개의 캐시 중단점을 정의할 수 있습니다:
- 다양한 빈도로 변경되는 다양한 섹션을 캐시합니다(예: 도구는 거의 변경되지 않지만 컨텍스트는 매일 업데이트됨).
- 정확히 무엇이 캐시되는지에 대한 더 많은 제어를 갖습니다.
- 최종 중단점 전에 20개 이상의 콘텐츠 블록이 있는 콘텐츠에 대한 캐싱을 보장합니다.
- 편집 가능한 콘텐츠 전에 중단점을 배치하여 20블록 윈도우를 벗어난 변경이 발생해도 캐시 히트를 보장합니다.
중요한 제한 사항: 프롬프트에 캐시 중단점 전에 20개 이상의 콘텐츠 블록이 있고 해당 블록보다 앞의 콘텐츠를 수정하면 해당 콘텐츠에 더 가까운 추가 명시적 중단점을 추가하지 않는 한 캐시 히트를 얻지 못합니다.
캐시 제한 사항
최소 캐시 가능 프롬프트 길이는:
- Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7(deprecated), Claude Opus 3(deprecated)의 경우 1024토큰
- Claude Haiku 4.5의 경우 4096토큰
- Claude Haiku 3.5 및 Claude Haiku 3의 경우 2048토큰
더 짧은 프롬프트는 cache_control로 표시되어 있어도 캐시할 수 없습니다. 이 토큰 수보다 적은 토큰을 캐시하려는 요청은 캐싱 없이 처리됩니다. 프롬프트가 캐시되었는지 확인하려면 응답 사용 필드를 참조하세요.
동시 요청의 경우 캐시 항목은 첫 번째 응답이 시작된 후에만 사용 가능해집니다. 병렬 요청에 대한 캐시 히트가 필요한 경우 첫 번째 응답을 기다린 후 후속 요청을 보내세요.
현재 "ephemeral"이 유일하게 지원되는 캐시 유형이며, 기본적으로 5분의 수명을 가집니다.
캐시 중단점 비용 이해
캐시 중단점 자체는 비용을 추가하지 않습니다. 다음에 대해서만 청구됩니다:
- 캐시 쓰기: 새 콘텐츠가 캐시에 기록될 때(5분 TTL의 경우 기본 입력 토큰보다 25% 더 많음)
- 캐시 읽기: 캐시된 콘텐츠가 사용될 때(기본 입력 토큰 가격의 10%)
- 일반 입력 토큰: 캐시되지 않은 콘텐츠의 경우
더 많은 cache_control 중단점을 추가해도 비용이 증가하지 않습니다. 실제로 캐시되고 읽혀지는 콘텐츠의 양에 따라 동일한 금액을 지불합니다. 중단점은 단순히 어떤 섹션을 독립적으로 캐시할 수 있는지에 대한 제어를 제공합니다.
캐시할 수 있는 것
요청의 대부분의 블록은 cache_control로 캐싱을 위해 지정할 수 있습니다. 여기에는 다음이 포함됩니다:
- 도구:
tools배열의 도구 정의 - 시스템 메시지:
system배열의 콘텐츠 블록 - 텍스트 메시지:
messages.content배열의 콘텐츠 블록(사용자 및 어시스턴트 턴 모두) - 이미지 및 문서: 사용자 턴의
messages.content배열의 콘텐츠 블록 - 도구 사용 및 도구 결과:
messages.content배열의 콘텐츠 블록(사용자 및 어시스턴트 턴 모두)
이러한 각 요소는 cache_control로 표시하여 요청의 해당 부분에 대한 캐싱을 활성화할 수 있습니다.
캐시할 수 없는 것
대부분의 요청 블록을 캐시할 수 있지만 몇 가지 예외가 있습니다:
-
사고 블록은
cache_control로 직접 캐시할 수 없습니다. 그러나 사고 블록은 이전 어시스턴트 턴에 나타날 때 다른 콘텐츠와 함께 캐시될 수 있습니다. 이런 방식으로 캐시될 때 캐시에서 읽을 때 입력 토큰으로 계산됩니다. -
하위 콘텐츠 블록(예: 인용)은 직접 캐시할 수 없습니다. 대신 최상위 블록을 캐시하세요.
인용의 경우 인용의 소스 자료로 제공되는 최상위 문서 콘텐츠 블록을 캐시할 수 있습니다. 이를 통해 인용이 참조할 문서를 캐시하여 인용과 함께 프롬프트 캐싱을 효과적으로 사용할 수 있습니다.
-
빈 텍스트 블록은 캐시할 수 없습니다.
캐시를 무효화하는 것
캐시된 콘텐츠에 대한 수정은 일부 또는 전체 캐시를 무효화할 수 있습니다.
프롬프트 구조화에서 설명한 대로 캐시는 계층 구조를 따릅니다: tools → system → messages. 각 수준의 변경 사항은 해당 수준과 모든 후속 수준을 무효화합니다.
다음 표는 다양한 유형의 변경으로 인해 캐시의 어느 부분이 무효화되는지 보여줍니다. ✘는 캐시가 무효화됨을 나타내고 ✓는 캐시가 유효함을 나타냅니다.
| 변경 사항 | 도구 캐시 | 시스템 캐시 | 메시지 캐시 | 영향 |
|---|---|---|---|---|
| 도구 정의 | ✘ | ✘ | ✘ | 도구 정의(이름, 설명, 매개변수) 수정은 전체 캐시를 무효화합니다 |
| 웹 검색 토글 | ✓ | ✘ | ✘ | 웹 검색 활성화/비활성화는 시스템 프롬프트를 수정합니다 |
| 인용 토글 | ✓ | ✘ | ✘ | 인용 활성화/비활성화는 시스템 프롬프트를 수정합니다 |
| 도구 선택 | ✓ | ✓ | ✘ | tool_choice 매개변수 변경은 메시지 블록에만 영향을 미칩니다 |
| 이미지 | ✓ | ✓ | ✘ | 프롬프트의 어디든 이미지 추가/제거는 메시지 블록에 영향을 미칩니다 |
| 사고 매개변수 | ✓ | ✓ | ✘ | 확장 사고 설정 변경(활성화/비활성화, 예산)은 메시지 블록에 영향을 미칩니다 |
| 확장 사고 요청에 전달된 비도구 결과 | ✓ | ✓ | ✘ | 확장 사고가 활성화된 상태에서 비도구 결과가 요청에 전달되면 이전에 캐시된 모든 사고 블록이 컨텍스트에서 제거되고 해당 사고 블록을 따르는 컨텍스트의 모든 메시지가 캐시에서 제거됩니다. 자세한 내용은 사고 블록을 사용한 캐싱을 참조하세요. |
캐시 성능 추적
응답의 usage 내에서 이러한 API 응답 필드를 사용하여 캐시 성능을 모니터링합니다(스트리밍인 경우 message_start 이벤트):
cache_creation_input_tokens: 새 항목을 만들 때 캐시에 기록된 토큰 수입니다.cache_read_input_tokens: 이 요청에 대해 캐시에서 검색된 토큰 수입니다.input_tokens: 캐시에서 읽거나 캐시를 만드는 데 사용되지 않은 입력 토큰 수입니다.
효과적인 캐싱을 위한 모범 사례
프롬프트 캐싱 성능을 최적화하려면:
- 시스템 지침, 배경 정보, 큰 컨텍스트 또는 빈번한 도구 정의와 같은 안정적이고 재사용 가능한 콘텐츠를 캐시합니다.
- 캐시된 콘텐츠를 최상의 성능을 위해 프롬프트의 시작 부분에 배치합니다.
- 캐시 중단점을 전략적으로 사용하여 다양한 캐시 가능한 접두사 섹션을 분리합니다.
- 특히 20개 이상의 콘텐츠 블록이 있는 프롬프트로 작업할 때 캐시 히트율을 최대화하기 위해 대화의 끝과 편집 가능한 콘텐츠 바로 앞에 캐시 중단점을 설정합니다.
- 캐시 히트율을 정기적으로 분석하고 필요에 따라 전략을 조정합니다.
다양한 사용 사례에 맞게 최적화
프롬프트 캐싱 전략을 시나리오에 맞게 조정합니다:
- 대화형 에이전트: 특히 긴 지침이나 업로드된 문서가 있는 확장된 대화의 비용과 지연 시간을 줄입니다.
- 코딩 어시스턴트: 관련 섹션이나 코드베이스의 요약 버전을 프롬프트에 유지하여 자동 완성 및 코드베이스 Q&A를 개선합니다.
- 대규모 문서 처리: 이미지를 포함한 완전한 장문 자료를 프롬프트에 통합하여 응답 지연 시간을 증가시키지 않습니다.
- 상세한 지침 세트: 광범위한 지침, 절차 및 예제 목록을 공유하여 Claude의 응답을 미세 조정합니다. 개발자는 종종 프롬프트에 한두 가지 예제를 포함하지만 프롬프트 캐싱을 사용하면 20개 이상의 다양한 고품질 답변 예제를 포함하여 훨씬 더 나은 성능을 얻을 수 있습니다.
- 에이전트 도구 사용: 여러 도구 호출 및 반복적인 코드 변경이 포함된 시나리오의 성능을 향상시킵니다. 각 단계는 일반적으로 새로운 API 호출이 필요합니다.
- 책, 논문, 문서, 팟캐스트 필사본 및 기타 장문 콘텐츠와 대화: 전체 문서를 프롬프트에 포함하고 사용자가 질문하도록 하여 모든 지식 기반을 활성화합니다.
일반적인 문제 해결
예상치 못한 동작이 발생하는 경우:
- 캐시된 섹션이 동일하고 호출 전체에서 동일한 위치에 cache_control로 표시되어 있는지 확인합니다
- 호출이 캐시 수명(기본적으로 5분) 내에 이루어지는지 확인합니다
tool_choice및 이미지 사용이 호출 간에 일관되게 유지되는지 확인합니다- 최소 토큰 수를 캐시하고 있는지 확인합니다
- 시스템은 자동으로 이전 콘텐츠 블록 경계에서 캐시 히트를 확인합니다(중단점 전에 약 20개 블록). 20개 이상의 콘텐츠 블록이 있는 프롬프트의 경우 모든 콘텐츠를 캐시할 수 있도록 프롬프트의 앞부분에 추가
cache_control매개변수가 필요할 수 있습니다 tool_use콘텐츠 블록의 키가 안정적인 순서를 가지고 있는지 확인합니다. 일부 언어(예: Swift, Go)는 JSON 변환 중에 키 순서를 무작위화하여 캐시를 깨뜨립니다
tool_choice 또는 프롬프트의 어디든 이미지의 존재/부재 변경은 캐시를 무효화하여 새 캐시 항목을 만들어야 합니다. 캐시 무효화에 대한 자세한 내용은 캐시를 무효화하는 것을 참조하세요.
사고 블록을 사용한 캐싱
확장 사고를 프롬프트 캐싱과 함께 사용할 때 사고 블록은 특별한 동작을 합니다:
다른 콘텐츠와 함께 자동 캐싱: 사고 블록은 cache_control로 명시적으로 표시할 수 없지만 도구 결과를 사용하여 후속 API 호출을 할 때 요청 콘텐츠의 일부로 캐시됩니다. 이는 일반적으로 도구 사용 중에 발생하며 사고 블록을 다시 대화에 전달합니다.
입력 토큰 계산: 사고 블록이 캐시에서 읽을 때 사용 메트릭에서 입력 토큰으로 계산됩니다. 이는 비용 계산 및 토큰 예산 책정에 중요합니다.
캐시 무효화 패턴:
- 도구 결과만 사용자 메시지로 제공될 때 캐시는 유효합니다
- 비도구 결과 사용자 콘텐츠가 추가되면 캐시가 무효화되어 모든 이전 사고 블록이 제거됩니다
- 이 캐싱 동작은 명시적
cache_control마커 없이도 발생합니다
캐시 무효화에 대한 자세한 내용은 캐시를 무효화하는 것을 참조하세요.
도구 사용 예제:
요청 1: 사용자: "파리의 날씨는?"
응답: [thinking_block_1] + [tool_use block 1]
요청 2:
사용자: ["파리의 날씨는?"],
어시스턴트: [thinking_block_1] + [tool_use block 1],
사용자: [tool_result_1, cache=True]
응답: [thinking_block_2] + [text block 2]
# 요청 2는 요청 콘텐츠를 캐시합니다(응답 아님)
# 캐시에는 다음이 포함됩니다: 사용자 메시지, thinking_block_1, tool_use block 1, tool_result_1
요청 3:
사용자: ["파리의 날씨는?"],
어시스턴트: [thinking_block_1] + [tool_use block 1],
사용자: [tool_result_1, cache=True],
어시스턴트: [thinking_block_2] + [text block 2],
사용자: [Text response, cache=True]
# 비도구 결과 사용자 블록은 모든 사고 블록을 무시하도록 지정합니다
# 이 요청은 사고 블록이 없었던 것처럼 처리됩니다비도구 결과 사용자 블록이 포함되면 새로운 어시스턴트 루프를 지정하고 모든 이전 사고 블록이 컨텍스트에서 제거됩니다.
자세한 내용은 확장 사고 문서를 참조하세요.
캐시 저장소 및 공유
-
조직 격리: 캐시는 조직 간에 격리됩니다. 동일한 프롬프트를 사용하더라도 다른 조직은 캐시를 공유하지 않습니다.
-
정확한 일치: 캐시 히트는 캐시 제어로 표시된 블록까지 포함한 모든 텍스트 및 이미지를 포함하여 100% 동일한 프롬프트 세그먼트가 필요합니다.
-
출력 토큰 생성: 프롬프트 캐싱은 출력 토큰 생성에 영향을 미치지 않습니다. 받는 응답은 프롬프트 캐싱을 사용하지 않은 경우와 동일합니다.
1시간 캐시 기간
5분이 너무 짧다면 Anthropic은 추가 비용으로 1시간 캐시 기간도 제공합니다.
확장 캐시를 사용하려면 다음과 같이 cache_control 정의에 ttl을 포함합니다:
"cache_control": {
"type": "ephemeral",
"ttl": "5m" | "1h"
}응답에는 다음과 같은 상세한 캐시 정보가 포함됩니다:
{
"usage": {
"input_tokens": ...,
"cache_read_input_tokens": ...,
"cache_creation_input_tokens": ...,
"output_tokens": ...,
"cache_creation": {
"ephemeral_5m_input_tokens": 456,
"ephemeral_1h_input_tokens": 100,
}
}
}현재 cache_creation_input_tokens 필드는 cache_creation 객체의 값의 합과 같습니다.
1시간 캐시를 사용하는 경우
5분마다 사용되는 프롬프트가 있는 경우 5분 캐시를 계속 사용하세요. 이는 추가 비용 없이 계속 새로 고쳐집니다.
1시간 캐시는 다음 시나리오에서 가장 잘 사용됩니다:
- 5분보다 자주 사용되지 않지만 1시간보다 자주 사용될 가능성이 있는 프롬프트가 있는 경우. 예를 들어 에이전트 측 에이전트가 5분 이상 걸리거나 사용자와의 긴 채팅 대화를 저장할 때 일반적으로 사용자가 다음 5분 내에 응답하지 않을 것으로 예상됩니다.
- 지연 시간이 중요하고 후속 프롬프트가 5분 이후에 전송될 수 있는 경우.
- 캐시 히트가 속도 제한에 대해 공제되지 않으므로 속도 제한 활용을 개선하려는 경우.
5분 및 1시간 캐시는 지연 시간과 관련하여 동일하게 동작합니다. 일반적으로 긴 문서에 대해 향상된 첫 토큰까지의 시간을 볼 수 있습니다.
다양한 TTL 혼합
동일한 요청에서 1시간 및 5분 캐시 제어를 사용할 수 있지만 중요한 제약이 있습니다: 더 긴 TTL을 가진 캐시 항목은 더 짧은 TTL보다 먼저 나타나야 합니다(즉, 1시간 캐시 항목은 모든 5분 캐시 항목보다 먼저 나타나야 함).
TTL을 혼합할 때 프롬프트에서 세 가지 청구 위치를 결정합니다:
- 위치
A: 가장 높은 캐시 히트의 토큰 수(히트가 없으면 0). - 위치
B:A이후 가장 높은 1시간cache_control블록의 토큰 수(없으면A와 같음). - 위치
C: 마지막cache_control블록의 토큰 수.
B 및/또는 C가 A보다 크면 A가 가장 높은 캐시 히트이므로 반드시 캐시 미스입니다.
다음에 대해 청구됩니다:
A에 대한 캐시 읽기 토큰.(B - A)에 대한 1시간 캐시 쓰기 토큰.(C - B)에 대한 5분 캐시 쓰기 토큰.
다음은 3가지 예입니다. 이는 3개의 요청의 입력 토큰을 나타내며, 각각 다양한 캐시 히트 및 캐시 미스를 가집니다. 각각은 색상 상자에 표시된 결과로 다른 계산된 가격을 가집니다.
프롬프트 캐싱 예제
프롬프트 캐싱을 시작하는 데 도움이 되도록 상세한 예제 및 모범 사례가 포함된 프롬프트 캐싱 요리책을 준비했습니다.
아래에는 다양한 프롬프트 캐싱 패턴을 보여주는 여러 코드 스니펫이 포함되어 있습니다. 이러한 예제는 다양한 시나리오에서 캐싱을 구현하는 방법을 보여주어 이 기능의 실제 응용을 이해하는 데 도움이 됩니다: