Python으로 구현하는 LLM 프롬프트 캐싱: 실행 가능한 코드 튜토리얼

TL;DR — OpenAI SDK 하나와 base_url 하나로 주요 LLM을 모두 호출할 수 있습니다. 이 글의 수치는 약 7,300 token 길이의 고정 system prompt를 사용해 2026-05-25에 실제 Synthorai 게이트웨이에서 측정했습니다. 여기서 게이트웨이가 제공하는 기능은 명확합니다. endpoint 하나, 인증 header 하나, 그리고 provider별 가격표를 직접 관리하지 않아도 되는 usage.cost 필드입니다. 캐싱의 기반이 되는 Transformer 연산은 1부: 캐싱 원리에서, provider별 설계 차이는 2부: Provider 비교에서 설명합니다.

시리즈: 5부 중 3부 · 이전 글: 1부 — 캐싱 원리 · 2부 — Provider 비교 및 평가 · 다음 글: 4부 — 사용 사례별 최적 LLM · 5부 — LangChain 연동

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 wire format을 사용합니다. SDK를 바꿀 필요 없이 model 필드만 변경하면 됩니다. 인증에는 Authorization: Bearer <key>를 사용합니다.

공개 게이트웨이에서 프롬프트 캐싱을 지원하는 model 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. 캐시를 활용하는 호출 방식(모든 Provider에서 동일)

별도로 활성화할 필요는 없습니다. upstream에서 프롬프트 캐싱을 지원하는 모델이라면 게이트웨이가 response metadata를 그대로 전달합니다. 결과는 다음 두 필드로 확인할 수 있습니다.

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는 upstream prefix cache에 적중한 input token 수입니다. usage.cost는 게이트웨이가 계산한 단일 호출의 USD 비용입니다. provider별 요금표를 로컬에서 관리할 필요가 없습니다.

아키텍처 특성상 모든 provider에 적용되는 규칙은 두 가지입니다.

1. 고정된 내용은 앞에, 바뀌는 내용은 뒤에 배치합니다. prefix는 token 0부터 비교하므로 시작 부분에서 단 1 byte만 달라져도 prefix 전체가 무효화됩니다.
2. 동적 데이터는 system prompt에 넣지 않습니다. 현재 timestamp, session ID, request UUID는 모두 캐시를 무효화합니다.

이하 내용은 같은 패턴을 provider별 예제로 보여줍니다.

2. Anthropic Claude — 명시적 cache_control Marker

Claude는 명시적 marker 방식입니다. Anthropic API는 자동으로 캐싱하지 않습니다. 캐시를 사용하려면 system 또는 messages 배열에 최대 4개의 cache_control breakpoint를 지정해야 합니다. 캐시 read 비용은 input 요금의 약 10%이고, 캐시 write 비용은 125%로 25%의 추가 비용이 붙습니다.

게이트웨이에서 cache_control을 가장 깔끔하게 사용하는 방법은 공식 anthropic SDK가 게이트웨이의 Anthropic native endpoint를 바라보도록 설정하는 것입니다. OpenAI 호환 /chat/completions 경로는 현재 cache_control marker를 전달하지 않으므로 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분 sliding TTL입니다. 적중할 때마다 만료 시간이 연장됩니다. 유휴 구간이 5분보다 긴 workload라면 같은 marker에 1시간 TTL을 지정합니다.

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

계층형 breakpoint. 최대 4개의 marker를 사용하면 “변하지 않는 내용” + “드물게 바뀌는 내용” + “task마다 바뀌는 내용”을 독립적으로 캐싱할 수 있습니다. prompt 구간마다 변경 주기가 다른 agent 및 RAG workload에 가장 적합한 방식입니다. 뒤쪽 계층(예: 검색된 문서)이 호출마다 바뀌더라도 앞쪽 계층은 계속 cache hit가 납니다.

모델 선택. 2026-05 기준 게이트웨이에서 사용할 수 있는 Claude ID는 claude-haiku-4-5, claude-sonnet-4-5 / 4-6, claude-opus-4-5 / 4-6 / 4-7입니다. 저렴한 chat에는 Haiku, 범용 workload와 강력한 agent 캐싱 패턴에는 Sonnet, 가장 어려운 reasoning task에는 Opus가 적합합니다.

Cache hit / write / 캐시 미사용 기준 측정값(2026-05-25, 약 7,976-token system prompt, max_tokens=64):

모든 모델에서 할인율이 비슷하게 유지됩니다. Write 비용은 캐시 미사용 대비 약 25% 높으며, 이는 Anthropic이 공개한 요금과 일치합니다. Cache hit가 한 번만 발생해도 손익분기점을 넘습니다.

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

OpenAI는 prefix가 충분히 긴 request를 자동으로 캐싱합니다. 코드를 변경하거나 marker를 추가할 필요가 없습니다.

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-token prompt를 두 번 호출했습니다. 두 번째 호출에서는 system prompt의 93%가 cache hit했고, 전체 latency는 3.6 s에서 1.2 s로 줄었습니다. 여기서는 첫 번째 호출의 completion이 더 길어 캐시 할인이 상쇄됐기 때문에 비용 차이가 거의 없습니다. provider 간 비교가 더 명확한 수치는 §7에서 확인할 수 있습니다.

gpt-5.4-nano에서는 할인 효과가 더 명확하게 나타났으며, cache hit 시 비용이 44% 감소했습니다. Chat UI에서 time-to-first-token만 중요하다면 streaming 수치를 봐야 합니다.

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-token system prompt로 gemini-2.5-flash를 측정한 결과, 7,140 token(97%)이 cache hit했고 비용은 $0.00198에서 $0.00024로 줄었습니다. 해당 호출 기준 88% 절감입니다.

알아둘 제약은 두 가지입니다.

• Gemini의 *-pro 변형은 reasoning model입니다. max_tokens가 작으면 숨겨진 thinking에 token budget이 소진되어 completion_tokens=0이 자주 발생합니다. 사용자에게 응답을 보여줘야 한다면 max_tokens를 256 이상으로 설정합니다.
• 암시적 cache TTL은 짧고 공식 수치가 공개되어 있지 않습니다. 테스트에서는 두 호출 간격이 5 s일 때는 적중했지만, 약 10 s 뒤의 세 번째 호출은 간헐적으로 실패했습니다. Cache hit를 전제로 로직을 설계하지 말고 cached_tokens를 확인한 뒤 적중하지 않아도 정상 처리되도록 구현해야 합니다.

5. DeepSeek-v4-flash — Disk 기반 자동 캐시

DeepSeek의 자동 캐시는 다른 vendor의 GPU memory 기반 캐시보다 오래 유지됩니다. 호출 형식은 동일합니다.

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

캐시된 호출의 streaming TTFT는 2.93 s였습니다. 이 비교군에서 DeepSeek는 latency가 가장 낮은 선택지는 아닙니다. 장점은 비용과 몇 시간의 호출 간격에도 캐시가 유지된다는 점입니다.

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

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에는 cache hit가 보고됐지만(7,234개 중 7,040개 = 97%), 캐시된 호출에서도 usage.cost는 줄지 않고 여전히 약 $0.0055였습니다. Upstream cache hit 자체는 발생했고 TTFT도 cold 상태의 3.03 s에서 1.53 s로 단축됐습니다. 다만 이 측정일에는 게이트웨이의 해당 provider 비용 필드에 캐시 요금 할인이 반영되지 않았습니다. Qwen 비용이 중요하다면 이 문제가 정상화될 때까지 cached_tokens를 모니터링하고 upstream 가격 페이지를 기준으로 판단해야 합니다.

7. Provider 간 Benchmark(2026-05-25 측정)

한 번의 순차 실행으로 측정했습니다. 고정된 system prompt는 7,284자이며 tokenizer에 따라 약 6,900~7,300 token입니다. max_tokens=64로 설정하고 miss 호출 직후 hit 호출을 한 번씩 실행했습니다.

자동 캐싱 provider(marker 불필요):

* gpt-5.4-mini의 miss 호출은 completion이 44 token이었고 hit 호출은 19 token이었습니다. 따라서 비용 차이에는 캐시 할인과 completion 길이 차이가 함께 반영되어 있습니다. 여기서는 latency 감소(3.63 → 1.23 s)가 더 명확한 지표입니다. † cached_tokens가 보고된 streaming 호출의 비용입니다. Gemini의 non-stream 호출에서는 간헐적으로 cached_tokens=null이 반환됐고 비용도 줄지 않았습니다. 현재 Gemini의 게이트웨이 metadata는 일관되지 않습니다. cached_tokens가 있으면 해당 값을 기준으로 판단해야 합니다. ‡ Gemini *-pro / *-flash reasoning model은 max_tokens가 작을 때 content token을 전혀 출력하지 않는 경우가 많아 이 budget에서는 TTFT가 의미 없습니다. Production에서 측정하려면 max_tokens를 늘려야 합니다. § §6을 참고하세요. Upstream cache hit가 발생해 latency는 줄었지만, 이 측정일에는 게이트웨이의 qwen3-max usage.cost 필드에 할인이 반영되지 않았습니다.

Anthropic Claude는 명시적 marker 방식입니다. 할인 적용에 cache_control을 직접 지정해야 하므로 별도 표로 정리했습니다. 패턴은 §2를 참고하세요. 동일한 prompt를 사용해 cache write와 cache read 비용을 측정했습니다.

지역, 시간대, 다른 tenant의 prefix가 캐시에 남아 있는 정도에 따라 결과는 달라집니다. 특정 날짜에 한 번 실행한 결과이므로 절대적인 benchmark로 인용하면 안 됩니다.

8. 출시 전 Checklist

캐시를 활용하는 prompt를 배포하기 전에 다음을 확인합니다.

1. 고정된 내용은 앞에 둡니다. System prompt, knowledge base, tool schema를 messages 상단에 배치합니다.
2. 바뀌는 내용은 뒤에 둡니다. User input, 검색된 문서, timestamp는 하단에 배치합니다.
3. system에 동적 변수를 넣지 않습니다. 현재 시간, user ID, random seed가 들어가면 prefix 전체가 무효화됩니다.
4. 모든 호출에서 cached_tokens를 기록합니다. Production hit rate가 50% 미만이라면 prefix가 실제로 고정되어 있지 않은 것입니다. Miss가 발생한 prompt를 조사해야 합니다.
5. 한 번의 hit 결과를 그대로 믿지 않습니다. TTL은 짧습니다. “항상 hit”를 전제로 하지 말고 hit_rate ∈ [0, 1) 범위에서 동작하도록 설계합니다.

9. TTL을 고려한 패턴

Production에서 가장 흔한 실패 원인은 “캐싱을 활성화하지 않았다”가 아닙니다. “실제 request가 TTL 안에 도착하지 않아 hit rate가 12%밖에 나오지 않는다”는 문제입니다.

8.1 Session 기반 Workload(chat, IDE assistant)

일반적인 호출 간격은 TTL보다 훨씬 짧습니다. Prompt 구조만 올바르게 잡으면 별도 처리 없이 캐시가 계속 warm 상태로 유지됩니다.

8.2 Batch / Cron용 Heartbeat

매일 09:00에 3분 동안 모델을 50번 호출해 report를 생성한다고 가정합니다. 밤사이 캐시가 cold 상태가 되므로 09:00의 첫 cache write는 낭비됩니다. 08:55부터 TTL/2 간격으로 캐시할 prefix와 함께 1-token “ping”을 보내 캐시를 warm 상태로 유지합니다.

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당 비용은 input token 수 × 캐시 요금입니다. gpt-5.4-mini에서 7K-token prefix를 사용한 이 예제는 약 $0.0026입니다. 실제 호출 50건의 첫 prefill에 전체 비용을 지불하는 것보다 훨씬 저렴합니다.

8.3 Cold Storage 문서

하루 동안 한 시간에 한 번 정도 간헐적으로 조회되는 문서는 대부분 in-memory cache가 cold 상태입니다. 현재 게이트웨이는 hosted explicit-cache 생성 endpoint를 제공하지 않습니다. 긴 TTL이 필요하면 실제로 몇 시간의 호출 간격에도 캐시가 유지되는 disk 기반 deepseek-v4-flash를 사용하거나, 게이트웨이를 거치지 않고 Google의 native cachedContent API를 직접 호출해야 합니다.

10. 게이트웨이가 실제로 제공하는 기능

게이트웨이가 “캐싱을 대신 해준다”고 주장하는 것은 정확하지 않습니다. 캐싱은 모델 계층에서 이루어지고, 게이트웨이는 해당 기능을 노출할 뿐입니다. 각 vendor의 native SDK를 직접 사용하는 방식과 비교했을 때 게이트웨이가 추가하는 기능은 세 가지입니다.

1. 하나의 base_url, 하나의 인증 header, 모든 모델. model 필드만 바꾸면 호출 형식은 그대로입니다. 같은 messages 배열과 같은 usage 필드 구조를 사용하므로 provider 5곳을 위해 SDK 5개를 관리할 필요가 없습니다.
2. 호출별 USD 단위 usage.cost. 게이트웨이가 최신 upstream 요금으로 비용을 계산해 모든 response에 포함합니다. 코드에서 가격표를 관리하거나 vendor별 가격 변경 알림을 구독할 필요가 없습니다.
3. 통일된 cached_tokens 필드. Anthropic은 cache hit를 cache_read_input_tokens로, OpenAI는 prompt_tokens_details.cached_tokens로, DeepSeek는 prompt_cache_hit_tokens로 보고합니다. 게이트웨이는 이를 OpenAI 형식으로 통일하므로 observability 코드에서 provider별 분기 처리를 하지 않아도 됩니다.

핵심은 여기까지입니다. 언제 캐싱할지, prompt를 어떻게 구성할지, 어떤 모델을 선택할지는 다음 글에서 다룹니다.

다음 글: 4부 — 사용 사례별 최적 LLM 선택법: Chat, API, AI Agent — workload 유형에 맞는 최적의 모델과 캐싱 전략을 비용 계산과 함께 정리한 의사결정 matrix입니다.

FAQ

OpenAI가 아닌 모델에 OpenAI SDK를 사용하는 이유는 무엇인가요? 게이트웨이는 연동된 모든 provider에 OpenAI wire format을 사용합니다. 공식 openai SDK는 typed response, 자동 retry, streaming helper를 제공합니다. HTTP client를 5개나 직접 구현할 이유가 없습니다.

Streaming response에서도 캐싱이 동작하나요? 네. stream_options={"include_usage": True}를 전달하면 마지막 chunk의 usage object에 cache hit 수가 포함됩니다. 사용자가 체감하는 지표는 TTFT이므로 latency 개선은 streaming에서 가장 분명하게 나타납니다.

내 workload에서 캐시 할인 폭이 가장 큰 provider는 어디인가요? 2026-05 요금과 70% 이상의 hit rate를 기준으로 하면 §7 표에서는 gemini-2.5-flash와 deepseek-v4-flash가 가장 저렴합니다. TTFT는 gpt-5.4-mini가 가장 낮습니다. Claude에서 공식적으로 제공하는 90% 캐시 할인을 받으려면 최대 4개의 cache_control breakpoint를 지정합니다(§2 참고). 직접 사용하는 prompt로 같은 benchmark를 실행하세요. 여러 주가 걸리는 migration이 아니라 하루면 끝나는 작업입니다.

cache_control marker는 언제 필요한가요? Anthropic Claude를 호출할 때만 필요합니다. 자세한 내용은 §2를 참고하세요. OpenAI/Gemini/DeepSeek/Qwen은 충분히 긴 prefix를 upstream에서 자동으로 캐싱하므로 marker가 필요하지 않습니다. 이들 provider에 해당 필드를 전달하면 아무 동작 없이 무시됩니다.

이 수치는 얼마나 최근에 측정됐나요? 2026-05-25에 공개 게이트웨이에서 측정했습니다. 하나의 측정값으로만 봐야 합니다. 가격과 latency는 release 주기마다 달라집니다.

Anthropic Claude도 지원하나요? Claude는 게이트웨이에서 명시적 cache_control marker 방식으로 지원합니다. anthropic SDK에 base_url="https://synthorai.io/"를 설정하면 SDK가 /v1/messages를 덧붙입니다. 현재 OpenAI 호환 /chat/completions 경로는 marker를 전달하지 않습니다. Claude 캐싱에는 §2의 Anthropic native 경로를 사용하세요.

출처 및 검증: 모든 수치는 openai SDK 2.38.0을 사용해 2026-05-25에 https://synthorai.io/v1에서 측정했습니다. Vendor 가격 페이지: Anthropic 프롬프트 캐싱 · OpenAI 프롬프트 캐싱 · Google Gemini 컨텍스트 캐싱 · DeepSeek KV Cache 가이드 · Alibaba Bailian 컨텍스트 캐시.

← 블로그로 돌아가기