프롬프트 캐싱

요청을 변경해도 기존 캐시 항목이 반드시 폐기되는 것은 아닙니다. 이후 요청에 같은 접두부가 있고, 조회 대상 중단점에서 일치하는 항목을 찾을 수 있는지가 중요합니다. 확인할 주요 설정은 다음과 같습니다.

GPT-5.6 이상에서 기본 캐시 수명은 30분이며, 캐시 쓰기 요율은 표준 비캐시 입력 토큰 요율의 1.25배입니다. Responses API에서는 일반 입력 요율의 2.5배로 최소 수명 12시간을 선택할 수 있습니다. 선택한 수명과 관계없이 이후 읽기 요율은 대부분의 해당 모델에서 일반 입력 요율의 0.1배이며, GPT-6.1 Sol과 GPT-6.1 Terra에서는 0.05배입니다.

읽기 요율이 0.1배이고 쓰기 수명이 30분이면 접두부를 한 번 쓰고 전체를 한 번 재사용하는 비용은 일반 입력 비용의 1.35배입니다. 캐싱 없이 두 번 처리하면 2배입니다. 같은 요율로 요청 10건에서 한 번 쓰고 전체를 아홉 번 읽으면 2.15배이며, 캐싱 없이 처리하면 10배입니다.

암시적 캐싱과 명시적 캐싱을 모두 지원합니다. 명시적 캐싱을 사용하면 캐시에 쓸 컨텍스트를 더 세밀하게 제어할 수 있습니다.

명시적 모드: 컨텍스트 관리 방식에 맞춰 캐시 중단점 위치를 직접 선택합니다.

• 개발자가 선택한 중단점만 사용하려면 prompt_cache_options.mode를 explicit으로 설정하세요. 원하는 각 중단점은 입력 메시지 내에서 지원되는 콘텐츠 블록에 prompt_cache_breakpoint: { "mode": "explicit" }를 추가해 표시하세요.
• 명시적 중단점을 지정하지 않으면 해당 요청에서는 프롬프트 캐싱을 사용하지 않으며 캐시 쓰기도 발생하지 않습니다.
• 명시적 전용 모드에서는 캐시 쓰기가 끝나는 위치를 선택할 수 있습니다. 마지막으로 선택한 중단점 이후의 내용에는 캐시 쓰기 요금 없이 비캐시 입력 토큰 요율이 적용됩니다. 자주 바뀌어 재사용할 가능성이 낮은 내용을 캐시에 쓰지 않아도 됩니다.
• 명시적 중단점을 여러 개 두면 변경 빈도가 서로 다른 접두부를 각각 보존할 수 있습니다. 요청 하나에서 캐시 쓰기는 최대 네 번까지 발생할 수 있습니다.
• additional_tools 입력 항목은 현재 prompt_cache_breakpoint를 지원하지 않습니다.

암시적 모드: 별도 설정 없이 OpenAI가 대부분의 사용 사례에 적합한 중단점 위치를 선택합니다.

• prompt_cache_options.mode가 implicit이면 OpenAI는 조건을 충족하는 가장 최근 메시지의 끝에 중단점을 둡니다. 대상 메시지는 다음과 같습니다.
  • 사용자 메시지
  • 연속된 도구 응답 중 마지막 응답
  • 처음에 연속해서 나오는 개발자 메시지 중 마지막 메시지
• 암시적 중단점을 유지하면서 명시적 중단점을 추가할 수 있습니다. 캐시 쓰기 슬롯 네 개 중 암시적 중단점이 하나를 사용하므로 명시적 캐시 쓰기에는 세 개를 사용할 수 있습니다.

암시적 캐싱만 지원합니다. OpenAI는 숨겨진 OpenAI 시스템 메시지의 시작부터 토큰 수를 세어 모델별 간격으로 암시적 중단점을 둡니다. 단, 숨겨진 컨텍스트의 끝부터 센 길이가 캐싱 가능한 최소 길이에 도달하거나 이를 넘는 중단점만 캐싱 대상입니다.

보고되는 cached_tokens 값은 마지막으로 일치한 중단점까지의 토큰 수에서 숨겨진 시스템 토큰 수를 뺀 뒤 128의 배수로 내림한 값입니다.

Responses API에서는 prompt_cache_options.ttl로 최소 캐시 수명을 선택하세요.

표의 요율은 쓰기에 적용되는 전체 요율이며 일반 입력 요금에 추가되지 않습니다. 캐시 읽기 요율은 두 수명에서 같습니다. OpenAI는 요청한 최소 수명보다 오래 항목을 보존할 수 있습니다. "12h"는 삭제 시한을 지정하거나 최대 데이터 보존 정책을 변경하지 않습니다.

요청 수준의 ttl은 암시적 중단점과 자체 ttl이 없는 명시적 중단점에 적용됩니다. 개별 명시적 중단점에 다른 수명을 적용하려면 prompt_cache_breakpoint.ttl을 설정하세요. 두 설정을 모두 생략하면 기본값인 "30m"이 적용됩니다. 지원되지 않는 값을 지정하면 400 invalid_request_error가 반환됩니다. 이 설정들은 이전 모델의 prompt_cache_retention 매개변수에 영향을 주지 않습니다.

한 요청에서 서로 다른 수명 사용하기

하루 동안 반복해서 사용하는 자료는 프롬프트 앞에 두고 해당 중단점의 수명을 "12h"로 설정하세요. 더 자주 바뀌는 세션 컨텍스트에는 "30m"을 사용하세요. 다음 예시에서는 요청의 기본 수명을 30분으로 설정하고 공통 접두부에만 별도 수명을 적용합니다. 명시적 전용 모드에서 현재 질문은 마지막 중단점 뒤에 있으므로 해당 내용에는 캐시 쓰기 요금이 발생하지 않습니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30{
  "model": "gpt-6.1-sol",
  "prompt_cache_options": { "mode": "explicit", "ttl": "30m" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "Shared instructions and reference material reused throughout the day...",
          "prompt_cache_breakpoint": { "mode": "explicit", "ttl": "12h" }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Session context reused over the next few minutes...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        },
        {
          "type": "input_text",
          "text": "The current question, which does not need a cache write..."
        }
      ]
    }
  ]
}

자리표시자 텍스트를 실제 내용으로 바꾸세요. 캐싱하려는 각 접두부는 모델의 캐싱 가능한 최소 길이를 충족해야 합니다.

쓰기 범위가 겹치거나 수명이 바뀌는 경우

중단점의 범위는 그 지점까지의 접두부 전체입니다. 한 요청에서 각 토큰에는 해당 토큰을 포함하는 쓰기 중 가장 긴 수명의 요율로 한 번만 요금이 부과됩니다. 뒤쪽 중단점에서 12시간 쓰기를 수행하면 그 접두부 안에서 앞서 선택한 중단점에도 12시간 수명이 적용됩니다.

다음 예시는 기존 캐시 접두부가 있다면 새 요청의 조회 대상 경계와 일치한다고 가정합니다.

유효한 30분 캐시의 수명을 12시간으로 늘리면 해당 토큰에 12시간 쓰기 요금이 새로 부과되며 이전 쓰기 요금은 차감되지 않습니다. 이미 유효한 12시간 캐시 항목에 포함된 부분은 계속 캐시 읽기로 처리됩니다.

30분 읽기가 발생하면 해당 캐시는 읽기 시점부터 최소 30분간 유효합니다. 유효한 12시간 캐시 항목을 읽으면 기존 만료 시점과 읽은 지 30분이 되는 시점 중 더 늦은 시점까지 유효합니다. 읽기 시점부터 12시간을 새로 계산하거나 쓰기 요금을 다시 부과하지 않습니다.

prompt_cache_retention을 사용하세요. 지원되는 값은 모델에 따라 다릅니다.

• in_memory: 사용하지 않는 항목은 보통 5~10분 정도 활성 상태로 유지되며, 최대 1시간까지 유지될 수 있습니다.
• 24h: 연장 보존을 사용하면 항목은 보통 약 30분간 사용 가능하며, 최대 24시간까지 보존될 수 있습니다.

보존 기본값과 데이터 비보관

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

• 데이터 비보관을 활성화하지 않은 조직의 기본값은 24h입니다.
• 데이터 비보관을 활성화한 조직의 기본값은 in_memory입니다.

값을 선택하기 전에 모델과 조직에서 사용할 수 있는 보존 정책을 확인하세요.

GPT-5.6 이전 모델에서는 재사용 가능한 접두부를 공유하는 요청에 일관된 prompt_cache_key를 사용하세요. 그러면 관련 요청을 같은 캐시로 라우팅하는 데 도움이 됩니다. 요청이 많은 그룹에서는 각 키를 사용하는 모든 접두부의 요청을 합해 분당 약 15건을 목표로 하세요. 트래픽이 더 많으면 같은 입력이 항상 같은 키에 배정되도록 일관된 규칙으로 여러 키에 분산하세요. 관련 요청에는 같은 prompt_cache_key를 사용해야 해당 캐시를 재사용할 수 있습니다. 키는 라우팅에 영향을 주지만 요청을 특정 머신에 고정하거나 캐시 적중을 보장하지는 않습니다.

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

키를 분리하면 각 고객이나 사용자의 캐시 토큰 사용량과 청구 내역을 더 쉽게 설명할 수 있습니다. 예를 들어 사용자가 후보 프롬프트를 보내고 캐시 적중 여부를 관찰해 다른 사용자가 같은 내용을 이전에 캐싱했는지 알아내려는 시도를 방지하는 데 도움이 됩니다. 키로 캐시 사용량 집계 분리하기를 참고하세요.

여러 턴에 걸쳐 대화하는 애플리케이션에서는 처음에 주어진 지침만 캐싱할 때보다 누적된 대화 기록을 재사용할 때 더 많은 입력 토큰을 절약할 수 있습니다. 이후 턴에서 공통 접두부 전체를 재사용할 수 있도록 이전 메시지와 도구 결과를 보존하세요.

• 접두부를 일정하게 유지하세요. 바뀌지 않는 개발자 지침과 공통 참고 자료를 맨 앞에 두세요. 개발자 지침이나 공통 자료에 타임스탬프, 사용자별 내용 등 동적 콘텐츠가 있다면 해당 내용은 끝에 두거나 이후 대화 메시지로 옮기세요.
• 대화 기록을 보존하세요. 이전 턴을 다시 작성하지 말고 새 메시지를 뒤에 추가하세요. 요약, 컨텍스트 압축, 컨텍스트 잘라내기로 접두부가 바뀌면 기존 캐시를 더 이상 재사용하지 못할 수 있습니다.
• 접두부를 다시 작성하지 않고 추론 수준을 변경하세요. GPT-6 모델에서는 configuration_update 입력 항목을 뒤에 추가하면 요청 수준의 reasoning.effort를 그대로 두고 응답 사이에 추론 수준을 변경할 수 있습니다. 이렇게 하면 원래 접두부가 보존되어 캐시를 재사용할 수 있습니다. 예시와 호환성 제한은 대화 도중 추론 수준 변경하기를 참고하세요.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26{
  "model": "gpt-6.1-sol",
  "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를 변경하면 숨겨진 시스템 지침의 내용이 바뀔 수 있으므로 원래 값을 유지하세요.

이후 응답에는 reasoning.effort의 가장 최근 업데이트에서 지정한 추론 수준이 적용됩니다. input 끝에 다음 항목을 추가하면 추론 수준이 high로 바뀝니다.

1
2
3
4{
  "type": "configuration_update",
  "reasoning": { "effort": "high" }
}

요청마다 애플리케이션에 필요한 도구가 다르다면 도구 정의는 그대로 두고 호출 가능한 도구만 변경하세요. 이렇게 하면 재사용 가능한 접두부가 유지됩니다.

• 도구 구성을 일정하게 유지하세요. 도구 정의, 순서, 스키마를 보존하세요.
• 특정 요청에서 도구 사용을 비활성화하세요. 도구 정의를 제거하는 대신 tool_choice를 "none"으로 설정하세요.
• 선택한 도구만 활성화하세요. allowed_tools를 사용하면 제공한 tools 목록을 그대로 유지하면서 호출 가능한 도구를 제한할 수 있습니다.
• 필요할 때 도구를 로드하세요. 도구 검색과 defer_loading: true를 함께 사용하면 여러 턴으로 이어지는 스레드의 초기 요청에서 도구 정의에 쓰이는 입력 토큰을 줄일 수 있습니다. 검색된 도구는 컨텍스트 끝에 추가되므로 앞부분의 재사용 가능한 내용이 유지됩니다.
• 도구 로드 기록을 보존하세요. 개발자 역할의 additional_tools 입력 항목을 사용해 애플리케이션 로직에 따라 스레드 진행 중에 도구를 추가하세요.

GPT-5.6 이상에서는 두 설정으로 캐시 중단점 위치를 결정합니다. prompt_cache_options.mode로 암시적 캐싱 또는 명시적 전용 캐싱을 선택하고, prompt_cache_breakpoint로 원하는 경계를 표시합니다.

• 중단점을 자동으로 배치하세요. 암시적 캐싱을 사용하면 조건을 충족하는 가장 최근 메시지의 끝에 중단점이 배치됩니다. 기존 컨텍스트 뒤에 내용을 추가하는 멀티턴 스레드에서 편리합니다.
• 필요한 위치에 중단점을 지정하세요. 바뀌지 않는 내용의 끝에 명시적 중단점을 두세요. 요청마다 달라지는 뒷부분을 불필요하게 캐시에 쓰지 않으려면 명시적 전용 모드를 사용하세요.

GPT-5.6 이상에서는 미리 알 수 있는 컨텍스트를 캐시에 준비해 두면 이후 요청에서 첫 토큰이 나올 때까지 걸리는 시간을 줄일 수 있습니다. 예를 들어 대화형 애플리케이션은 사용자가 첫 질문을 하기 전, 애플리케이션을 시작할 때 공통 지침, 도구 정의, 참고 자료를 미리 캐시에 넣을 수 있습니다.

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

1
2
3
4
5
6
7
8
9
10
11
12{
  "model": "gpt-6.1-sol",
  "input": [
    {
      "role": "developer",
      "content": "Your app's shared instructions and reference material..."
    }
  ],
  "prompt_cache_options": {
    "prewarm": true
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13{
  "model": "gpt-6.1-sol",
  "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_options를 지원하는 Responses API 모델에서는 자주 재사용하는 컨텍스트에 "30m"을 사용하세요. 긴 간격을 두고 재사용하는 고정 접두부에는 "12h"를 고려하세요. 더 높은 12시간 쓰기 요율을 적용한 비용과 30분 캐시가 만료된 뒤 접두부를 다시 쓰는 비용을 비교하세요. 중단점별로 수명을 지정하면 공통 자료에 세션별 컨텍스트보다 긴 수명을 적용할 수 있습니다. 예시와 과금 규칙은 캐시 수명을 참고하세요.

이전 모델에서는 모델과 데이터 보존 요구 사항이 허용한다면 prompt_cache_retention을 "24h"로 설정해 연장 보존을 사용하는 것이 좋습니다. 지원되는 설정과 기본값은 캐시 수명을 참고하세요.

여러 요청이 같은 개발자 지침과 도구 정의를 재사용하지만 공통 접두부가 모델의 캐싱 가능한 최소 길이에 못 미친다면, 접두부를 줄이거나 유용하면서 바뀌지 않는 지침, 예시, 참고 자료로 늘리는 방안을 고려하세요. 캐시 재사용으로 절약한 비용이 추가 입력 토큰과 캐시 쓰기 요금을 상쇄하는지 측정하고, 평가 결과와 동작이 안정적으로 유지되는지 확인하세요.

아래 차트는 짧은 접두부를 캐싱 없이 처리하는 비용이 캐싱 가능한 최소 토큰 수까지 접두부를 늘렸을 때보다 높아지는 구간을 보여 줍니다. GPT-5.6 이상의 30분 캐시 쓰기 요율을 사용합니다.

• 실제 캐시 성능을 측정하세요. usage.input_tokens_details.cached_tokens, usage.input_tokens_details.cache_write_tokens, 수명별 쓰기 토큰 수, 입력 토큰 수, 지연 시간, 실제 비용을 추적하세요. 사용자, 워크스페이스, 날짜 등 적절한 단위로 캐시 토큰 수와 입력 토큰 수를 각각 합산한 뒤, 총 캐시 토큰 수를 총 입력 토큰 수로 나누어 토큰 캐시 적중률을 구하세요.
• 입력 비용을 계산하세요. response.usage의 토큰 수와 모델의 100만 토큰당 요금을 사용하세요.
• 프롬프트 캐싱 대시보드를 사용하세요. 프롬프트 캐싱 대시보드에서 캐시 적중률을 모니터링하세요.

prompt_cache_options를 지원하는 Responses API 모델에서는 input_tokens_details.cache_write_tokens_details에 쓰기 토큰 수가 ttl_30m_tokens와 ttl_12h_tokens로 나뉘어 표시됩니다. 두 수에는 중복이 없으며 합계는 cache_write_tokens와 같습니다. 한쪽 값이 0이어도 두 필드가 모두 반환됩니다. cached_tokens에는 읽기로 과금된 토큰만 포함되며, 30분에서 12시간으로 수명을 늘린 토큰을 비롯해 쓰기로 과금된 토큰은 제외됩니다.

1
2
3
4
5
6
7
8
9
10
11
12
13{
  "usage": {
    "input_tokens": 12000,
    "input_tokens_details": {
      "cached_tokens": 4000,
      "cache_write_tokens": 7000,
      "cache_write_tokens_details": {
        "ttl_30m_tokens": 3000,
        "ttl_12h_tokens": 4000
      }
    }
  }
}

이 사용량 예시에서 일반 입력은 1,000토큰입니다(12000 - 4000 - 7000). 입력 비용을 구하려면 일반 입력 토큰 수에는 모델의 입력 단가를, cached_tokens에는 캐시 입력 단가를, ttl_30m_tokens에는 입력 단가의 1.25배를, ttl_12h_tokens에는 입력 단가의 2.5배를 곱하세요. 100만 토큰당 단가를 사용했다면 이 금액을 모두 더한 뒤 1,000,000으로 나누세요. 두 수명별 쓰기 토큰을 이미 반영했으므로 cache_write_tokens를 다시 더하지 마세요.

예를 들어 입력 단가가 100만 토큰당 1달러이고 캐시 입력 단가가 100만 토큰당 0.10달러이면 이 예시의 입력 비용은 (1000 + 4000 × 0.1 + 3000 × 1.25 + 4000 × 2.5) / 1000000 = $0.01515입니다. 계산할 때는 캐시 입력 요율을 비롯해 사용 중인 모델의 실제 요율을 적용하세요.

다음 헬퍼 함수는 모든 캐시 쓰기에 같은 요율 배수를 사용합니다. 모든 쓰기의 수명이 30분이면 1.25를, 모두 12시간이면 2.5를 사용하세요. 두 수명을 함께 사용하는 요청에서는 위에서 설명한 대로 수명별 쓰기 비용을 따로 계산하세요.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18function 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;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21from 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

1
2
3
4
5func calculateInputCost(usage responses.ResponseUsage, pricePerMillion, cacheInputMultiplier, cacheWriteMultiplier float64) float64 {
	ordinary := usage.InputTokens - usage.InputTokensDetails.CachedTokens - usage.InputTokensDetails.CacheWriteTokens
	weighted := float64(ordinary) + float64(usage.InputTokensDetails.CachedTokens)*cacheInputMultiplier + float64(usage.InputTokensDetails.CacheWriteTokens)*cacheWriteMultiplier
	return weighted * pricePerMillion / 1_000_000
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14import com.openai.models.responses.ResponseUsage;

static double calculateInputCost(
    ResponseUsage usage,
    double pricePerMillion,
    double cacheInputMultiplier,
    double cacheWriteMultiplier) {
  long cached = usage.inputTokensDetails().cachedTokens();
  long written = usage.inputTokensDetails().cacheWriteTokens();
  long ordinary = usage.inputTokens() - cached - written;
  return (ordinary + cached * cacheInputMultiplier + written * cacheWriteMultiplier)
      * pricePerMillion
      / 1_000_000;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17def 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

• 기존의 고정 접두부를 유지하세요.
• prompt_cache_key를 사용한다면 고객별 또는 사용자별 캐시 사용량이 계속 분리 집계되도록 기존 값을 유지하세요.
• prompt_cache_retention을 prompt_cache_options.ttl로 바꾸세요.
• 재사용할 접두부가 모델의 캐싱 가능한 최소 길이를 충족하는지 확인하세요.
• 기본 중단점의 범위에 요청마다 바뀌는 내용이 포함된다면 고정 접두부 뒤에 명시적 중단점을 추가하세요.
• 그 뒤의 내용을 캐시에 쓸 실익이 없다면 prompt_cache_options.mode: "explicit"을 사용하세요.
• 마이그레이션 전후의 cached_tokens, cache_write_tokens, 지연 시간, 총비용을 비교하세요.

사용자와 챗봇의 대화가 끝난 후 대화 내용에 사용자가 만족했다는 근거가 있는지 판단하는 단일 턴 LLM 평가자를 예로 들어 보겠습니다. 각 요청에서는 같은 평가 기준과 레이블이 지정된 퓨샷 예시를 사용해 서로 다른 대화를 평가합니다.

• 접두부 보존: 고정된 평가 기준과 예시를 맨 앞에 둡니다. 평가자의 판단 기준을 조정하는 데 도움이 되는 자료를 사용해 둘을 합친 길이가 모델의 캐싱 가능한 최소 길이를 조금 넘도록 합니다. 평가할 대화는 맨 뒤에 둡니다.
• 캐싱 모드와 중단점: 명시적 전용 캐싱을 활성화하고 고정된 평가 기준과 예시 뒤에 중단점을 둡니다. 평가할 사용자와 챗봇의 대화는 중단점 뒤에 있어 캐시에 기록되지 않으므로 재사용 가능성이 낮은 내용에 캐시 쓰기 요금이 발생하지 않습니다.

이 원칙을 적용한 배포 사례에서는 약 70%의 토큰 캐시 적중률을 기록했습니다. 이는 가능한 결과의 한 예입니다. 실제로 달성할 수 있는 최대 적중률은 컨텍스트와 애플리케이션 사용 패턴에 따라 달라집니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22{
  "model": "gpt-6.1-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%를 넘는 토큰 캐시 적중률을 기록했습니다. 이는 가능한 결과의 한 예입니다. 실제로 달성할 수 있는 최대 적중률은 컨텍스트와 애플리케이션 사용 패턴에 따라 달라집니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41{
  "model": "gpt-6.1-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...?" }
  ]
}

이전 모델에서 GPT-5.6 이상으로 마이그레이션할 때는 암시적 캐싱 방식이 달라져 이 문제가 특히 자주 발생합니다. 요청들이 긴 접두부를 공유하더라도 뒷부분이 서로 다르면 첫 요청 전체를 암시적 캐싱만으로 저장해도 그보다 짧은 공통 접두부를 재사용할 수는 없습니다.

각 요청에서 고정된 개발자 메시지 뒤에 매번 달라지는 사용자 메시지가 오는 경우를 생각해 보세요. 이 요청은 달라지는 내용까지 캐시에 씁니다. 다음 요청에서 그 내용이 바뀌면 캐시에 저장한 긴 접두부와 일치하지 않으며, 고정된 내용 뒤에는 별도의 중단점이 없습니다.

1
2
3
4
5
6
7
8
9
10{
  "model": "gpt-6.1-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..." }
  ]
}

이 문제를 해결하려면 두 요청 모두에서 고정된 내용 뒤에 명시적 중단점을 두세요. 첫 요청이 재사용 가능한 접두부를 캐시에 쓰면 다음 요청에서는 동적 내용이 바뀌어도 해당 접두부를 재사용할 수 있습니다. 다음 예시는 동적 내용을 캐시에 쓰지 않도록 명시적 전용 모드를 사용합니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17{
  "model": "gpt-6.1-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는 자체 입력에 있는 명시적 중단점만 확인합니다. 따라서 요청 2의 명시적 중단점 중 하나가 요청 1에서 캐싱한 끝 지점과 일치하지 않는 한 요청 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가 있고, 후속 요청 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] ▼

대화 구조가 허용한다면 원래 메시지를 유지하고 새 메시지를 뒤에 추가하세요. 그렇지 않다면 재사용할 텍스트를 별도의 콘텐츠 블록에 넣고 두 요청 모두에서 해당 블록 뒤에 명시적 중단점을 두세요.

암시적 모드에서는 처음에 연속해서 나오는 개발자 메시지 묶음 이후의 개발자 메시지는 자동 캐시 조회 경계가 되지 않습니다. 재사용할 개발자 메시지 끝에 명시적 중단점을 추가하고 이후 요청에서도 유지하세요. 그러면 OpenAI가 일치하는 캐시 접두부를 확인할 수 있습니다.

한 모델에서 캐싱할 수 있는 접두부가 다른 모델에서는 너무 짧을 수 있습니다. 모델별 비교를 확인하고 실제로 사용하는 모델과 설정으로 재사용할 접두부의 길이를 측정하세요. 모델을 변경할 때는 이전 모델의 기준이 그대로 적용된다고 가정하지 말고 다시 확인하세요.

컨텍스트 압축은 이전 대화 컨텍스트를 더 짧은 표현으로 대체합니다. 이 과정에서 접두부가 바뀔 수 있으므로 논리적으로 같은 대화라도 압축 후 첫 요청에서는 기존 캐시를 재사용하는 범위가 줄어들 수 있습니다.

가능하면 재사용할 지침과 참고 자료는 그대로 유지하고 이후 턴에서 압축된 컨텍스트에 새 내용을 추가하세요. 압축 전후의 총 입력 비용을 비교하세요. 캐시 적중률이 떨어져도 입력 토큰 수가 줄어 비용을 절약할 수 있습니다.

아니요. 프롬프트 캐싱은 모델이 출력 토큰을 생성하는 방식을 바꾸지 않습니다. 모델은 캐시된 접두부를 사용해 새 응답을 생성하므로 같은 요청을 보내도 출력이 같다고 보장할 수 없습니다.

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

예. 캐시된 입력 토큰도 분당 토큰 한도에 포함됩니다. 프롬프트 캐싱은 요청 한도를 계산하는 방식을 바꾸지 않습니다.