프롬프트 캐싱

프롬프트 캐싱

출처: 문서

본문

프롬프트 캐싱이 중요한 이유

프롬프트 캐싱(Prompt caching)은 요청이 같은 프롬프트 접두어(prefix)를 공유할 때 이전 작업을 재사용합니다. 이는 세 가지 주요 이점을 제공합니다:

  • 계산 효율: 모델이 이미 처리한 프롬프트 접두어를 다시 계산하지 않습니다.
  • 더 저렴한 입력 토큰: 재사용된 토큰에 대해 모델의 할인된 캐시 입력 요율을 지불하며, 최대 90% 할인됩니다.
  • 더 빠름: 응답이 시작되기 전에 입력 처리에 소요되는 시간을 줄입니다.

프롬프트 캐싱은 지원되는 OpenAI 모델에서 기본적으로 활성화됩니다. Prompt Caching Dashboard를 사용해 캐시 읽기 적중률을 모니터링하고, Prompt Cache Diagnostics 도구를 사용해 캐시 누락을 진단하고 캐시 재사용을 개선하세요.

Agents API 모델 호출은 Responses API와 동일한 프롬프트 캐싱 동작을 사용합니다. 세션 내에서 컨텍스트를 재사용하면 공유 프롬프트 접두어를 보존할 수 있지만, 세션을 유지한다고 캐시 적중이 보장되지는 않습니다. 세션 사용량 필드와 subagent 회계는 관측성 및 사용량을 참고하세요.

프롬프트 캐싱 가격은 모델에 따라 다릅니다. 현재 캐시 입력 및 캐시 쓰기 요율은 API 가격을 참고하세요. 캐시 쓰기 가격은 추가 요금이 아닙니다: 입력 토큰은 비캐시 입력, 캐시 입력, 또는 캐시 쓰기 요율 중 하나를 사용합니다.

프롬프트 캐시란 무엇인가요

모델이 입력 토큰을 처리할 때, key-value(KV) 상태로 알려진 중간 상태를 계산해야 합니다. 이 상태를 통해 모델은 새 입력을 처리하고 출력 토큰을 생성하는 동안 이전 토큰을 다시 참조할 수 있습니다.

프롬프트 캐싱은 재사용 가능한 접두어(프롬프트 시작 부분의 변경되지 않은 토큰)에 대해 그 상태를 보존합니다. 이후 요청이 같은 접두어를 갖고 일치하는 캐시 항목을 찾으면 모델은 그 토큰을 다시 처리하는 대신 저장된 상태를 재사용할 수 있습니다. 새 응답을 생성하려면 여전히 새 입력을 처리해야 합니다.

프롬프트 캐시에는 토큰 자체가 아니라 key-value(KV) 텐서가 저장됩니다.

OpenAI는 OpenAI 제공 지침, 개발자 메시지, 도구 정의, 그리고 텍스트, 이미지, 문서, 지원되는 오디오를 포함하는 대화 기록을 포함한 모델의 전체 렌더링된 컨텍스트를 캐시합니다.

캐시 재사용은 전체 렌더링된 접두어가 일치해야 합니다. 브레이크포인트 이전에 콘텐츠나 관련 설정이 변경되면, 그 변경 이후의 접두어는 기존 캐시 항목과 일치할 수 없습니다.

어떤 설정이 캐시된 접두어에 영향을 미치나요

요청을 변경한다고 해서 기존 캐시 항목이 반드시 버려지는 것은 아닙니다. 중요한 것은 후속 요청에 같은 접두어가 있고 자격이 되는 일치 브레이크포인트를 찾을 수 있는지 여부입니다. 확인할 주요 설정은:

Setting 영향
model 다른 모델은 다른 가중치와 캐싱 동작을 사용할 수 있습니다.
tools 도구 이름, 설명, 스키마, 순서 또는 도구별 지침을 변경합니다.
parallel_tool_calls 한 턴에서 여러 도구를 호출하는 것에 대한 지침을 변경할 수 있습니다.
text.format (Structured Outputs) 출력 형식 지침과 요청된 스키마를 추가합니다.
reasoning.effort 모델 측 추론 지침을 변경할 수 있습니다. 지원되는 모델에서 이전 접두어를 보존하면서 effort를 변경하려면 구성 업데이트를 사용하세요.
text.verbosity 응답 상세 수준에 대한 지침을 변경할 수 있습니다.
context_management (Compaction) 이전 대화 내용을 압축된 컨텍스트로 대체하며, 첫 번째 변경 토큰부터 재사용을 막을 수 있습니다.

캐싱 작동 방식

캐시 브레이크포인트(cache breakpoint)는 OpenAI가 캐시에 저장하고 이후 요청에서 재사용할 수 있는 프롬프트 접두어의 끝을 표시합니다. 첫 번째 요청이 자격이 되는 접두어를 캐시에 쓰고, 이후 요청은 자격이 되는 브레이크포인트를 거꾸로 탐색해 사용 가능한 가장 긴 일치 캐시 접두어를 찾습니다.

프롬프트 접두어는 캐시되려면 모델의 최소 캐시 가능 토큰 길이를 충족해야 합니다. OpenAI가 제공하는 숨겨진 시스템 콘텐츠의 토큰은 이 최소 길이에 포함되지 않습니다. 최소 캐시 가능 프롬프트 길이는 GPT-5.6 이상에서 1,024 토큰이며, 이전 모델에서는 요청 설정에 따라 달라집니다. 자세한 내용은 모델 비교를 참고하세요.

최소 캐시 가능 토큰 길이 이후에는 캐시 브레이크포인트 위치를 명시적으로 선택하거나 OpenAI가 암시적으로 위치를 선택하게 할 수 있습니다. 사용 가능한 옵션은 모델에 따라 다릅니다.

GPT-5.6 이상

GPT-5.6 이상의 경우 캐시 쓰기는 표준 비캐시 입력 토큰 요율의 1.25배입니다. 접두어가 재사용될 것임을 알 때 이 비용을 부담할 가치가 있습니다. 이후 읽기는 그 요율의 0.1배이기 때문입니다. 접두어를 한 번 쓰고 한 번 완전히 재사용하면 일반 입력 비용의 1.35배이며, 캐싱 없이 두 번 처리하는 2배와 비교됩니다. 캐시 읽기가 추가될 때마다 절약이 커집니다: 10개 요청에 걸쳐 한 번의 쓰기와 9번의 전체 읽기는 2.15배이며, 캐싱 없이는 10배입니다.

암시적 및 명시적 캐싱이 모두 지원되며, 명시적 캐싱은 어떤 컨텍스트를 캐시에 쓸지 더 많이 제어할 수 있습니다.

명시적 모드: 컨텍스트 관리에 따라 캐시 브레이크포인트 위치를 직접 선택합니다.

  • prompt_cache_options.mode를 explicit로 설정해 개발자가 선택한 브레이크포인트만 사용하고, 입력 메시지 안의 지원되는 콘텐츠 블록에 prompt_cache_breakpoint: { "mode": "explicit" }을 추가해 원하는 각 브레이크포인트를 표시하세요.
  • 명시적 브레이크포인트가 없으면 요청은 프롬프트 캐싱을 사용하지 않거나 캐시 쓰기를 만들지 않습니다.
  • 명시적 전용 모드를 사용하면 캐시 쓰기가 끝나는 위치를 선택할 수 있습니다. 마지막 선택 브레이크포인트 이후의 콘텐츠는 캐시 쓰기 요금 없이 비캐시 입력 토큰 요율로 처리되므로, 재사용될 가능성이 없는 변경 콘텐츠를 쓰지 않을 수 있습니다.
  • 여러 명시적 브레이크포인트는 서로 다른 속도로 변경되는 접두어를 보존할 수 있습니다. 각 요청은 최대 4개의 캐시 쓰기를 만들 수 있습니다.
  • additional_tools 입력 항목은 현재 prompt_cache_breakpoint를 허용하지 않습니다.

최상위 instructions에는 명시적 브레이크포인트를 포함할 수 없습니다. 재사용 가능한 개발자 지침을 표시하려면 개발자 메시지 안의 input_text 블록에 배치하세요.

암시적 모드: OpenAI가 대부분의 사용 사례에 잘 맞는 브레이크포인트 위치를 기본적으로 선택합니다.

  • prompt_cache_options.mode가 implicit이면 OpenAI는 가장 최근의 자격이 되는 메시지 끝에 브레이크포인트를 배치합니다. 자격이 되는 메시지는 다음과 같습니다:
    • user 메시지
    • 연속된 tool response 그룹의 마지막 tool response
    • 초기 연속 developer 메시지 그룹의 마지막 developer 메시지
  • 암시적 브레이크포인트를 끄지 않고 명시적 브레이크포인트를 추가할 수 있습니다. 암시적 브레이크포인트는 네 개의 캐시 쓰기 슬롯 중 하나를 사용해 사용 가능한 명시적 캐시 쓰기 슬롯을 세 개 남깁니다.

이전 모델

암시적 캐싱만 지원됩니다. OpenAI는 숨겨진 OpenAI 시스템 메시지 시작부터 세어 모델별 간격으로 암시적 브레이크포인트를 배치합니다. 최소 캐시 가능 길이(숨겨진 컨텍스트 끝부터 계산)에 있거나 그 너머의 브레이크포인트만 자격이 됩니다.

보고된 cached_tokens는 마지막 일치 브레이크포인트에서 숨겨진 시스템 토큰을 빼고, 가장 가까운 128의 배수로 내림해 계산됩니다.

접두어 일치 작동 방식

OpenAI는 들어오는 요청에서 캐시 조회 경계(아래 설명)만 가장 긴 접두어부터 가장 짧은 접두어까지 탐색하며, 해당 머신에 이미 캐시된 사용 가능한 일치 접두어를 찾습니다.

GPT-5.6 이상의 경우 들어오는 요청의 캐시 조회 경계는 다음과 같습니다:

  • 명시적 전용 모드: 처음 2개와 최근 50개의 명시적 브레이크포인트.
  • 암시적 모드: 처음 2개와 최근 50개의 명시적 브레이크포인트, 암시적 브레이크포인트, 최대 20개의 이전 자격이 되는 메시지 끝, 그리고 초기 연속 developer 메시지 블록의 끝점. 이를 통해 암시적 모드는 명시적 브레이크포인트 없이도 더 이른 메시지에서 끝나는 접두어를 재사용할 수 있습니다.

캐시 수명

캐시 항목은 무기한 저장되지 않습니다. 이후 요청은 해당 항목이 사용 가능한 동안에만 캐시된 접두어를 재사용할 수 있으며, 접두어를 재사용하면 별도의 캐시 쓰기 요금 없이 수명이 갱신됩니다. 수명과 보존 설정은 모델에 따라 다릅니다.

GPT-5.6 이상

prompt_cache_options.ttl을 사용해 최소 캐시 수명을 제어하세요. 지원되는 유일한 값인 30m이 기본값이기도 합니다. 캐시된 접두어는 가장 최근의 쓰기 또는 재사용 후 30분 동안 재사용 자격을 유지하지만, OpenAI가 더 오래 보존할 수도 있습니다.

이전 모델

prompt_cache_retention을 사용하며, 지원되는 값은 모델에 따라 다릅니다:

  • in_memory: 항목은 일반적으로 비활성 상태로 약 5~10분 동안 활성 상태를 유지하며, 최대 1시간까지 가능합니다.
  • 24h: 확장 보존은 일반적으로 항목을 약 30분간 유지하며 최대 24시간까지 보존할 수 있습니다.

보존 기본값과 Zero Data Retention

프롬프트 캐싱은 애플리케이션 상태로 GPU 로컬 저장소에 암호화된 key/value 텐서를 저장할 수 있습니다. in_memory와 24h를 모두 지원하는 모델의 경우 기본값은 조직의 데이터 보존 정책에 따라 달라집니다:

  • Zero Data Retention이 활성화되지 않은 조직은 기본적으로 24h를 사용합니다.
  • Zero Data Retention이 활성화된 조직은 기본적으로 in_memory를 사용합니다.

값을 선택하기 전에 모델과 조직에서 사용 가능한 보존 정책을 확인하세요.

캐시 위치

캐시된 상태는 개별 머신에 있으며, 분당 15개 요청 이상의 트래픽은 오버플로 라우팅으로 이어질 수 있습니다. 요청은 일치하는 항목을 보유하고 아직 만료되지 않은 머신에 도달해야만 캐시된 접두어를 재사용할 수 있습니다. 따라서 요청을 올바른 머신으로 라우팅하는 것이 캐시 재사용에 중요합니다.

캐시는 조직 간에 공유되지 않으며 지역 처리 경계를 넘어 재사용할 수 없습니다.

OpenAI가 라우팅을 자동으로 처리합니다. 조직과 처리 지역 내에서 특정 모델의 라우팅은 다음에 따라 달라집니다:

  • 현재 머신 부하와 사용 가능한 용량.
  • 숨겨진 OpenAI 콘텐츠 이후 초기 토큰의 해시(도구 정의가 있으면 포함). 해시되는 토큰 수는 모델에 따라 다릅니다.
  • 제공된 prompt_cache_key. 이는 요청 그룹 간 캐시 재사용을 분리하고 GPT-5.6 이전 모델에서 캐시 라우팅을 최적화하는 데 도움이 됩니다.

프롬프트 캐시 키

GPT-5.6 이전 모델에서는 재사용 가능한 접두어를 공유하는 요청에 안정적인 prompt_cache_key를 사용해 관련 요청을 같은 캐시로 라우팅하세요. 바쁜 그룹의 경우 각 키를 사용하는 모든 접두어에 걸쳐 총 분당 약 15개 요청을 목표로 하세요. 더 높은 볼륨 트래픽은 안정적이고 결정적인 매핑으로 여러 키에 분산하세요. 관련 요청을 같은 prompt_cache_key에 유지해 그 캐시를 재사용하게 하세요. 키는 라우팅에 영향을 주며, 요청을 특정 머신에 고정하거나 캐시 적중을 보장하지는 않습니다.

GPT-5.6 이상에서는 OpenAI가 캐시 라우팅을 자동으로 처리하므로 캐싱을 최적화하는 데 키가 필요하지 않습니다. 애플리케이션 내 고객이나 사용자에 대해 별도의 캐시 회계를 유지하려면 별도의 키를 사용할 수 있습니다.

별도의 키를 사용하면 각 고객이나 사용자에 대한 캐시된 토큰 사용량과 청구를 설명하기 쉬워집니다. 예를 들어 별도 키는 사용자 간 캐시 적중 탐색(cache-hit probing)을 방지하는 데 도움이 됩니다: 후보 프롬프트를 제출하고 캐시 적중을 관찰해 일치하는 콘텐츠가 이전에 캐시되었는지 알아내는 것입니다. 키로 캐시 회계 분리를 참고하세요.

모델 차이 요약

동작 GPT-5.6 이상 GPT-5.5 및 GPT-5.5 Pro 기타 이전 모델
암시적 브레이크포인트 가장 최근의 자격이 되는 메시지의 끝. 정기적인 2,048토큰 간격. 정기적인 모델별 간격.
명시적 브레이크포인트 지원됨 지원 안 됨 지원 안 됨
prompt_cache_key 별도 캐시 회계용으로 선택적 캐시 라우팅 최적화에 안정적 키 사용 캐시 라우팅 최적화에 안정적 키 사용
최소 캐시 가능 접두어 1,024개의 보이는 입력 토큰 요청 설정에 따라 다름 요청 설정에 따라 다름
캐시된 토큰 보고 숨겨진 토큰을 제외한 정확한 자격 경계 숨겨진 토큰을 제외하고 128의 배수로 내림 숨겨진 토큰을 제외하고 128의 배수로 내림
캐시 읽기 요금 비캐시 입력 토큰 요율의 0.1배 모델별 캐시 입력 요율 모델별 캐시 입력 요율
캐시 쓰기 요금 비캐시 입력 토큰 요율의 1.25배 추가 캐시 쓰기 요금 없음 추가 캐시 쓰기 요금 없음
캐시 수명 제어 prompt_cache_options.ttl prompt_cache_retention prompt_cache_retention
지원되는 보존 값 "30m" "24h"만 "in_memory" 또는 "24h"*
캐시 수명 최신 쓰기 또는 재사용 후 최소 30분 일반적으로 약 30분, 최대 24시간 in_memory는 일반적으로 5~10분 비활성, 24h는 최대 24시간

* 확장 보존은 gpt-5.5, gpt-5.5-pro, gpt-5.4, gpt-5.2, gpt-5.1-codex-max, gpt-5.1, gpt-5.1-codex, gpt-5.1-codex-mini, gpt-5.1-chat-latest, gpt-5, gpt-5-codex, gpt-4.1이 지원합니다.

GPT-5.6 이전 모델의 경우 최소 캐시 가능 입력 길이는 도구, 이미지, 출력 스키마, 추론 effort, 장황함(verbosity)을 포함한 요청 설정에 따라 달라집니다.

프롬프트 캐싱 최적화 방법

대화 기록 보존, 도구 정의를 안정적으로 유지, 캐싱이 발생하는 위치 선택에 집중하세요. GPT-5.6 이상에서는 prompt_cache_options.mode와 prompt_cache_breakpoint를 사용해 캐시 브레이크포인트를 제어하세요. 애플리케이션에 고객별 별도 캐시 회계가 필요하면 선택적 prompt_cache_key를 사용할 수도 있습니다. GPT-5.6 이전 모델에서는 재사용 가능한 접두어를 공유하는 요청에 안정적인 prompt_cache_key를 사용해 캐시 라우팅을 최적화하세요.

대화 기록 보존

다중 턴 애플리케이션에서 커지는 대화 기록을 재사용하면 초기 지침만 캐시하는 것보다 더 많은 입력 토큰을 절약할 수 있습니다. 이전 메시지와 도구 결과를 보존해 이후 턴이 전체 공유 접두어를 재사용할 수 있게 하세요.

  • 접두어를 안정적으로 유지하세요. 안정적인 개발자 지침과 공유 참조 자료를 먼저 배치하세요. 개발자 지침이나 공유 자료에 타임스탬프, 사용자별 콘텐츠 또는 기타 동적 콘텐츠가 포함되어 있으면 시작 부분이 아니라 끝에 배치하거나 나중 대화 메시지로 옮기세요.
  • 대화 기록을 보존하세요. 이전 턴을 다시 쓰는 대신 새 메시지를 추가하세요. 요약, compaction, 또는 컨텍스트 잘림은 접두어를 변경하고 캐시 재사용을 리셋할 수 있습니다.
  • 접두어를 다시 쓰지 않고 추론 effort 변경하기. GPT-6 모델에서는 configuration_update 입력 항목을 추가해 요청 수준 reasoning.effort를 변경하지 않고 응답 사이에 추론 effort를 변경하세요. 이는 캐시 재사용을 위해 원래 접두어를 보존합니다. 예시와 호환성 제한은 대화 중간에 추론 변경을 참고하세요.

변경되는 콘텐츠를 브레이크포인트 뒤에 유지

{
  "model": "gpt-5.6",
  "reasoning": { "effort": "low", "context": "all_turns" },
  "text": { "verbosity": "medium" },
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "Stable instructions and shared reference material...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        }
      ]
    },
    {
      "role": "developer",
      "content": "Dynamic developer instructions, such as user-specific content and timestamps..."
    },
    {
      "role": "user",
      "content": "The user's current question..."
    }
  ]
}

접두어를 다시 쓰지 않고 추론 effort 변경하기

지원되는 GPT-6 이상 모델에서 configuration_update 입력 항목을 추가해 이전 캐시된 접두어를 보존하면서 대화 중에 추론 effort를 변경하세요. 최상위 reasoning.effort는 원래 값으로 유지하세요. 이 설정을 변경하면 숨겨진 시스템 지침의 지침이 다시 쓰여질 수 있기 때문입니다.

가장 최근 구성 업데이트가 이후 응답의 추론 effort를 제어합니다. 예를 들어 기존 input 배열에 이 항목을 추가해 이후 요청을 high 추론으로 전환하세요:

입력 배열에 추가할 항목

{
  "type": "configuration_update",
  "reasoning": { "effort": "high" }
}

도구를 추가 전용 업데이트로 관리

애플리케이션이 필요로 하는 도구가 요청마다 다를 때, 재사용 가능한 접두어를 보존하면서 호출 가능한 도구를 변경하세요.

  • 도구를 일관되게 유지하세요. 도구 정의, 순서, 스키마를 보존하세요.
  • 요청에 대해 도구 사용을 비활성화하세요. 도구 정의를 제거하는 대신 tool_choice를 "none"으로 설정하세요.
  • 선택된 도구만 활성화하세요. 제공된 tools 목록을 안정적으로 유지하면서 호출 가능한 도구를 제한하려면 allowed_tools를 사용하세요.
  • 필요할 때 도구를 로드하세요. 다중 턴 스레드의 초기 요청에서 도구 정의에 소비되는 입력 토큰을 줄이려면 defer_loading: true와 함께 tool search를 사용하세요. 발견된 도구는 컨텍스트 끝에 추가되어 더 이른 재사용 가능 콘텐츠를 보존합니다.
  • 도구 로딩 기록을 보존하세요. 개발자 역할의 additional_tools 입력 항목을 사용해 애플리케이션 로직에 따라 스레드 중간에 도구를 추가하세요.

캐싱 모드 선택

GPT-5.6 이상에서 캐시 브레이크포인트가 배치되는 위치를 결정하는 두 가지 제어가 있습니다: prompt_cache_options.mode는 암시적 또는 명시적 전용 캐싱을 선택하고, prompt_cache_breakpoint는 선택한 경계를 표시합니다.

  • 브레이크포인트를 자동으로 배치하세요. 암시적 캐싱을 사용해 가장 최근의 자격이 되는 메시지 끝에 브레이크포인트를 배치하세요. 이는 기존 컨텍스트에 추가하는 다중 턴 스레드에 편리합니다.
  • 브레이크포인트를 의도적으로 선택하세요. 안정적인 콘텐츠 끝에 명시적 표시를 배치하세요. 변경되는 접미어에 불필요한 캐시 쓰기를 피하려면 명시적 전용 모드를 사용하세요.

그림: 명시적 전용 모드에서 도구와 스키마는 안정적인 developer 메시지 접두어와 브레이크포인트 1 앞에 옵니다. 한 분기는 브레이크포인트 2 전에 가변 developer 접미어와 더 많은 대화 턴을 추가한 뒤 새 user 입력으로 나뉩니다. 다른 분기는 선택되지 않은 가변 접미어를 갖습니다. 각 분기의 마지막 선택 브레이크포인트 이후 콘텐츠는 캐시 쓰기 요금 없이 비캐시 입력 요율로 청구됩니다.

캐시 프리워밍

GPT-5.6 이상의 경우 알려진 컨텍스트를 미리 준비해 후속 요청의 첫 토큰까지의 시간을 줄이세요. 예를 들어 대화형 애플리케이션은 사용자가 첫 질문을 하기 전에 시작 시 공유 지침, 도구 정의 또는 참조 자료를 프리워밍할 수 있습니다.

Responses API 요청에서 prompt_cache_options.prewarm을 true로 설정해 출력을 생성하지 않고 프롬프트 캐시를 준비하세요. 완료되면 같은 프롬프트 접두어로 실제 요청을 보내되 prewarm을 생략하거나 false로 설정하세요.

캐시 프리워밍

{
  "model": "gpt-5.6",
  "input": [
    {
      "role": "developer",
      "content": "Your app's shared instructions and reference material..."
    }
  ],
  "prompt_cache_options": {
    "prewarm": true
  }
}

후속 요청 보내기

{
  "model": "gpt-5.6",
  "input": [
    {
      "role": "developer",
      "content": "Your app's shared instructions and reference material..."
    },
    {
      "role": "user",
      "content": "The user's question..."
    }
  ]
}

참고: 프리워밍 요청 중 캐시에 쓰여진 토큰은 표준 캐시 쓰기 요율로 청구됩니다.

키로 캐시 회계 분리

GPT-5.6 이상에서 애플리케이션 내 고객, 사용자 또는 워크스페이스에 대해 별도의 캐시 회계를 유지하려면 prompt_cache_key를 사용하세요. 이는 각 그룹 내에서 캐시된 토큰 사용량과 청구를 설명하기 쉽게 만들 수 있습니다. 이 키는 선택 사항이며 이 모델들에서 캐싱을 최적화하는 데 필요하지 않습니다.

  • 캐시 회계를 분리하는 방법을 선택하세요. 캐시 회계를 분리해야 하는 각 고객이나 사용자에게 고유한 키를 할당하세요. 예를 들어 support:customer_123와 support:customer_456은 요청에 같은 접두어가 포함되어 있어도 두 고객에 대해 별도의 캐시 회계를 유지합니다.
  • 각 그룹 내에서 키를 안정적으로 유지하세요. 고객의 관련 요청에 같은 키를 재사용하세요. 세션이나 스레드에 자체 캐시 회계가 필요한 경우에만 별도의 키를 생성하세요.
  • 키를 일관되게 적용하세요. 고객의 요청에 걸쳐 해당 고객의 키를 사용해 별도의 캐시 회계를 유지하세요. 이는 고객 간 캐시 적중 탐색을 방지하는 데도 도움이 됩니다.

GPT-5.6 이전 모델에서는 prompt_cache_key가 캐시 적중률 최적화에 중요합니다. 재사용 가능한 접두어를 공유하는 요청에 안정적인 키를 사용해 같은 캐시로 라우팅하세요. 바쁜 그룹의 경우 더 많은 키에 트래픽 분산 지침을 따르세요.

캐시 보존 구성

이전 모델의 경우 모델과 데이터 보존 요구 사항이 허용한다면 확장 보존을 위해 prompt_cache_retention을 "24h"로 설정하는 것을 선호하세요. 지원되는 설정과 기본값은 캐시 수명을 참고하세요.

최소 캐시 가능 길이 비용 함정 탈출

많은 요청이 같은 개발자 지침과 도구 정의를 재사용하지만 그 공유 접두어가 모델의 최소 캐시 가능 길이보다 짧으면, 유용하고 안정적인 지침, 예시 또는 참조 자료로 그것을 줄이거나 확장하는 것을 고려하세요. 캐시 재사용이 추가 입력 토큰과 캐시 쓰기 요금을 상쇄하는지 측정하고, 평가와 동작이 안정적으로 유지되는지 확인하세요.

차트는 짧은 접두어 길이가 최소 캐시 가능 토큰 길이로 확장하는 것보다 더 많은 비캐시 비용이 들 수 있는 최소 캐시 가능 길이 비용 함정을 강조합니다.

수학적 세부 사항

비용만 비교한다면, $$M$$을 최소 캐시 가능 길이, $$L < M$$을 원래 접두어 길이, $$r$$을 캐시 읽기 배수, $$w$$를 캐시 쓰기 배수, $$N$$을 총 요청 수라고 하겠습니다. 확장된 접두어가 정확히 $$M$$ 토큰이고, 한 번 쓰이며, 이후 모든 요청에서 완전히 재사용된다고 가정합니다. 비캐시 입력 토큰 상당으로, 원래 접두어를 유지하면 $$N \times L$$이 들고, 확장하면 $$M \left[w + (N - 1)r\right]$$이 듭니다. 손익분기 원래 길이는 다음과 같습니다:

$$ L_{\mathrm{break\text{-}even}} = M\left(r + \frac{w-r}{N}\right) $$

$$L > L_{\mathrm{break\text{-}even}}$$이면 확장하세요; $$L < L_{\mathrm{break\text{-}even}}$$이면 더 짧은 접두어를 유지하는 것이 비용이 덜 듭니다. 같으면 비용이 동일합니다. 확장이 더 저렴한 가장 작은 정수 토큰 길이는 $$\left\lfloor L_{\mathrm{break\text{-}even}} \right\rfloor + 1$$입니다. 반대로 캐시 가능한 접두어를 $$M$$ 아래로 줄이면 캐싱을 잃습니다: 같은 가정에서 더 짧은 비캐시 접두어는 $$M$$ 토큰 캐싱보다 비용이 덜 들려면 $$L_{\mathrm{break\text{-}even}}$$ 아래여야 합니다. 보편적인 최대 비용 프롬프트 길이는 없습니다. 교차점은 재사용과 가격에 따라 달라집니다.

예를 들어 $$M = 1{,}024$$, $$r = 0.1$$, $$w = 1.25$$일 때 교차점은 $$102.4 + \frac{1{,}177.6}{N}$$ 토큰입니다. 10개 요청에서 최소 221토큰의 원래 접두어를 1,024토큰으로 확장하는 것이 더 저렴합니다. 재사용이 늘어나면 교차점은 102.4토큰에 접근합니다. 103토큰 접두어는 혜택을 보려면 총 최소 1,963개 요청이 필요합니다; 102토큰 이하의 접두어는 이 가정에서 절대 혜택이 없습니다. 이 비교는 성능, 출력 토큰, 변경되지 않은 요청 비용을 제외합니다. 추가 누락, 쓰기 또는 다른 모델 요율은 결과를 바꿉니다.

캐시 성능 모니터링

  • 실제 캐시 성능을 측정하세요. usage.input_tokens_details.cached_tokens, usage.input_tokens_details.cache_write_tokens, 입력 토큰 수, 지연 시간, 실현 비용을 추적하세요. 총 캐시된 토큰을 총 입력 토큰으로 나누어 토큰 캐시 적중률을 추적하되, 사용자·워크스페이스·일 또는 다른 유용한 그룹으로 두 수를 집계하세요.
  • 입력 비용을 계산하세요. response.usage의 토큰 수와 모델의 백만 토큰당 가격을 사용하세요.
  • 프롬프트 캐싱 대시보드를 사용하세요. Prompt Caching Dashboard에서 캐시 적중률을 모니터링하세요.

입력 비용 계산

function calculateInputCost(
  usage,
  inputPricePerMillion,
  cacheInputMultiplier = 0.1,
  cacheWriteMultiplier = 1.25
) {
  const inputTokens = usage.input_tokens;
  const cachedTokens = usage.input_tokens_details.cached_tokens;
  const cacheWriteTokens = usage.input_tokens_details.cache_write_tokens;
  const ordinaryInputTokens = inputTokens - cachedTokens - cacheWriteTokens;

  const weightedInputTokens =
    ordinaryInputTokens +
    cachedTokens * cacheInputMultiplier +
    cacheWriteTokens * cacheWriteMultiplier;
  const inputCost = (weightedInputTokens * inputPricePerMillion) / 1_000_000;
  return inputCost;
}

from openai.types.responses import ResponseUsage


def calculate_input_cost(
    usage: ResponseUsage,
    input_price_per_million: float,
    cache_input_multiplier: float = 0.1,
    cache_write_multiplier: float = 1.25,
) -> float:
    input_tokens = usage.input_tokens
    cached_tokens = usage.input_tokens_details.cached_tokens
    cache_write_tokens = usage.input_tokens_details.cache_write_tokens
    ordinary_input_tokens = input_tokens - cached_tokens - cache_write_tokens

    weighted_input_tokens = (
        ordinary_input_tokens
        + cached_tokens * cache_input_multiplier
        + cache_write_tokens * cache_write_multiplier
    )
    input_cost = weighted_input_tokens * input_price_per_million / 1_000_000
    return input_cost

def calculate_input_cost(
  usage,
  input_price_per_million,
  cache_input_multiplier = 0.1,
  cache_write_multiplier = 1.25
)
  input_tokens = usage.input_tokens
  details = usage.input_tokens_details
  cached_tokens = details.cached_tokens
  cache_write_tokens = details.cache_write_tokens
  ordinary_input_tokens = input_tokens - cached_tokens - cache_write_tokens

  weighted_input_tokens = ordinary_input_tokens +
                          (cached_tokens * cache_input_multiplier) +
                          (cache_write_tokens * cache_write_multiplier)
  (weighted_input_tokens * input_price_per_million) / 1_000_000
end

이전 모델에서 GPT-5.6 이상으로 프롬프트 캐싱 마이그레이션

  • 기존의 안정적인 접두어를 유지하세요.
  • prompt_cache_key를 사용한다면 기존 값을 유지해 고객이나 사용자에 대한 별도 캐시 회계를 보존하세요.
  • prompt_cache_retention을 prompt_cache_options.ttl로 교체하세요.
  • 재사용 가능한 접두어가 모델의 최소 캐시 가능 길이를 충족하는지 확인하세요.
  • 기본 브레이크포인트가 요청 간 변경되는 콘텐츠를 포함한다면 안정적인 접두어 뒤에 명시적 브레이크포인트를 추가하세요.
  • 이후 콘텐츠가 쓰기에 가치가 없을 때 prompt_cache_options.mode: "explicit"을 사용하세요.
  • 마이그레이션 전후로 cached_tokens, cache_write_tokens, 지연 시간, 총 비용을 비교하세요.

예시

다음 예시는 GPT-5.6 이상 모델에 적용됩니다.

단일 턴 LLM-as-a-Judge

챗봇과의 상호작용 후 사용자가 만족했다는 증거를 완료된 상호작용이 보여주는지 판단하는 단일 턴 LLM 판사를 고려해 보세요. 각 요청은 동일한 채점 루브릭과 라벨링된 few-shot 예시를 사용해 서로 다른 상호작용을 평가합니다.

  • 접두어 보존: 고정된 루브릭과 예시가 먼저 옵니다. 결합 길이는 판사 보정에 도움이 되는 자료를 사용해 모델의 최소 캐시 가능 길이 바로 위로 의도적으로 유지됩니다. 평가되는 상호작용이 마지막에 옵니다.
  • 캐싱 모드와 브레이크포인트: 명시적 전용 캐싱이 활성화되어 있고, 고정된 루브릭과 예시 뒤에 브레이크포인트가 있습니다. 평가되는 사용자-챗봇 대화는 그 브레이크포인트 뒤에 오며 캐시에 쓰이지 않아, 재사용될 가능성이 낮은 콘텐츠에 대한 캐시 쓰기 요금을 피합니다.

이 원리를 사용한 예시 배포는 **토큰 캐시 적중률 약 70%**를 보고했습니다. 이 수치는 가능한 결과를 나타냅니다. 실제 캐시 적중률 상한은 컨텍스트와 애플리케이션 사용량에 따라 달라집니다.

단일 턴 판사를 위한 Responses API 요청

{
  "model": "gpt-5.6-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "low" },
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "Judge whether the completed interaction provides evidence that the user is satisfied. Return true or false. Full grading rubric and labeled few-shot examples...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        }
      ]
    },
    {
      "role": "user",
      "content": "Completed interaction to evaluate..."
    }
  ]
}

다중 턴 에이전트

길고 공유된 개발자 지침과 빈번한 도구 호출이 있는 다중 턴 에이전트를 고려해 보세요. 일반적인 사용은 사용자가 에이전트로 여러 세션을 동시에 실행하고, 종종 스레드를 분기(fork)하는 것입니다.

  • 접두어 보존: 각 턴은 이전 컨텍스트를 다시 쓰지 않고 새 메시지, 도구 호출, 결과를 추가하므로 재사용 가능한 접두어가 시간이 지나면서 커집니다.
  • 선택적 프롬프트 캐시 키: 이 예시는 agent_123_v1:user_456을 사용해 사용자 456의 별도 캐시 회계를 유지하며, 그들의 캐시된 토큰 사용량과 청구를 설명하기 쉽게 만듭니다. 이는 사용자 간 캐시 적중 탐색을 방지하는 데도 도움이 됩니다. 키는 해당 사용자의 에이전트와의 세션 및 분기에 걸쳐 동일하게 유지됩니다. 애플리케이션에 이 분리가 필요하지 않으면 생략하세요.
  • 암시적 캐싱 모드: 가장 최근의 자격이 되는 user 또는 tool 메시지가 브레이크포인트를 제공하도록 암시적 캐싱이 활성화됩니다.
  • 명시적 브레이크포인트: 각 tool 결과 뒤에 브레이크포인트가 추가되어 이전 재사용 가능한 접두어를 보존하고 분기의 캐시 효율을 개선합니다.

이 원리를 사용한 예시 배포는 **토큰 캐시 적중률 >90%**를 보고했습니다. 이 수치는 가능한 결과를 나타냅니다. 실제 캐시 적중률 상한은 컨텍스트와 애플리케이션 사용량에 따라 달라집니다.

다중 턴 에이전트를 위한 Responses API 요청

{
  "model": "gpt-5.6-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "medium" },
  "prompt_cache_key": "agent_123_v1:user_456",
  "prompt_cache_options": { "mode": "implicit" },
  "tools": [
    {
      "type": "function",
      "name": "function_name",
      "description": "Function description",
      "parameters": { "...": "..." }
    }
  ],
  "input": [
    {
      "role": "developer",
      "content": "Stable developer instructions and reference material..."
    },
    { "role": "user", "content": "Can you do...?" },
    {
      "type": "function_call",
      "call_id": "call_123",
      "name": "function_name",
      "arguments": "..."
    },
    {
      "type": "function_call_output",
      "call_id": "call_123",
      "output": [
        {
          "type": "input_text",
          "text": "Tool result...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        }
      ]
    },
    { "role": "assistant", "content": "Assistant response..." },
    { "role": "user", "content": "Can you also do...?" }
  ]
}

함정 (Gotchas)

공유 접두어가 항상 캐시된 접두어인 것은 아닙니다

이는 특히 암시적 캐싱 동작의 변경으로 이전 모델에서 GPT-5.6 이상으로 마이그레이션할 때 널리 나타납니다. 요청이 긴 접두어를 공유하지만 접미어가 다르면, 첫 번째 완전한 요청을 암시적으로만 캐시해도 더 짧은 공유 접두어가 재사용 가능해지지 않습니다.

각 요청에서 정적 developer 메시지 뒤에 동적 user 메시지가 오는 경우를 생각해 보세요. 이 요청은 동적 콘텐츠를 통해 쓰기를 합니다. 다음 요청에서 그 콘텐츠를 변경하면 더 긴 캐시된 접두어와 일치하지 않으며, 정적 콘텐츠 뒤에 별도의 브레이크포인트가 없습니다.

정적 콘텐츠 뒤에 브레이크포인트 없음

{
  "model": "gpt-5.6-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "low" },
  "prompt_cache_options": { "mode": "implicit" },
  "input": [
    { "role": "developer", "content": "Static content..." },
    { "role": "user", "content": "Dynamic content..." }
  ]
}

해결하려면 두 요청 모두에서 정적 콘텐츠 뒤에 명시적 브레이크포인트를 배치하세요. 첫 번째 요청이 재사용 가능한 접두어를 쓰고, 다음 요청은 동적 콘텐츠가 변경되어도 그것을 재사용할 수 있습니다. 이 예시는 동적 콘텐츠를 캐시에 쓰지 않도록 명시적 전용 모드를 사용합니다.

정적 콘텐츠 뒤에 브레이크포인트 있음

{
  "model": "gpt-5.6-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "low" },
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    {
      "role": "developer",
      "content": [{
        "type": "input_text",
        "text": "Static content...",
        "prompt_cache_breakpoint": { "mode": "explicit" }
      }]
    },
    { "role": "user", "content": "Dynamic content..." }
  ]
}

명시적 전용 모드로 전환하면 암시적 캐시 쓰기를 놓칠 수 있습니다

요청 1이 암시적 모드를 사용해 user 메시지 끝까지 접두어를 캐시하고, 후속 요청 2가 그 접두어를 보존하지만 prompt_cache_options.mode: "explicit"으로 전환한다고 가정해 보세요. 접두어 일치 작동 방식에서 설명했듯이 요청 2는 자체 입력의 명시적 브레이크포인트만 확인하므로, 요청 1의 저장된 암시적 접두어를 재사용하지 않습니다(요청 2의 명시적 브레이크포인트 중 하나가 요청 1의 캐시된 끝점과 일치하지 않는 한).

▼ = breakpoint

- Request 1: implicit mode
  [Developer message][User message] ▼

- Request 2: explicit-only mode. Does not hit cache.
  [Developer message][User message][Follow-up] ▼

요청 1의 암시적 접두어를 재사용하려면 요청 2의 일치하는 콘텐츠 블록 경계에 명시적 브레이크포인트를 배치하거나, 더 이른 자격 메시지 끝이 조회 후보로 남도록 암시적 모드를 유지하세요.

메시지를 확장하면 캐시된 접두어 재사용이 막힐 수 있습니다

두 요청 모두 암시적 모드를 사용하더라도 같은 초기 토큰을 보존하는 것만으로는 항상 충분하지 않습니다. 요청 1이 Content A를 포함하는 user 메시지로 끝나고, 후속 요청 2가 그 메시지를 Content A + Content B로 확장한다고 가정해 보세요. Content A 뒤의 이전 끝점은 이제 메시지 끝이 아니라 내부에 있습니다. 접두어 일치 작동 방식에서 설명했듯이 그 경계에 명시적 브레이크포인트가 없으면 요청 2는 거기에 저장된 접두어를 재사용하지 않습니다.

▼ = breakpoint

- Request 1: implicit mode
  [Developer message][User message: Content A] ▼

- Request 2: implicit mode. Cannot reuse the prefix through Content A.
  [Developer message][User message: Content A + Content B] ▼

대화 구조가 허용하면 원래 메시지를 보존하고 새 메시지를 추가하세요. 그렇지 않으면 재사용 가능한 텍스트를 별도의 콘텐츠 블록에 유지하고 두 요청 모두에서 그 뒤에 명시적 브레이크포인트를 배치하세요.

모든 developer 메시지가 암시적 모드 캐시 조회 경계인 것은 아닙니다

암시적 모드에서 초기 연속 developer 메시지 블록 이후의 developer 메시지는 자동 캐시 조회 경계가 아닙니다. 재사용 가능한 developer 메시지 끝에 명시적 브레이크포인트를 추가해 후속 요청에서 그 브레이크포인트를 보존하면 OpenAI가 일치하는 캐시된 접두어를 확인할 수 있습니다.

최소 캐시 가능 길이는 모델에 따라 다릅니다

한 모델에서 캐싱 자격이 되는 접두어는 다른 모델에서는 너무 짧을 수 있습니다. 모델 비교를 확인하고 실제로 사용하는 모델과 설정으로 재사용 가능한 접두어를 측정하세요. 모델을 변경할 때 이전 모델의 임계값이 여전히 적용된다고 가정하지 말고 다시 확인하세요.

Compaction은 캐시 재사용을 줄일 수 있습니다

Compaction은 이전 대화 컨텍스트를 더 짧은 표현으로 대체합니다. 이는 접두어를 변경할 수 있으므로, 대화가 논리적으로 같아도 compaction 후 첫 요청은 이전 캐시를 덜 재사용할 수 있습니다.

가능하면 재사용 가능한 지침과 참조 자료를 안정적으로 유지한 뒤, 이후 턴이 압축된 컨텍스트 위에 구축되게 하세요. compaction 전후의 총 입력 비용을 비교하세요: 캐시 적중률이 떨어져도 입력 토큰이 적으면 여전히 비용을 절약할 수 있습니다.

자주 묻는 질문

프롬프트 캐싱이 출력 생성에 영향을 주나요?

아니요. 프롬프트 캐싱은 모델이 출력 토큰을 생성하는 방식을 바꾸지 않습니다. 모델은 캐시된 접두어를 사용해 새 응답을 생성하므로, 동일한 요청이 동일한 출력을 생성한다는 보장은 없습니다.

캐시를 수동으로 지울 수 있나요?

아니요. 수동 캐시 비우기는 현재 제공되지 않습니다. 캐시 항목은 모델의 캐시 수명과 보존 설정에 따라 만료됩니다.

캐시된 프롬프트가 속도 제한에 집계되나요?

네. 캐시된 입력 토큰은 여전히 분당 토큰 제한에 집계됩니다. 프롬프트 캐싱은 속도 제한 계산 방식을 바꾸지 않습니다.

더 알아보기 (Learn more)