GPT 프롬프트 캐싱

​

빠른 시작

curl https://aihubmix.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -d '{
    "model": "gpt-5.6-sol",
    "prompt_cache_key": "my-app-report-assistant-v1",
    "messages": [
      {
        "role": "system",
        "content": "You are a meticulous assistant for analyzing quarterly financial reports... [변하지 않는 긴 지침 또는 참고 자료를 여기에 배치, ≥1024 토큰]"
      },
      {
        "role": "user",
        "content": "Summarize the key figures in one sentence."
      }
    ]
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AIHUBMIX_API_KEY"],  # 키는 환경 변수에서 읽습니다
    base_url="https://aihubmix.com/v1",
)

long_context = "You are a meticulous assistant for analyzing quarterly financial reports... [변하지 않는 긴 지침 또는 참고 자료, ≥1024 토큰]"

# 동일한 접두사로 두 번 연속 요청하면 두 번째에 캐시에 히트합니다
for i in range(2):
    completion = client.chat.completions.create(
        model="gpt-5.6-sol",
        prompt_cache_key="my-app-report-assistant-v1",
        messages=[
            {"role": "system", "content": long_context},
            {"role": "user", "content": "Summarize the key figures in one sentence."},
        ],
    )
    print(completion.usage.prompt_tokens_details)

// 1번째 호출: 미히트
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 0}

// 2번째 호출: 접두사가 캐시에 히트
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 2816}

​

캐시 요금

​

캐시가 자동으로 적용되는 방식

1. 접두사가 1,024 토큰에 도달하고 일치하는 캐시 접두사가 있으면, 히트한 부분은 캐시 읽기 가격으로 과금되고 첫 토큰 지연이 줄어듭니다.
2. 없으면 일반 입력으로 처리하고 접두사를 캐시에 기록합니다(GPT-5.6 및 이후는 1.25배 쓰기 비용 과금).
3. 히트하려면 접두사가 바이트 단위로 일치해야 하며, 접두사 중 한 곳이라도 바뀌면 그 위치 이후의 캐시가 모두 무효화됩니다.

• 고정된 긴 시스템 지침 또는 대량의 few-shot 예시
• 긴 참고 자료를 반복 인용하는 RAG 시나리오
• 대량의 도구 정의(tools)를 포함하는 Agent 워크플로
• 메시지를 뒤로만 추가하는 긴 다중 턴 대화

​

GPT-5.6 캐시 파라미터

1. 기본(implicit 모드): 캐시 파라미터를 전혀 전달하지 않아도 자동으로 캐시에 기록됩니다. 시스템이 최신 메시지 위치에 자동으로 중단점을 설정합니다. GPT-5.6 및 이후에서는 자동으로 발생한 캐시 쓰기도 1.25배로 과금됩니다.
2. implicit 모드 + 명시적 중단점: 자동 중단점 외에 콘텐츠 블록에 prompt_cache_breakpoint를 설정하여 캐시 경계를 고정 콘텐츠의 끝에 고정할 수 있습니다. 중단점 이후의 콘텐츠 변경은 중단점 이전의 접두사 캐시를 깨뜨리지 않습니다.
3. explicit 모드: prompt_cache_options.mode를 "explicit"으로 설정하면 수동 중단점만 사용합니다. 중단점을 전혀 설정하지 않으면 해당 요청은 캐시를 사용하지 않고 캐시 쓰기 비용도 발생하지 않습니다. 공식 원문: “If the conversation contains no explicit breakpoints, the request does not use prompt caching or incur cache-write charges.”

{
  "model": "gpt-5.6-sol",
  "prompt_cache_options": {"mode": "explicit"},
  "messages": [
    {"role": "user", "content": "[재사용되지 않는 일회성 긴 콘텐츠]"}
  ]
}

{
  "model": "gpt-5.6-sol",
  "prompt_cache_key": "my-app-report-assistant-v1",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "[변하지 않는 긴 지침 또는 참고 자료, ≥1024 토큰]",
          "prompt_cache_breakpoint": {"mode": "explicit"}
        }
      ]
    },
    {"role": "user", "content": "Summarize the key figures in one sentence."}
  ]
}

• 요청당 최대 4개의 새 캐시 쓰기를 생성할 수 있으며, implicit 모드의 자동 중단점이 그중 1개를 차지합니다.
• 중단점 이전의 접두사가 1,024 토큰에 도달해야 캐시에 기록됩니다.
• 읽기 시 최근 50개 중단점 중 가장 긴 일치 접두사를 사용합니다.
• 지원되지 않는 콘텐츠 블록에 중단점을 설정하면 400 invalid_request_error가 반환됩니다. Chat Completions는 text / image_url / input_audio / file / refusal 블록을, Responses API는 input_text / input_image / input_file 블록을 지원합니다.

​

캐시가 히트하지 않는 이유

• 접두사가 1,024 토큰 미만: 최소 캐시 길이 미만의 요청은 일반 입력으로 처리됩니다.
• 접두사에 변하는 콘텐츠가 섞임: 타임스탬프, 세션 ID, 사용자 변수 등은 고정 콘텐츠 뒤에 배치해야 합니다. 접두사 중 한 곳이라도 바뀌면 그 이후의 캐시가 무효화됩니다.
• tools 정의 또는 순서 변경: 도구 목록은 접두사 계산에 포함되며, 정의와 배열 순서가 완전히 일치해야 합니다.
• 이미지 detail 파라미터 불일치: detail은 이미지 토큰화 결과에 영향을 주므로 동일하게 유지해야 합니다.
• 구조화된 출력 schema 변경: response_format의 JSON Schema는 시스템 메시지 접두사로 캐시에 포함되며, schema가 바뀌면 접두사도 바뀝니다.
• reasoning_effort 변경: 공식 문서에서 캐시 적중률 저하의 일반적인 원인으로 명시되어 있습니다(“Changes to reasoning effort”).
• 캐시 유지 기간 초과: GPT-5.6 이전은 비활성 5–10분 후 삭제되고, GPT-5.6 및 이후는 최소 30분 유지됩니다.
• prompt_cache_key 미설정(GPT-5.6): 설정하지 않아도 자동으로 히트할 수 있으나, 더 신뢰할 수 있는 매칭 메커니즘을 사용하지 않게 됩니다.

​

모범 사례

• 고정 콘텐츠(시스템 지침, 예시, 참고 자료, 도구 정의)는 요청의 맨 앞에, 매 턴 바뀌는 콘텐츠는 맨 뒤에 배치하세요.
• 동일한 접두사를 공유하는 트래픽에는 동일한 고정 prompt_cache_key를 설정하고, key 하나당 총 트래픽은 약 15회/분 이내로 유지하세요. 초과 시 비즈니스 단위로 key를 더 분할하세요.
• 다중 턴 대화는 메시지를 뒤로만 추가하고, 과거 메시지를 수정하지 마세요.
• 동일 접두사 요청에 지속적인 트래픽을 유지하여 캐시 삭제를 줄이세요.
• 접두사가 재사용되지 않는 일회성 긴 요청은 explicit 모드로 캐시 쓰기 비용을 피하세요(GPT-5.6 및 이후).
• usage.prompt_tokens_details.cached_tokens로 히트 상황을 지속적으로 모니터링하세요.

​

자주 묻는 질문(FAQ)

​

GPT 프롬프트 캐싱은 수동으로 켜야 하나요?

​

GPT-5.6의 캐시 쓰기 비용은 어떻게 계산되나요? 불필요한 쓰기 비용은 어떻게 피하나요?

​

캐시는 얼마나 유지되나요?

​

GPT-5.6의 명시적 중단점과 Claude의 cache_control은 무엇이 다른가요?

​

캐시가 출력 내용에 영향을 주나요?

​

공식 참고 자료

• GPT-5.6 발표 공지: 캐시 쓰기 1.25배 / 읽기 90% 할인 과금 규칙
• 프롬프트 캐싱 가이드: 메커니즘, 파라미터, usage 필드와 제한
• OpenAI Pricing: 각 모델 공식 가격
• GPT-5.6 모델 문서: 컨텍스트 윈도우, 롱 컨텍스트 과금 임계값