Skip to Content
개발 문서고급 기능프롬프트 캐싱

프롬프트 캐싱

Prompt Caching은 반복 사용되는 프롬프트 접두사를 캐싱하여 토큰 소비와 응답 지연을 줄일 수 있습니다.

동작 원리

요청에 길고 반복적으로 사용되는 system prompt 또는 컨텍스트 정보가 포함되어 있을 때:

  1. 첫 번째 요청 — 모든 토큰을 완전히 처리하고, 프롬프트 접두사를 캐싱합니다
  2. 후속 요청 — 캐시가 적중되면, 캐싱된 부분의 토큰은 다시 과금되지 않습니다
  3. 캐시 만료 — 캐시에는 일정한 TTL(일반적으로 5-10분)이 있으며, 만료 후 다시 캐싱해야 합니다

캐싱 지원

OfoxAI의 모델 리소스는 AWS Bedrock, Azure OpenAI, Google Cloud, Alibaba Cloud, Volcengine 등 모델 공식 클라우드 공급자를 통해 제공됩니다. 클라우드 공급자가 Prompt Caching을 지원하는 모델은 OfoxAI도 동일하게 지원합니다.

클라우드 공급자대표 모델캐싱 메커니즘
AWS BedrockClaude 시리즈네이티브 Prompt Caching
Azure OpenAIGPT-4o 시리즈자동 캐싱
Google CloudGemini 시리즈Context Caching
Alibaba CloudQwen 시리즈플랫폼 측 캐싱
VolcengineDoubao 시리즈플랫폼 측 캐싱

구체적인 모델의 캐시 지원 현황은 각 클라우드 공급자의 공식 문서를 기준으로 합니다. OfoxAI는 캐시 관련 파라미터를 투명하게 전달하므로, 별도의 설정이 필요 없습니다.

사용 방법

OpenAI 프로토콜

OpenAI 모델의 Prompt Caching은 자동으로 작동합니다 — 반복되는 프롬프트 접두사가 감지되면 자동으로 활성화됩니다:

caching_openai.py
# 긴 system prompt는 자동으로 캐싱됩니다 SYSTEM_PROMPT = """당신은 OfoxAI의 기술 지원 어시스턴트입니다. 다음은 알아야 할 제품 정보입니다: - OfoxAI는 LLM Gateway로, 100개 이상의 대형 모델을 지원합니다 - OpenAI / Anthropic / Gemini 3대 프로토콜을 지원합니다 - ... (추가 제품 지식 생략) """ # 첫 번째 요청: system prompt 캐싱 response1 = client.chat.completions.create( model="openai/gpt-4o", messages=[ {"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": "OfoxAI는 어떤 모델을 지원하나요?"} ] ) # 두 번째 요청: 캐시 적중, 더 빠르고 저렴 response2 = client.chat.completions.create( model="openai/gpt-4o", messages=[ {"role": "system", "content": SYSTEM_PROMPT}, # 캐시 적중 {"role": "user", "content": "Claude Code는 어떻게 설정하나요?"} ] )

Anthropic 프로토콜

Anthropic 모델은 명시적인 캐시 제어를 지원합니다:

caching_anthropic.py
import anthropic client = anthropic.Anthropic( base_url="https://api.ofox.ai/anthropic", api_key="<OFOXAI_API_KEY>" ) response = client.messages.create( model="anthropic/claude-sonnet-4.5", max_tokens=1024, system=[{ "type": "text", "text": "당신은 전문 어시스턴트입니다. 다음은 제품 문서입니다...", "cache_control": {"type": "ephemeral"} # 명시적으로 캐싱 활성화 }], messages=[{"role": "user", "content": "제품 특징을 요약해주세요"}] ) # 캐시 적중 상황 확인 print(f"캐시 기록 토큰: {response.usage.cache_creation_input_tokens}") print(f"캐시 적중 토큰: {response.usage.cache_read_input_tokens}")

비용 절감

캐시 적중 후, 캐싱된 부분의 토큰은 더 낮은 가격으로 과금되며, 절감 비율은 모델에 따라 다릅니다:

  • Anthropic Claude 시리즈 — 캐시 적중 시 입력 비용의 약 90% 절감
  • OpenAI GPT 시리즈 — 캐시 적중 시 입력 비용의 약 50% 절감
  • Google Gemini 시리즈 — 캐시 적중 시 입력 비용의 약 50-75% 절감

실제 절감 비율은 캐시 적중률과 각 클라우드 공급자의 과금 정책에 따라 달라집니다. 자세한 내용은 OfoxAI 콘솔의 사용량 통계를 참조하세요.

모범 사례

  1. 긴 텍스트를 앞에 배치 — system prompt, 지식 베이스 콘텐츠 등 변하지 않는 부분을 messages 앞에 배치
  2. 접두사 일관성 유지 — 완전히 동일한 접두사만 캐시에 적중
  3. 프롬프트 구조를 합리적으로 설계 — 고정 부분과 변동 부분을 분리
# ✅ 좋은 설계: 고정 콘텐츠가 앞에, 변동 콘텐츠가 뒤에 messages = [ {"role": "system", "content": LONG_STATIC_PROMPT}, # 캐싱 가능 {"role": "user", "content": dynamic_question} # 변동 부분 ] # ❌ 나쁜 설계: 변동 콘텐츠가 고정 콘텐츠 사이에 끼어 있음 messages = [ {"role": "system", "content": f"Today is {date}. {LONG_PROMPT}"} # 매일 달라져 캐싱 불가 ]

캐시 적중 여부는 API 응답의 usage 필드에서 확인할 수 있으며, OfoxAI 콘솔의 사용량 통계에서 캐시 적중률을 확인할 수도 있습니다.

Last updated on