메인 콘텐츠로 건너뛰기

​
개요

​
제공자 프롬프트 캐시 작동 방식

제공자 프롬프트 캐싱은 프롬프트 접두사의 처리된 표현을 제공자의 서버에 저장합니다. 동일한 접두사를 포함한 요청을 보내면, 제공자는 해당 토큰들을 다시 처리하는 과정을 생략할 수 있습니다.

​
주요 특징

  • 접두사(Prefix) 기반: 프롬프트의 시작 부분만 캐싱 가능
  • 정확한 일치: 시맨틱 유사성이 아닌 동일한 토큰 필요
  • 시간 제한: 캐시 항목은 만료됨 (일반적으로 5~60분)
  • 자동: 별도의 설정 필요 없음
Request 1: [System prompt + Context A + Question 1]
           ^^^^^^^^^^^^^^^^^^^^^^^^
           이 접두사가 캐싱됩니다.

Request 2: [System prompt + Context A + Question 2]
           ^^^^^^^^^^^^^^^^^^^^^^^^
           캐시 히트! Question 2만 처리됩니다.

​
지원되는 제공자

제공자캐시 읽기 할인캐시 쓰기 비용최소 토큰
Anthropic90% 할인25% 프리미엄1024
OpenAI50% 할인입력 비용과 동일1024
DeepSeek90% 할인입력 비용과 동일64
Google75% 할인25% 프리미엄32768
할인은 자동으로 적용됩니다. AI Sonar는 제공자의 캐시 가격 정책을 그대로 사용자에게 전달합니다.

​
캐시 사용량 확인

​
사용 로그에서

사용 로그에서 상세한 캐시 토큰 내역을 확인할 수 있습니다:
필드설명
cacheReadTokens제공자 캐시에서 제공된 토큰 (할인 적용)
cacheWriteTokens캐시에 기록된 토큰 (향후 요청용)
nonCachedPromptTokens캐시 없이 처리된 토큰

​
트랜잭션에서

업스트림 캐싱이 사용된 경우 트랜잭션에 제공자 Cache 라벨이 표시됩니다:
  • 제공자 Cache (청록색): 업스트림 프롬프트 캐시 히트 - 할인 요금 적용

​
비용 계산 예시

Claude (Anthropic)에 10,000개의 입력 토큰을 보내는 요청의 경우: 캐시 미사용 시: 
10,000 tokens × $3.00/1M = $0.030
제공자 캐시 사용 시 (8,000개 캐시됨 + 2,000개 신규): 
Cache read:  8,000 tokens × $0.30/1M = $0.0024  (90% 할인)
Cache write: 2,000 tokens × $3.75/1M = $0.0075
Total: $0.0099 (67% 절감)

​
권장 사항

시스템 프롬프트와 정적 컨텍스트를 메시지의 시작 부분에 배치하세요. 이는 캐시 히트 가능성을 극대화합니다.
캐시가 만료되기 전에 혜택을 볼 수 있도록 동일한 접두사를 가진 요청들을 짧은 시간 간격 내에 보내세요.
캐싱 가능한 접두사가 제공자의 최소 기준(예: Anthropic/OpenAI의 경우 1024 토큰)을 충족하는지 확인하세요.
대시보드 사용 통계에서 캐시 히트율과 절감액을 확인하세요.

​
캐시 상태 확인

​
응답 헤더

X-Upstream-Cache-Read: 8000   # 제공자 캐시 읽기 토큰
X-Upstream-Cache-Write: 2000  # 제공자 캐시 쓰기 토큰

​
사용량 API

사용 로그를 쿼리하여 캐시 내역을 확인할 수 있습니다: 
GET /v1/usage/logs is currently not a public endpoint.
Use X-Upstream-Cache-* response headers, plus the dashboard usage page.
응답 예시: 
{
  "promptTokens": 10000,
  "cacheReadTokens": 8000,
  "cacheWriteTokens": 2000,
  "nonCachedPromptTokens": 0,
  "completionTokens": 500,
  "cost": 0.0099
}

​
자주 묻는 질문 (FAQ)

제공자 캐싱은 자동으로 이루어지며 비활성화할 수 없습니다. 하지만 이는 비용 절감이라는 혜택만 제공하므로 비활성화할 이유가 없습니다.
일반적인 원인은 다음과 같습니다:
  • 접두사가 변경됨 (단 하나의 토큰 차이도 허용 안 됨)
  • 캐시 만료 (일반적으로 5~60분)
  • 접두사가 너무 짧음 (최소 토큰 미달)
  • 다른 API 키 사용
네! 본인의 API 키(BYOK)를 사용할 때도 제공자 캐싱은 동일하게 작동합니다. 캐시는 업스트림 API 키에 귀속됩니다.
  1. 프롬프트 구조를 설계할 때 정적 컨텍스트를 앞에 배치하세요.
  2. 여러 요청에서 시스템 프롬프트를 일관되게 유지하세요.
  3. 관련된 요청들을 빠른 간격으로 보내세요.