프롬프트 캐싱
Prompt Caching은 반복 사용되는 프롬프트 접두사를 캐싱하여 토큰 소비와 응답 지연을 줄일 수 있습니다.
동작 원리
요청에 길고 반복적으로 사용되는 system prompt 또는 컨텍스트 정보가 포함되어 있을 때:
- 첫 번째 요청 — 모든 토큰을 완전히 처리하고, 프롬프트 접두사를 캐싱합니다
- 후속 요청 — 캐시가 적중되면, 캐싱된 부분의 토큰은 다시 과금되지 않습니다
- 캐시 만료 — 캐시에는 일정한 TTL(일반적으로 5-10분)이 있으며, 만료 후 다시 캐싱해야 합니다
캐싱 지원
OfoxAI의 모델 리소스는 AWS Bedrock, Azure OpenAI, Google Cloud, Alibaba Cloud, Volcengine 등 모델 공식 클라우드 공급자를 통해 제공됩니다. 클라우드 공급자가 Prompt Caching을 지원하는 모델은 OfoxAI도 동일하게 지원합니다.
| 클라우드 공급자 | 대표 모델 | 캐싱 메커니즘 |
|---|---|---|
| AWS Bedrock | Claude 시리즈 | 네이티브 Prompt Caching |
| Azure OpenAI | GPT-4o 시리즈 | 자동 캐싱 |
| Google Cloud | Gemini 시리즈 | Context Caching |
| Alibaba Cloud | Qwen 시리즈 | 플랫폼 측 캐싱 |
| Volcengine | Doubao 시리즈 | 플랫폼 측 캐싱 |
구체적인 모델의 캐시 지원 현황은 각 클라우드 공급자의 공식 문서를 기준으로 합니다. OfoxAI는 캐시 관련 파라미터를 투명하게 전달하므로, 별도의 설정이 필요 없습니다.
이 문서는 자동 / 암시적 캐싱(모델이 반복 접두사를 최선 노력으로 재사용)을 다룹니다. 대용량의 반복 재사용 컨텍스트를 직접 캐시로 생성하여 확정적으로 적중시켜야 한다면, Gemini는 명시적 캐싱도 지원합니다 —— Gemini 명시적 캐싱(cachedContents)을 확인하세요.
사용 방법
OpenAI 프로토콜
OpenAI 모델의 Prompt Caching은 자동으로 작동합니다 — 반복되는 프롬프트 접두사가 감지되면 자동으로 활성화됩니다:
# 긴 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 모델은 명시적인 캐시 제어를 지원합니다:
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.6",
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 콘솔의 사용량 통계를 참조하세요.
모범 사례
- 긴 텍스트를 앞에 배치 — system prompt, 지식 베이스 콘텐츠 등 변하지 않는 부분을 messages 앞에 배치
- 접두사 일관성 유지 — 완전히 동일한 접두사만 캐시에 적중
- 프롬프트 구조를 합리적으로 설계 — 고정 부분과 변동 부분을 분리
# ✅ 좋은 설계: 고정 콘텐츠가 앞에, 변동 콘텐츠가 뒤에
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 콘솔의 사용량 통계에서 캐시 적중률을 확인할 수도 있습니다.