Claude 프롬프트 캐싱

이 페이지에서는 Claude에서 프롬프트 캐싱을 켜고 적중 여부를 확인하는 방법을 설명합니다. 모델 ID와 엔드포인트 주소는 Claude 시리즈 개요를 참고하십시오.

요점Claude의 캐시는 cache_control을 명시적으로 표시해야 하며, 두 API 모두 자동으로 캐시하지 않습니다.

길고 고정된 콘텐츠(시스템 프롬프트, 문서, 도구 정의)를 요청 앞부분에 두고, 마지막 고정 콘텐츠 블록에 cache_control을 표시하십시오. 이후 요청의 접두부가 이와 완전히 같으면 캐시가 적중합니다.

Anthropic 네이티브 API

claude_cache.py


import os
import anthropic
 
client = anthropic.Anthropic(base_url="https://api.ofox.ai/anthropic", api_key=os.environ["OFOX_API_KEY"])
LONG_DOC = open("manual.txt", encoding="utf-8").read()  # 비교적 긴 고정 문서
 
for question in ["3장은 어떤 내용입니까?", "전체 내용의 요점을 정리해 주세요."]:
    message = client.messages.create(
        model="anthropic/claude-sonnet-4.6",
        max_tokens=1024,
        system=[
            {"type": "text", "text": "아래 문서를 바탕으로 질문에 답하십시오."},
            {"type": "text", "text": LONG_DOC, "cache_control": {"type": "ephemeral"}},
        ],
        messages=[{"role": "user", "content": question}],
    )
    u = message.usage
    print("쓰기:", u.cache_creation_input_tokens, "읽기:", u.cache_read_input_tokens)

항목	설명
유효 기간	기본 5분이며 적중하면 다시 계산됨. `"cache_control": {"type": "ephemeral", "ttl": "1h"}`는 1시간
적중 확인(네이티브 API)	첫 요청에서 `usage.cache_creation_input_tokens`가 0보다 큼. 적중 시 `usage.cache_read_input_tokens`가 0보다 큼
적중 확인(OpenAI 호환 API)	적중 시 `usage.prompt_tokens_details.cached_tokens`가 0보다 큼
최소 길이	콘텐츠가 너무 짧으면 캐시되지 않으며 두 필드 모두 0. 모델별 최소 캐시 가능 길이는 Anthropic 공식 문서 참고
과금	쓰기와 읽기는 각각 캐시 쓰기 단가와 캐시 읽기 단가로 과금. 모델 페이지 참고

캐시에 대한 일반 설명은 프롬프트 캐싱을 참고하십시오.

기타 오류는 자주 발생하는 오류를 참고하십시오.

Claude 프롬프트 캐싱

Anthropic 네이티브 API

OpenAI 호환 API