프롬프트 캐싱

같은 요청이 반복될 때 이전에 처리한 프롬프트 앞부분을 재사용하면 비용도 시간도 아낄 수 있어요. 프롬프트 캐싱이 바로 그 작업을 해 주는 기능이고, 큰 시스템 프롬프트나 대화 히스토리를 반복해 보내는 애플리케이션에서 특히 체감이 큽니다. 이 가이드에서는 캐시가 무엇인지, 어떻게 동작하는지, 그리고 재사용률을 높이려면 어떻게 설정해야 하는지 차례대로 설명할게요.

출처: 공식문서

왜 프롬프트 캐싱이 중요할까?

프롬프트 캐싱은 요청이 같은 프롬프트 접두사(prefix)를 공유할 때 이전 작업을 재사용해요. 여기서 세 가지 주요 이점이 나와요.

계산 효율: 모델이 이미 처리한 프롬프트 접두사를 다시 계산하지 않는다.
입력 토큰 비용 절감: 재사용되는 토큰에 모델의 할인된 캐시 입력 요율을 적용해 최대 90%까지 할인받는다.
더 빠른 속도: 응답이 시작되기 전에 입력을 처리하는 시간을 줄인다.

프롬프트 캐싱은 지원되는 OpenAI 모델에서 기본적으로 활성화돼 있어요. Prompt Caching Dashboard에서 캐시 읽기 적중률을 모니터링하고, Prompt Cache Diagnostics 도구로 캐시 미스를 진단해 재사용을 개선할 수 있습니다. Agents API 모델 호출도 Responses API와 같은 프롬프트 캐싱 동작을 사용해요. 세션 안에서 컨텍스트를 재사용하면 공유 프롬프트 접두사를 보존할 수 있지만, 세션을 유지한다고 해서 캐시 적중이 보장되는 건 아니에요.

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

모델이 입력 토큰을 처리할 때는 키-값(KV) 상태라고 불리는 중간 상태를 계산해야 해요. 이 상태 덕분에 모델이 새 입력을 처리하고 출력 토큰을 생성하면서 이전 토큰을 참조할 수 있습니다. 프롬프트 캐싱은 이 상태를 재사용 가능한 접두사(프롬프트 시작 부분의 변경되지 않은 토큰)에 대해 보존해요. 나중에 요청이 같은 접두사를 갖고 일치하는 캐시 항목을 찾으면, 모델은 그 토큰들을 다시 처리하는 대신 저장된 상태를 재사용할 수 있죠. 새 응답을 생성하려면 새 입력은 여전히 처리해야 해요.

프롬프트 캐시는 토큰 자체가 아니라 키-값(KV) 텐서를 저장해요. OpenAI는 모델이 렌더링한 전체 컨텍스트를 캐시하는데, 여기에는 OpenAI가 제공한 지시문, 개발자 메시지, 도구 정의, 그리고 텍스트·이미지·문서·지원되는 오디오를 담은 대화 히스토리가 포함됩니다. 캐시 재사용은 렌더링된 전체 접두사가 일치해야 해요. 브레이크포인트 앞에서 콘텐츠나 관련 설정이 바뀌면, 그 변경 이후의 접두사는 기존 캐시 항목과 일치할 수 없어요.

어떤 설정이 캐시된 접두사에 영향을 주나요?

요청을 바꾼다고 해서 기존 캐시 항목이 반드시 버려지는 건 아니에요. 중요한 건 후속 요청이 같은 접두사를 갖고 적격한 일치 브레이크포인트를 찾을 수 있느냐입니다. 확인할 주요 설정은 이렇습니다.

설정	영향
`model`	다른 모델은 다른 가중치와 캐싱 동작을 쓸 수 있음
`tools`	도구 이름·설명·스키마·순서·도구 특화 지시문을 바꿈
`parallel_tool_calls`	한 턴에 여러 도구 호출에 대한 지시를 바꿀 수 있음
`text.format` (Structured Outputs)	출력 형식 지시와 요청 스키마를 추가함
`reasoning.effort`	모델 측 추론 지시를 바꿀 수 있음. 지원 모델에서는 이전 접두사를 보존하면서 설정을 바꾸려면 configuration update 사용
`text.verbosity`	응답 상세에 대한 지시를 바꿀 수 있음
`context_management` (Compaction)	이전 대화 콘텐츠를 압축된 컨텍스트로 대체해 첫 변경 토큰부터 재사용을 막을 수 있음

캐싱 동작 방식

캐시 브레이크포인트(cache breakpoint) 는 OpenAI가 캐시에 저장했다가 나중에 재사용할 수 있는 프롬프트 접두사의 끝을 표시해요. 첫 요청이 적격한 접두사를 캐시에 쓰고, 이후 요청은 사용 가능한 적격 브레이크포인트를 역순으로 거슬러 가며 일치하는 캐시된 접두사 중 가장 긴 것을 찾습니다.

프롬프트 접두사는 캐시되려면 모델의 최소 캐시 가능 토큰 길이를 충족해야 해요. OpenAI가 제공한 숨은 시스템 콘텐츠의 토큰은 이 최소값에 포함되지 않습니다. 최소 캐시 가능 프롬프트 길이는 GPT-5.6 이후 모델에서 1,024토큰이고, 이전 모델에서는 요청 설정에 따라 달라져요. 아래 모델 비교 표에서 자세히 확인할 수 있습니다.

최소 캐시 가능 토큰 길이 이후에는 캐시 브레이크포인트 위치를 직접 정하거나, OpenAI가 암시적으로 위치를 선택하게 할 수 있어요. 옵션은 모델에 따라 달라집니다.

GPT-5.6 이후 모델

GPT-5.6 이후 모델에서는 캐시 쓰기(write)가 표준·비캐시 입력 토큰 요율의 1.25배로 비용이 들어요. 접두사가 재사용될 걸 알 때 이 비용을 감수할 만한데, 이후 읽기는 그 요율의 0.1배만 하면 되기 때문이에요. 접두사를 한 번 쓰고 완전히 한 번 재사용하면 비용은 캐시 없이 두 번 처리했을 때 2배와 비교해 보통 입력 비용의 1.35배예요. 캐시 읽기가 추가될수록 절약은 커져서, 열 번 요청에 한 번 쓰고 아홉 번 전부 읽으면 캐싱 없이 10배일 때와 비교해 2.15배가 됩니다.

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

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

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가 가장 최근 적격 메시지의 끝에 브레이크포인트를 둡니다. 적격 메시지는 사용자 메시지, 연속된 도구 응답 그룹의 마지막 도구 응답, 초기 연속 개발자 메시지 그룹의 마지막 개발자 메시지예요.
암시적 브레이크포인트를 끄지 않고 명시적 브레이크포인트를 추가할 수 있어요. 암시적 브레이크포인트는 네 개의 캐시 쓰기 슬롯 중 하나를 사용해 세 개의 사용 가능한 명시적 캐시 쓰기 슬롯을 남깁니다.

이전 모델

암시적 캐싱만 지원돼요. OpenAI는 숨은 OpenAI 시스템 메시지의 시작부터 세어 모델별 간격으로 암시적 브레이크포인트를 둡니다. 최소 캐시 가능 길이(숨은 컨텍스트의 끝에서 계산) 이상에 있는 브레이크포인트만 적격입니다. 보고되는 cached_tokens는 마지막 일치 브레이크포인트에서 숨은 시스템 토큰을 뺀 뒤 128의 배수로 내림해 계산해요.

접두사 일치 동작 방식

OpenAI는 들어오는 요청에서 캐시 조회 경계(아래 설명)만 가장 긴 접두사부터 짧은 순으로 훑어서, 이미 기계에 캐시된 일치 접두사가 있는지 찾아요. GPT-5.6 이후 모델의 들어오는 요청에서 캐시 조회 경계는 이렇습니다.

명시적 전용 모드: 처음 2개와 최신 50개 명시적 브레이크포인트.
암시적 모드: 처음 2개와 최신 50개 명시적 브레이크포인트, 암시적 브레이크포인트, 최대 20개의 이전 적격 메시지 끝, 그리고 초기 연속 개발자 메시지 블록의 끝점. 이렇게 하면 암시적 모드가 거기에 명시적 브레이크포인트 없이도 더 이른 메시지에서 끝나는 접두사를 재사용할 수 있어요.

캐시 수명

캐시 항목은 무기한 저장되지 않아요. 후속 요청은 항목이 사용 가능한 동안에만 캐시된 접두사를 재사용할 수 있고, 접두사를 재사용하면 캐시 쓰기 비용 없이 수명이 새로워집니다. 수명과 보존 설정은 모델에 따라 달라져요.

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 로컬 저장소에 저장할 수 있어요. in_memory와 24h를 모두 지원하는 모델에서는 조직의 데이터 보존 정책에 따라 기본값이 달라집니다.

Zero Data Retention을 켜지 않은 조직은 기본값이 24h예요.
Zero Data Retention을 켠 조직은 기본값이 in_memory입니다.

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

캐시 위치

캐시된 상태는 개별 기계에 저장되고, 분당 15요청 이상의 트래픽에서는 오버플로 라우팅이 발생할 수 있어요. 요청은 일치 항목이 있고 만료되지 않은 기계에 도달할 때만 캐시된 접두사를 재사용할 수 있으므로, 캐시 재사용에는 올바른 기계로의 라우팅이 중요합니다. 캐시는 조직 간에 공유되지 않고 리전별 처리 경계를 넘어 재사용될 수 없어요.

OpenAI가 라우팅을 자동으로 처리해요. 조직과 처리 리전 내에서 주어진 모델의 라우팅은 다음에 따라 달라집니다.

현재 기계 부하와 가용 용량.
숨은 OpenAI 콘텐츠 이후 초기 토큰의 해시(도구 정의가 있으면 포함). 해시되는 토큰 수는 모델마다 달라요.
선택적 prompt_cache_key로, 요청 그룹 간 캐시 재사용을 분리합니다.

프롬프트 캐시 키

prompt_cache_key는 애플리케이션 안에서 고객이나 사용자별로 캐시 회계를 분리하기 위한 선택적 제어 수단이에요. OpenAI가 캐시 라우팅을 자동으로 처리하므로 보통 캐싱에서는 이 키를 생략할 수 있습니다. 별도 키를 쓰면 고객·사용자별 캐시 토큰 사용량과 과금을 설명하기 쉬워져요. 예를 들어 여러 사용자에 걸친 캐시 적중 프로빙(후보 프롬프트를 제출하고 캐시 적중을 관찰해 일치 콘텐츠가 이전에 캐시됐는지 알아내는 것)을 막는 데도 도움이 됩니다.

모델 차이 요약

동작	GPT-5.6 이후	GPT-5.5·GPT-5.5 Pro	기타 이전 모델
암시적 브레이크포인트	가장 최근 적격 메시지 끝	2,048토큰 규칙 간격	모델별 규칙 간격
명시적 브레이크포인트	지원	미지원	미지원
최소 캐시 가능 접두사	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 이전 모델에서는 최소 캐시 가능 입력 길이가 도구·이미지·출력 스키마·추론 노력·상세도 등 요청 설정에 따라 달라집니다.

프롬프트 캐싱 최적화 방법

핵심은 대화 히스토리 보존, 도구 정의 안정성 유지, 그리고 캐싱이 일어날 위치를 고르는 것이에요. prompt_cache_options.mode와 prompt_cache_breakpoint로 캐시 브레이크포인트를 제어하고, 고객별 캐시 회계가 필요하면 선택적 prompt_cache_key를 쓸 수 있습니다.

대화 히스토리 보존

멀티턴 애플리케이션에서는 커져 가는 대화 히스토리를 재사용하는 게 초기 지시만 캐시하는 것보다 더 많은 입력 토큰을 아낄 수 있어요. 이전 메시지와 도구 결과를 보존해서 뒷턴이 전체 공유 접두사를 재사용할 수 있게 하세요.

접두사를 안정적으로 유지하세요. 안정적인 개발자 지시와 공유 참고 자료를 앞에 두세요. 개발자 지시·공유 자료에 타임스탬프·사용자 특화 콘텐츠 등 동적 콘텐츠가 있다면 그걸 시작이 아닌 끝에 두거나, 나중 대화 메시지로 옮기세요.
대화 히스토리를 보존하세요. 이전 턴을 다시 쓰기보다 새 메시지를 추가하세요. 요약·압축·컨텍스트 잘라내기는 접두사를 바꿔 캐시 재사용을 초기화할 수 있어요.
접두사를 다시 쓰지 않고 추론 노력을 바꾸세요. GPT-6 Astra에서는 configuration_update 입력 항목을 추가해 요청 레벨 reasoning.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..."
    }
  ]
}

접두사를 다시 쓰지 않고 추론 노력 바꾸기

지원되는 GPT-6 이후 모델에서 configuration_update 입력 항목을 추가하면 이전 캐시 접두사를 보존하면서 대화 중 추론 노력을 바꿀 수 있어요. 상위 레벨 reasoning.effort는 원래 값으로 유지하세요. 그 설정을 바꾸면 숨은 시스템 지시의 지시가 다시 쓰여질 수 있기 때문이에요. 최신 configuration update가 이후 응답의 추론 노력을 제어합니다. 예를 들어 기존 input 배열에 이 항목을 추가해 이후 요청을 high 추론으로 전환할 수 있어요.

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

도구를 append-only로 관리하기

요청마다 필요한 도구가 달라진다면, 재사용 가능한 접두사를 보존하기 위해 도구 정의는 안정적으로 유지한 채 호출 가능한 도구만 바꾸세요.

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

캐싱 모드 고르기

GPT-5.6 이후 모델에서는 두 제어가 캐시 브레이크포인트 위치를 결정해요. prompt_cache_options.mode는 암시적 또는 명시적 전용 캐싱을 고르고, prompt_cache_breakpoint는 직접 고른 경계를 표시합니다.

브레이크포인트를 자동으로 두세요. 암시적 캐싱을 쓰면 가장 최근 적격 메시지 끝에 브레이크포인트를 둬요. 기존 컨텍스트에 이어붙이는 멀티턴 스레드에 편리하죠.
의도적으로 브레이크포인트를 고르세요. 안정된 콘텐츠의 끝에 명시적 마커를 두고, 명시적 전용 모드로 바뀌는 접미사에 대한 불필요한 캐시 쓰기를 피하세요.

명시적 전용 모드에서 주의할 점: 도구와 스키마가 안정적인 개발자 메시지 접두사와 브레이크포인트 1 앞에 옵니다. 한 갈래는 가변 개발자 접미사와 대화 턴을 더해 브레이크포인트 2 앞에 두고 새 사용자 입력으로 나뉘고, 다른 갈래는 선택되지 않은 가변 접미사를 둡니다. 각 갈래의 마지막 선택 브레이크포인트 이후 콘텐츠는 캐시 쓰기 비용 없이 비캐시 입력 요율로 과금돼요.

캐시 키로 회계 분리

고객·사용자·워크스페이스별로 별도의 캐시 회계를 유지하고 싶을 때 prompt_cache_key를 쓰세요. 그러면 각 그룹 안에서 캐시 토큰 사용량과 과금을 설명하기 쉬워져요. 이 키는 선택 사항이고 캐싱 최적화에 필수는 아닙니다.

캐시 회계를 나눌 방식 고르기. 캐시 회계를 분리해야 하는 고객·사용자마다 고유 키를 할당하세요. 예를 들어 support:customer_123과 support:customer_456은 요청에 같은 접두사가 있어도 두 고객의 캐시 회계를 분리합니다.
그룹 안에서 키를 안정적으로 유지하세요. 한 고객의 관련 요청에 같은 키를 재사용하세요. 자체 캐시 회계가 필요한 세션·스레드에만 별도 키를 만드세요.
키를 일관되게 적용하세요. 고객의 요청 전체에 그 키를 써서 별도 캐시 회계를 유지하고, 고객 간 캐시 적중 프로빙을 막는 데도 도움이 됩니다.

캐시 보존 설정

이전 모델에서는 모델과 데이터 보존 요구사항이 허용할 때 prompt_cache_retention을 "24h"로 설정해 확장 보존을 선호하세요. 지원 설정과 기본값은 캐시 수명 섹션을 참고하세요.

최소 캐시 가능 길이 비용 함정 벗어나기

많은 요청이 같은 개발자 지시와 도구 정의를 재사용하는데 그 공유 접두사가 모델의 최소 캐시 가능 길이보다 짧다면, 유용하고 안정적인 지시·예시·참고 자료로 접두사를 줄이거나 늘리는 걸 고려하세요. 캐시 재사용이 추가 입력 토큰과 캐시 쓰기 비용을 상쇄하는지 측정하고, 평가와 동작이 안정적인지 확인하세요. 짧은 접두사 길이가 최소 캐시 가능 토큰 길이까지 늘리는 것보다 더 비쌀 수 있다는 점이 바로 이 비용 함정이에요.

수학적으로는 최소 캐시 가능 길이를 M, 원래 접두사 길이를 L < M, 캐시 읽기 배수를 r, 캐시 쓰기 배수를 w, 총 요청 수를 N이라 할 때, 원래 접두사를 유지하는 비용은 N × L, 늘린 경우는 M[w + (N - 1)r](비캐시 입력 토큰 등가)입니다. 손익분기 원래 길이는 L_break-even = M(r + (w-r)/N)이에요. L > L_break-even이면 늘리고, L < L_break-even이면 짧게 유지하는 게 저렴합니다. 예를 들어 M = 1,024, r = 0.1, w = 1.25라면 손익분기는 102.4 + 1,177.6/N토큰입니다. 10회 요청에서 221토큰 이상의 원래 접두사를 1,024토큰으로 늘리는 게 저렴해요. 수치는 재사용과 가격에 따라 달라집니다.

캐시 성능 모니터링

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

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

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

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

예시

단일 턴 LLM-as-a-Judge

챗봇과의 상호작용이 끝났을 때 사용자가 만족했는지 증거가 있는지 판단하는 단일 턴 LLM 심사자를 생각해 볼게요. 각 요청은 같은 채점 루브릭과 레이블된 few-shot 예시를 사용해 서로 다른 상호작용을 평가해요.

접두사 보존: 고정된 루브릭과 예시를 앞에 두고, 그 결합 길이를 의도적으로 모델의 최소 캐시 가능 길이 바로 위로 유지해 심사자 보정을 돕는 자료를 사용해요. 평가 대상 상호작용은 마지막에 둡니다.
캐싱 모드와 브레이크포인트: 고정된 루브릭·예시 뒤에 브레이크포인트를 두고 명시적 전용 캐싱을 켭니다. 평가 대상 사용자-챗봇 대화는 브레이크포인트 뒤에 와서 캐시에 쓰이지 않으므로, 재사용될 것 같지 않은 콘텐츠에 대한 캐시 쓰기 비용을 피할 수 있어요.

이 원리를 쓴 예시 배포는 약 70%의 토큰 캐시 적중률을 보고했어요. 이 수치는 가능한 결과를 보여주는 것이고, 실제 적중률 상한은 컨텍스트와 애플리케이션 사용에 따라 달라집니다.

{
  "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..."
    }
  ]
}

멀티턴 에이전트

길고 공유되는 개발자 지시와 잦은 도구 호출이 있는 멀티턴 에이전트를 생각해 볼게요. 전형적인 사용은 사용자가 에이전트로 여러 세션을 동시에 돌리고 스레드를 자주 포크하는 경우예요.

접두사 보존: 각 턴이 이전 컨텍스트를 다시 쓰지 않고 새 메시지·도구 호출·결과를 추가하므로, 재사용 가능한 접두사가 시간이 지나며 커져요.
선택적 프롬프트 캐시 키: 이 예시는 agent_123_v1:user_456을 써서 사용자 456의 캐시 회계를 분리하고, 그 캐시 토큰 사용량과 과금을 설명하기 쉽게 해요. 이 또한 사용자 간 캐시 적중 프로빙을 막는 데 도움이 됩니다. 이 키는 그 사용자의 세션·포크 전반에 걸쳐 동일하게 유지되고, 이 분리가 필요 없다면 생략하세요.
암시적 캐싱 모드: 가장 최근 적격 사용자·도구 메시지가 브레이크포인트를 제공하도록 암시적 캐싱을 켭니다.
명시적 브레이크포인트: 각 도구 결과 뒤에 브레이크포인트를 추가해 이전 재사용 가능한 접두사를 보존하고 포킹의 캐시 효율을 높여요.

이 원리를 쓴 예시 배포는 90% 이상의 토큰 캐시 적중률을 보고했어요. 이 수치는 가능한 결과를 보여주는 것이고, 실제 적중률 상한은 컨텍스트와 애플리케이션 사용에 따라 달라집니다.

{
  "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 이후로 마이그레이션할 때 특히 자주 겪는 문제예요. 암시적 캐싱 동작이 바뀌었기 때문이죠. 요청이 긴 접두사를 공유하지만 접미사가 다르다면, 첫 완전 요청을 암시적 전용으로 캐시해도 짧은 공유 접두사가 재사용 가능해지지는 않아요.

각 요청에 정적인 개발자 메시지 뒤에 동적인 사용자 메시지가 온다고 생각해 보세요. 이 요청은 동적 콘텐츠까지 쓴 뒤, 다음 요청에서 그 콘텐츠를 바꾸면 더 긴 캐시된 접두사와 일치하지 않고, 정적 콘텐츠 뒤에 별도 브레이크포인트도 없어요.

{
  "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이 암시적 모드를 쓰고 사용자 메시지 끝까지의 접두사를 캐시했다고 해 볼게요. 후속 요청 2가 그 접두사를 보존하지만 prompt_cache_options.mode: "explicit"으로 바꾸면, 접두사 일치 동작에서 설명했듯이 요청 2는 자기 입력의 명시적 브레이크포인트만 검사하므로 요청 1의 저장된 암시적 접두사(요청 2의 명시적 브레이크포인트 중 하나가 요청 1의 캐시 끝점과 일치하지 않는 한)를 재사용하지 않아요.

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

메시지 확장은 그 캐시 접두사 재사용을 막을 수 있다

두 요청이 모두 암시적 모드를 써도 같은 초기 토큰을 보존하는 게 항상 충분하진 않아요. 요청 1이 Content A를 담은 사용자 메시지로 끝나고, 요청 2가 같은 메시지를 Content A + Content B로 확장했다고 해 볼게요. Content A 이후의 옛 끝점은 이제 메시지 끝이 아니라 안쪽에 있으므로, 그 경계에 명시적 브레이크포인트가 없다면 요청 2는 거기에 저장된 접두사를 재사용하지 않아요. 대화 구조가 허용한다면 원래 메시지를 보존하고 새 메시지를 추가하세요. 그게 어렵다면 재사용 가능한 텍스트를 별도 콘텐츠 블록에 두고 두 요청 모두에서 그 뒤에 명시적 브레이크포인트를 배치하세요.

모든 개발자 메시지가 암시적 모드 캐시 조회 경계는 아니다

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

최소 캐시 가능 길이는 모델마다 다르다

한 모델에서 캐싱에 적격한 접두사가 다른 모델에서는 너무 짧을 수 있어요. 모델 비교 표를 확인하고 실제 쓰는 모델·설정으로 재사용 가능한 접두사를 측정하세요. 모델을 바꿀 때는 이전 모델의 기준이 여전히 적용된다고 가정하지 말고 다시 확인하세요.

압축은 캐시 재사용을 줄일 수 있다

압축(Compaction)은 이전 대화 컨텍스트를 더 짧은 표현으로 대체해요. 그러면 접두사가 바뀔 수 있어서, 대화가 논리적으로 같더라도 압축 후 첫 요청은 이전 캐시를 덜 재사용할 수 있습니다. 가능하면 재사용 가능한 지시·참고 자료를 안정적으로 유지하고, 이후 턴이 압축된 컨텍스트 위에 쌓이게 하세요. 압축 전후의 총 입력 비용을 비교해 보세요. 캐시 적중률이 떨어져도 입력 토큰이 줄면 여전히 비용을 아낄 수 있습니다.

자주 묻는 질문

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

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

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

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

캐시된 프롬프트가 레이트 리밋에 포함되나요?

네. 캐시된 입력 토큰도 분당 토큰 한도에 계속 집계돼요. 프롬프트 캐싱은 레이트 리밋 계산 방식을 바꾸지 않습니다.

더 알아보기 (Learn more)

Responses API 레퍼런스: 캐싱 파라미터 상세
Prompt Caching Dashboard: 캐시 적중률 모니터링
Compaction 가이드: 압축이 캐시에 미치는 영향
Rate limits 가이드: 토큰 레이트 리밋 계산