핵심 정리
| 항목 | 기준 |
|---|---|
| 목적 | 반복되는 긴 prefix의 비용과 지연 줄이기 |
| 자동 caching | 요청 top-level cache_control 사용 |
| 명시적 breakpoint | content block에 cache_control 지정 |
| 기본 TTL | 5분 |
| 확장 TTL | 1시간, 추가 비용 고려 |
| cache 범위 | tools -> system -> messages 순서의 prefix |
json
{
"model": "claude-opus-4-7",
"max_tokens": 1024,
"cache_control": { "type": "ephemeral" },
"system": "You are an assistant for a large policy document.",
"messages": [
{
"role": "user",
"content": "Summarize the compliance risks."
}
]
}구조
Prompt caching은 응답을 저장하는 기능이 아니라, 요청 앞부분의 동일한 prompt prefix를 다시 처리하지 않도록 하는 기능입니다. 같은 도구 정의, 같은 system instruction, 같은 긴 문서나 예시 묶음이 반복될 때 효과가 큽니다.
text
static prefix
-> tools
-> system
-> long context
dynamic tail
-> user question자동 caching은 시작하기 쉽습니다. top-level cache_control을 두면 시스템이 마지막 cacheable block까지를 cache 대상으로 잡고, 대화가 길어질수록 breakpoint를 앞으로 이동시킵니다.
명시적 breakpoint는 더 세밀합니다. 고정 정책, 긴 문서, 예시 묶음처럼 바뀌는 주기가 다른 덩어리에 직접 cache_control을 붙여 cache 경계를 관리합니다.
json
{
"type": "text",
"text": "<long reusable policy text>",
"cache_control": {
"type": "ephemeral",
"ttl": "1h"
}
}선택 기준
| 상황 | 선택 |
|---|---|
| 긴 system prompt와 문서가 반복됨 | prompt caching |
| 짧은 단발성 질문 | caching 없이 단순 요청 |
| 대화형 agent가 같은 맥락을 반복 사용 | 자동 caching |
| 문서, 예시, tool 정의의 변경 주기가 다름 | 명시적 breakpoint |
| 후속 요청이 5분을 넘겨 이어짐 | 1시간 TTL 검토 |
| cache hit 여부를 봐야 함 | usage의 cache token 필드 확인 |
Cache hit는 prefix가 동일해야 발생합니다. tool 정의, system prompt, message block 순서가 바뀌면 해당 지점 이후의 cache가 깨질 수 있습니다.
주의할 점
Prompt caching은 출력 token 비용을 줄이는 기능이 아닙니다. 긴 입력을 다시 처리하는 비용과 지연을 줄이는 기능이므로, 응답이 길거나 후처리가 비싼 문제는 별도로 관리해야 합니다.
또 cache는 정확히 같은 prefix에 의존합니다. 실험 중 system prompt나 tool schema를 자주 바꾸면 cache hit가 거의 나지 않을 수 있으므로, 안정된 부분과 실험하는 부분을 분리하세요.
참고 링크
1 sources