LLM 프롬프트 캐싱 #3: 동작하는 Python 튜토리얼

한 줄 요약 — OpenAI SDK 하나, base_url 하나로 모든 주요 LLM을 사용합니다. 이 글의 수치는 약 7,300 토큰의 안정적인 시스템 프롬프트를 사용해 2026-05-25에 운영 중인 Synthorai 게이트웨이를 상대로 실측한 것입니다. 여기서 게이트웨이의 역할은 소박하고 정직합니다. 단일 엔드포인트, 단일 인증 헤더, 그리고 벤더별 가격 매트릭스를 유지할 필요를 없애 주는 usage.cost 필드, 이게 전부입니다. 캐싱 뒤에 있는 Transformer 수학은 1부: 캐싱 원리에서 다룹니다. 프로바이더별 설계 선택은 2부: 프로바이더 비교에 있습니다.

시리즈: 전 4부 중 3부 · 이전: 1부 — 캐싱 원리 · 2부 — 프로바이더 비교 및 평가 · 다음: 4부 — 사용 사례별 최적 LLM

0. 설정

pip install openai

# common.py — reused across every example
import os, time
from openai import OpenAI

oai = OpenAI(
    api_key=os.environ["SYNTHORAI_KEY"],
    base_url="https://synthorai.io/v1",
)

게이트웨이는 자신이 앞단에서 처리하는 모든 모델(GPT, Claude, Gemini, DeepSeek, Qwen)에 대해 OpenAI의 와이어 포맷을 사용합니다. 바꾸는 것은 model 필드이지 SDK가 아닙니다. 인증은 Authorization: Bearer <key>를 사용합니다.

공개 게이트웨이에서 사용할 수 있는 캐시 지원 모델 ID(2026-05 스냅샷): claude-haiku-4-5, claude-sonnet-4-5 / 4-6, claude-opus-4-5 / 4-6 / 4-7, gpt-5.4-mini, gpt-5.4-nano, gpt-5.2, gpt-5.5-pro, gemini-2.5-flash, gemini-2.5-pro, gemini-3.1-pro-preview, deepseek-v4-flash, qwen3-max, qwen3.5-flash. 전체 실시간 목록은 GET /v1/models에 있습니다.

1. 캐시를 인식하는 호출(모든 프로바이더에서 동일)

옵트인할 필요가 없습니다. 상류에서 프롬프트 캐싱을 지원하는 모델이라면, 게이트웨이는 응답 메타데이터를 그대로 통과시킬 뿐입니다. 무슨 일이 일어났는지는 두 필드가 알려줍니다:

resp = oai.chat.completions.create(
    model="gpt-5.4-mini",
    max_tokens=128,
    messages=[
        {"role": "system", "content": LONG_STABLE_PROMPT},   # ~7K tokens
        {"role": "user",   "content": "First question"},
    ],
)
print(resp.usage.prompt_tokens_details.cached_tokens)   # cache hit count
print(resp.usage.cost)                                  # USD, gateway-computed

cached_tokens는 상류 프리픽스 캐시에 적중한 입력 토큰 수입니다. usage.cost는 게이트웨이가 이 한 번의 호출에 대해 계산한 가격(USD)입니다. 프로바이더별 요율표를 로컬에 유지할 필요가 없습니다.

아키텍처에서 도출되며 모든 프로바이더에 적용되는 두 가지 규칙:

1. 안정적인 내용을 먼저, 변동하는 내용을 나중에. 프리픽스는 토큰 0부터 매칭됩니다. 시작 부분에서 단 한 바이트만 바뀌어도 프리픽스 전체가 무효화됩니다.
2. 동적 데이터를 시스템 프롬프트에 넣지 마세요. 현재 타임스탬프, 세션 ID, 요청 UUID는 모두 캐시를 깨뜨립니다.

아래 내용은 모두 같은 패턴을 벤더별로 예시한 것에 불과합니다.

2. Anthropic Claude —— 명시적 cache_control 마커

Claude는 명시 마커 계열입니다. Anthropic의 API는 자동 캐싱을 하지 않습니다. 캐시 적중을 얻으려면 system 또는 messages 배열에 최대 4개의 cache_control 중단점을 표시합니다. 캐시 읽기는 입력 요율의 약 10%, 캐시 쓰기는 125%(25% 할증)입니다.

게이트웨이를 통해 cache_control을 사용하는 가장 깔끔한 방법은, 공식 anthropic SDK를 게이트웨이의 Anthropic 네이티브 엔드포인트로 향하게 하는 것입니다(OpenAI 호환 /chat/completions 경로는 현재 cache_control 마커를 전파하지 않습니다. Claude 캐싱에는 /v1/messages를 사용하세요).

import os
from anthropic import Anthropic

anth = Anthropic(
    api_key=os.environ["SYNTHORAI_KEY"],
    base_url="https://synthorai.io/",   # SDK appends /v1/messages
)

msg = anth.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=512,
    system=[
        {"type": "text", "text": SYSTEM_INSTRUCTIONS,
         "cache_control": {"type": "ephemeral"}},       # BP 1: never changes
        {"type": "text", "text": TOOL_DESCRIPTIONS,
         "cache_control": {"type": "ephemeral"}},       # BP 2: rarely changes
        {"type": "text", "text": RETRIEVED_DOCUMENTS},  # changes per call — not cached
    ],
    messages=[{"role": "user", "content": question}],
)

print(msg.usage)
# Usage(input_tokens=18, output_tokens=64,
#       cache_creation_input_tokens=0, cache_read_input_tokens=8123,
#       cost=...)

TTL 옵션. {"type": "ephemeral"}는 기본적으로 5분 슬라이딩 TTL(적중할 때마다 만료가 뒤로 밀림)을 사용합니다. 유휴 간격이 5분을 넘는 워크로드에서는 같은 마커에 1시간 TTL을 요청합니다:

"cache_control": {"type": "ephemeral", "ttl": "1h"}

계층화된 중단점. 최대 4개의 마커로 “절대 안 바뀜” + “거의 안 바뀜” + “작업마다 바뀜” 내용을 독립적으로 캐싱할 수 있습니다. 프롬프트의 각 섹션이 서로 다른 주기로 변하는 에이전트와 RAG 워크로드에는 동급 최강의 기능입니다. 마지막 계층(예: 검색된 문서)이 호출마다 바뀌어도, 앞쪽 계층은 여전히 적중합니다.

모델 선택. 2026-05 기준 게이트웨이에서 사용할 수 있는 Claude ID: claude-haiku-4-5, claude-sonnet-4-5 / 4-6, claude-opus-4-5 / 4-6 / 4-7. Haiku는 저렴한 채팅용, Sonnet은 가장 강력한 에이전트 캐싱 패턴을 갖춘 범용용, Opus는 가장 어려운 추론 작업용입니다.

실측 캐시 적중 / 쓰기 / 캐시 없음 기준값(2026-05-25, 약 7,976 토큰 시스템 프롬프트, max_tokens=64):

할인은 계열 전반에 걸쳐 일관되게 유지됩니다. 쓰기 할증은 캐시 없음 대비 약 25%(Anthropic이 문서화한 요율)이며, 손익분기점은 캐시 적중 1회입니다.

3. OpenAI GPT-5.x —— 자동 캐싱

OpenAI는 프리픽스가 충분히 긴 요청을 자동으로 캐싱합니다. 코드 변경도, 마커도 필요 없습니다.

def ask_gpt(question: str):
    t0 = time.perf_counter()
    resp = oai.chat.completions.create(
        model="gpt-5.4-mini",
        max_tokens=64,
        messages=[
            {"role": "system", "content": LONG_STABLE_PROMPT},
            {"role": "user",   "content": question},
        ],
    )
    return resp, time.perf_counter() - t0

r1, t1 = ask_gpt("Which export formats are supported?")
r2, t2 = ask_gpt("How long is the refund window for annual plans?")

print(t1, r1.usage.prompt_tokens_details.cached_tokens, r1.usage.cost)
# 3.63   0       0.00267
print(t2, r2.usage.prompt_tokens_details.cached_tokens, r2.usage.cost)
# 1.23   6400    0.00257

같은 6,887 토큰 프롬프트를 두 번. 두 번째 호출: 시스템 프롬프트의 93%가 캐시에 적중하고, 총 지연 시간이 3.6 s에서 1.2 s로 떨어집니다. 여기서 비용이 거의 변하지 않는 이유는, 캐시 할인이 첫 호출의 더 긴 완료(completion)로 상쇄되기 때문입니다 — 더 깔끔한 크로스 프로바이더 수치는 §7을 참고하세요.

gpt-5.4-nano는 할인을 더 명확하게 보여줍니다(적중 시 비용 44% 감소). time-to-first-token만 신경 쓰는 채팅 UI에서는 스트리밍 수치가 중요합니다:

def ttft(model, question):
    t0 = time.perf_counter()
    stream = oai.chat.completions.create(
        model=model, max_tokens=64,
        messages=[
            {"role": "system", "content": LONG_STABLE_PROMPT},
            {"role": "user",   "content": question},
        ],
        stream=True, stream_options={"include_usage": True},
    )
    for ev in stream:
        if ev.choices and ev.choices[0].delta and ev.choices[0].delta.content:
            return time.perf_counter() - t0     # first content token

캐시 적중 패스에서 실측한 TTFT: gpt-5.4-mini는 0.73 s, gpt-5.4-nano는 1.00 s.

4. Google Gemini —— 암묵적 캐싱

게이트웨이를 통해 접근하면 Gemini의 캐시도 자동입니다. 수행해야 하는 cachedContent 생성 단계가 없습니다.

r = oai.chat.completions.create(
    model="gemini-2.5-flash",
    max_tokens=128,
    messages=[
        {"role": "system", "content": LONG_STABLE_PROMPT},
        {"role": "user",   "content": "Summarize section 6 in two bullets."},
    ],
)
print(r.usage.prompt_tokens_details.cached_tokens, r.usage.cost)

약 7,300 토큰 시스템 프롬프트에 대한 gemini-2.5-flash의 실측 적중: 7,140 캐시 토큰(97%), 비용은 $0.00198에서 $0.00024로 하락 —— 그 패스에서 88% 할인.

알아둘 만한 두 가지 함정:

• Gemini의 *-pro 변형은 추론 모델입니다. max_tokens가 작으면 예산이 숨겨진 사고에 소비되어 completion_tokens=0이 자주 보입니다. 사용자 대면 용도라면 max_tokens를 ≥256으로 올리세요.
• 암묵적 캐시의 TTL은 짧고 공식적으로 명시되어 있지 않습니다. 우리 테스트에서는 5 s 간격의 두 호출 사이에서는 적중이 성공했지만, 약 10 s 뒤의 세 번째 호출은 가끔 미스했습니다. 적중을 가정하는 로직을 설계하지 마세요. cached_tokens를 확인하고 우아하게 폴백하세요.

5. DeepSeek-v4-flash —— 디스크 기반 자동 캐시

DeepSeek의 자동 캐시는 다른 벤더의 GPU 메모리 상주 캐시보다 오래 살아남습니다. 호출 형태는 동일합니다:

r1 = oai.chat.completions.create(
    model="deepseek-v4-flash", max_tokens=128,
    messages=[{"role": "system", "content": LONG_STABLE_PROMPT},
              {"role": "user",   "content": "Q1"}],
)
# r1.usage.cost = $0.00091, cached_tokens = 0

r2 = oai.chat.completions.create(
    model="deepseek-v4-flash", max_tokens=128,
    messages=[{"role": "system", "content": LONG_STABLE_PROMPT},
              {"role": "user",   "content": "Q2"}],
)
# r2.usage.cost = $0.00023, cached_tokens = 6784  →  74% saved

캐시 적중 패스의 스트리밍 TTFT: 2.93 s. 이 세트에서 DeepSeek은 가장 낮은 지연 옵션이 아닙니다 —— 강점은 비용, 그리고 캐시가 시간 단위 간격을 넘어 따뜻하게 유지된다는 점에 있습니다.

6. Alibaba Qwen —— 적중은 보고되지만 할인은 가변적

r = oai.chat.completions.create(
    model="qwen3-max", max_tokens=128,
    messages=[{"role": "system", "content": LONG_STABLE_PROMPT},
              {"role": "user",   "content": "Q1"}],
)
print(r.usage.prompt_tokens_details.cached_tokens, r.usage.cost)
# 7040    0.00549

테스트 실행에서 본 주의점: cached_tokens는 적중을 보고하지만(7,234 중 7,040 = 97%), usage.cost는 캐시 적중 패스에서 떨어지지 않았습니다(여전히 약 $0.0055). 이는 상류 캐시 적중은 일어났지만(TTFT 더 빠름, 1.53 s 대 콜드 3.03 s), 이 프로바이더에 대한 게이트웨이의 비용 필드가 이 날짜에는 아직 캐시 요율 할인을 반영하지 못했음을 의미합니다. Qwen에서 비용에 민감하다면 cached_tokens를 주시하고, 이것이 정상화될 때까지는 상류 가격 페이지를 신뢰하세요.

7. 크로스 프로바이더 벤치마크(2026-05-25 실측)

단일 순차 실행. 7,284자(토크나이저에 따라 약 6,900–7,300 토큰)의 안정적인 시스템 프롬프트. max_tokens=64. 미스 호출 1회 직후 적중 호출 1회.

자동 캐시 프로바이더(마커 불필요):

* gpt-5.4-mini의 미스 호출 완료는 44 토큰, 적중 호출은 19 토큰이었습니다 —— 비용 차이는 캐시 할인과 완료 길이 차이가 섞여 있습니다. 여기서 더 깔끔한 신호는 지연 감소(3.63 → 1.23 s)입니다. † 스트리밍 패스 비용(cached_tokens가 보고된 쪽); 비스트리밍 패스는 Gemini에 대해 가끔 cached_tokens=null을 반환했고 비용이 떨어지지 않았습니다. Gemini에 대한 게이트웨이 메타데이터는 현재 일관되지 않습니다 —— cached_tokens가 있을 때는 그것을 신뢰하세요. ‡ Gemini의 *-pro / *-flash 추론 모델은 작은 max_tokens에서 콘텐츠 토큰을 0개만 내보내는 경우가 많아, 그 예산에서는 TTFT가 무의미합니다. 운영 환경에서 측정한다면 max_tokens를 올리세요. § §6 참고 —— 상류 캐시 적중은 일어났지만(지연은 떨어짐), 게이트웨이의 usage.cost 필드는 이 날짜에 qwen3-max의 할인을 반영하지 않았습니다.

Anthropic Claude는 명시 마커 기반입니다. 할인이 cache_control로 옵트인되기 때문에 수치는 별도 표에 둡니다(패턴은 §2 참고). 같은 프롬프트로 실측한 캐시 쓰기 대 캐시 읽기:

여러분의 수치는 리전, 시간대, 그리고 다른 테넌트 프리픽스의 온도(warmth)에 따라 달라집니다. 단일 실행, 단일 날짜 —— 이를 벤치마크의 절대 진리로 인용하지 마세요.

8. 출시 전 체크리스트

캐시를 인식하는 프롬프트를 배포하기 전에:

1. 안정적인 내용을 먼저 —— 시스템 프롬프트, 지식 베이스, 도구 스키마를 messages 상단에.
2. 변동하는 내용을 나중에 —— 사용자 입력, 검색된 문서, 타임스탬프를 하단에.
3. system에 동적 변수를 넣지 마세요 —— 현재 시각, 사용자 ID, 랜덤 시드는 프리픽스를 날려버립니다.
4. 모든 호출에서 cached_tokens를 로깅하세요. 운영에서 적중률이 50% 미만이면, 프리픽스가 실제로는 안정적이지 않은 것입니다. 미스하는 프롬프트를 조사하세요.
5. 단일 적중 패스를 신뢰하지 마세요. TTL은 짧습니다. “항상 적중”이 아니라 hit_rate ∈ [0, 1)을 전제로 설계하세요.

9. TTL을 인식하는 패턴

운영에서 가장 흔한 실패 모드는 “캐싱을 켜는 걸 잊었다”가 아니라 “요청이 실제로 TTL 윈도우 안에 도착하지 않아 적중률이 12%다”입니다.

8.1 세션에 묶인 워크로드(채팅, IDE 어시스턴트)

자연스러운 주기가 TTL보다 충분히 낮습니다. 프롬프트를 올바르게 구성하면 캐시는 알아서 따뜻하게 유지됩니다 —— 다른 것을 만들지 마세요.

8.2 배치 / Cron을 위한 하트비트

09:00에 일일 보고서를 실행하면서 3분의 버스트 동안 모델을 50번 호출한다면, 캐시가 밤새 콜드가 되었기 때문에 09:00의 첫 캐시 쓰기는 낭비됩니다. 08:55부터 TTL/2마다 캐시된 프리픽스와 함께 1 토큰짜리 “ping”을 보내 따뜻하게 유지하세요:

def keepalive():
    oai.chat.completions.create(
        model="gpt-5.4-mini",
        max_tokens=1,
        messages=[
            {"role": "system", "content": LONG_STABLE_PROMPT},
            {"role": "user",   "content": "."},
        ],
    )

ping 한 번의 비용은 입력 토큰 × 캐시 요율로, 우리의 7K 토큰 프리픽스를 gpt-5.4-mini에서 쓰면 약 $0.0026입니다 —— 배치 작업이 처음 50번의 실제 호출에서 전체 prefill을 지불하게 두는 것보다 훨씬 저렴합니다.

8.3 콜드 스토리지 문서

산발적으로(하루 종일 시간당 1회) 조회되는 문서의 경우, 인메모리 캐시는 대부분의 시간 동안 콜드입니다. 이 글을 쓰는 시점에 게이트웨이는 호스팅형 명시 캐시 생성 엔드포인트를 노출하지 않습니다 —— 긴 TTL이 필요하면 deepseek-v4-flash(디스크 기반; 실제로 시간 단위 간격을 견딤)를 사용하거나, 게이트웨이 밖에서 Google 네이티브 cachedContent API를 직접 호출하세요.

10. 게이트웨이가 실제로 더해 주는 것

게이트웨이가 “여러분을 대신해 캐싱을 해준다”고 주장하는 것은 정직하지 않습니다. 캐싱은 모델 계층에서 일어나며, 게이트웨이는 거기 있는 것을 노출할 뿐입니다. 각 벤더의 네이티브 SDK를 직접 쓰는 것과 비교해 그것이 실제로 더해 주는 것은 세 가지입니다:

1. 하나의 base_url, 하나의 인증 헤더, 모든 모델. model 필드를 바꿔도 호출 형태는 변하지 않습니다. 같은 messages 배열, 같은 usage 필드 구조입니다. 다섯 프로바이더를 위해 다섯 개의 SDK를 들고 다닐 필요가 없습니다.
2. 호출당 usage.cost(USD). 게이트웨이는 현재 상류 요율로 달러 비용을 계산해 모든 응답에 포함합니다. 코드 안에 가격 매트릭스를 유지할 필요도, 벤더별 가격 변경 알림을 구독할 필요도 없습니다.
3. 통일된 cached_tokens 필드. Anthropic은 캐시 적중을 cache_read_input_tokens로, OpenAI는 prompt_tokens_details.cached_tokens로, DeepSeek은 prompt_cache_hit_tokens로 보고합니다. 게이트웨이는 이들을 OpenAI 형태로 정규화하므로, 여러분의 관측성 코드가 프로바이더별로 분기할 필요가 없습니다.

이것이 전체 어필입니다. 나머지 모든 것 —— 언제 캐싱할지, 프롬프트를 어떻게 구성할지, 어떤 모델을 고를지 —— 는 다음 글의 몫입니다.

다음: 4부 — 사용 사례별 최적 LLM 선택 방법: 채팅, API & AI 에이전트 —— 워크로드 유형을 최적 모델 + 캐싱 전략에 대응시키는 결정 매트릭스를 비용 계산과 함께.

FAQ

왜 OpenAI가 아닌 모델에도 OpenAI SDK를 쓰나요? 게이트웨이는 자신이 앞단에서 처리하는 모든 프로바이더에 대해 OpenAI의 와이어 포맷을 사용합니다. 공식 openai SDK는 타입이 지정된 응답, 자동 재시도, 스트리밍 헬퍼를 제공합니다 —— 다섯 개의 HTTP 클라이언트를 손으로 작성할 이유가 없습니다.

캐싱은 스트리밍 응답에서도 동작하나요? 동작합니다. 마지막 청크의 usage 객체가 캐시 적중 수를 보고합니다(stream_options={"include_usage": True}를 전달했을 때). 지연 이득은 스트리밍에서 가장 잘 드러납니다. 사용자가 보는 것은 TTFT이기 때문입니다.

내 워크로드에서 어느 프로바이더의 캐시 할인이 가장 깊나요? 2026-05 가격과 70%+ 적중률에서, §7 표에서 가장 저렴한 것은 gemini-2.5-flash와 deepseek-v4-flash입니다. TTFT에서는 gpt-5.4-mini가 이깁니다. Claude의 문서화된 90% 캐시 할인을 얻으려면 최대 4개의 cache_control 중단점을 표시하세요(§2 참고). 여러분 자신의 프롬프트로 같은 벤치마크를 실행하세요 —— 그것은 몇 주짜리 마이그레이션이 아니라 하루짜리 작업입니다.

cache_control 마커는 언제 필요한가요? Anthropic Claude를 호출할 때만 필요합니다 —— §2 참고. OpenAI/Gemini/DeepSeek/Qwen에서는 상류가 충분히 긴 프리픽스를 자동 캐싱하므로 마커가 필요 없습니다. 이 프로바이더들에 대해서는 해당 필드가 조용히 무시됩니다.

이 수치들은 얼마나 최신인가요? 2026-05-25에 공개 게이트웨이에서 실측했습니다. 단일 데이터 포인트로 다루세요 —— 가격과 지연은 릴리스 주기마다 변합니다.

Anthropic Claude는 어떤가요? Claude는 명시적 cache_control 마커를 통해 게이트웨이에서 지원됩니다 —— base_url="https://synthorai.io/"를 지정한 anthropic SDK를 사용하세요(SDK가 /v1/messages를 덧붙입니다). OpenAI 호환 /chat/completions 경로는 현재 마커를 전파하지 않습니다. 특히 Claude 캐싱에는 §2에 나온 Anthropic 네이티브 경로를 사용하세요.

출처 및 검증: 모든 수치는 openai SDK 2.38.0을 사용해 2026-05-25에 https://synthorai.io/v1을 상대로 실측했습니다. 벤더 가격 페이지: Anthropic Prompt Caching · OpenAI Prompt Caching · Google Gemini Context Caching · DeepSeek KV Cache Guide · Alibaba Bailian Context Cache.

← 블로그로 돌아가기