프롬프트 캐시 진단

프롬프트 캐시 진단 (Prompt cache diagnostics)

출처: 문서

프롬프트 캐시 진단은 요청이 예상보다 적은 토큰을 재사용한 이유를 설명하는 데 도움을 줘요. 요청을 이전 응답과 비교해 재사용을 막은 모델, 도구, 설정, 또는 입력의 변경을 식별해요.

진단은 Responses API에서 GPT-5.6 및 이후의 지원되는 모델에 사용할 수 있어요. 개별 요청을 조사할 때 사용하고, 애플리케이션 전반의 캐시 성능을 모니터링하려면 Prompt Caching Dashboard를 사용해요.

작동 방식

프롬프트 캐시 진단은 현재 요청을 이전 응답과 비교해서, 예상했던 프롬프트 접두부(prefix)가 재사용되지 않은 이유를 설명하는 데 도움을 줘요. 접두부는 프롬프트 시작 부분의 콘텐츠예요. 재사용에는 정확한 접두부 일치와 호환되는 요청 설정(모델, 서비스 티어, 도구 포함)이 필요해요.

기준 응답(baseline response)을 선택해요. 현재 요청이 재사용할 것으로 예상되는 접두부를 가진, 같은 조직의 최근 완료 응답(예: 직전 대화 턴)을 사용해요.
비교를 요청해요. prompt_cache_options.comparison_response_id를 기준 응답의 id로 설정해요.
결과를 읽어요. 현재 응답에서 prompt_cache_diagnostics를 확인해요. 진단이 캐시 미스를 식별하면 조사에 도움이 되는 이유가 포함돼요. 실제 캐시 재사용을 측정하려면 usage.input_tokens_details.cached_tokens를 사용해요.

comparison_response_id를 설정하는 것은 진단만 요청하는 것이에요. 이전 대화를 로드하거나 캐싱 동작을 바꾸지 않아요. 현재 요청은 다른 요청의 일치하는 캐시 항목을 여전히 재사용할 수 있어요.

사용 예시

다음 예시는 같은 모델, 지침, 입력으로 두 요청을 보내지만 function 도구의 이름을 get_time에서 get_date로 바꿔요. 두 번째 요청은 첫 번째 요청과 비교해 캐시 재사용을 확인해요.

support-policy.txt에 사용자 자체 정책 문서를 사용해요. 재사용 가능한 접두부는 모델의 최소 캐시 가능 길이를 충족해야 하며, GPT-5.6 이후에서는 1,024 토큰이에요.

응답 간 프롬프트 캐시 재사용 비교하기

from pathlib import Path

from openai import OpenAI

client = OpenAI()
policy = Path("support-policy.txt").read_text()  # At least 1,024 tokens.

first = client.responses.create(
    model="gpt-6-astra",
    instructions=policy,
    input="Reply with exactly OK.",
    tools=[{"type": "function", "name": "get_time"}],
)

second = client.responses.create(
    model="gpt-6-astra",
    instructions=policy,
    input="Reply with exactly OK.",
    tools=[{"type": "function", "name": "get_date"}],
    prompt_cache_options={"comparison_response_id": first.id},
)

diagnostics = second.prompt_cache_diagnostics
if diagnostics is not None and diagnostics.type == "cache_miss":
    print(diagnostics.reason)
    print(diagnostics.comparison_reusable_tokens)
    print(diagnostics.cache_missed_tokens)

도구 변경이 미스를 유발하면 결과는 다음과 같이 보일 수 있어요. 토큰 수는 입력에 따라 달라져요.

{
  "prompt_cache_diagnostics": {
    "type": "cache_miss",
    "reason": "tools_changed",
    "comparison_reusable_tokens": 5629,
    "cache_missed_tokens": 5629
  }
}

재사용을 보존하려면 요청 간에 도구 정의와 순서를 변경하지 않은 채 유지해요. Append-only 업데이트로 도구 관리하기를 참고해요.

다중 턴 대화

연속된 턴을 비교하려면 각 완료된 응답의 id를 저장하고, 다음 요청의 prompt_cache_options에서 comparison_response_id로 전달해요. 첫 번째 턴에서는 비교 ID를 생략해요.

수정을 테스트할 때는 비교 ID를 기준 응답으로 유지해요.

스트리밍

stream=True일 때는 response.completed 이벤트의 event.response에서 prompt_cache_diagnostics를 읽어요.

응답 이해하기

prompt_cache_diagnostics.type을 읽어 비교 결과를 판단해요.

유형	의미	해야 할 일
`cache_hit`	비교에 대해 캐시 미스가 감지되지 않음.	`usage.input_tokens_details.cached_tokens`를 확인해 실제 재사용을 측정해요.
`cache_miss`	차이가 예상 접두부의 재사용을 막았음. 결과에 `reason`과 `cache_missed_tokens`가 포함됨. `comparison_reusable_tokens`도 포함될 수 있음.	캐시 미스 고치기에서 이유와 권장 수정 사항을 찾아요.
`comparison_response_not_found`	비교 응답에 대해 사용 가능한 진단 레코드가 없음. 누락되었거나 만료되었을 수 있음.	같은 조직의 다른 최근 완료 응답을 선택해요.
`unavailable`	비교가 결정적인 결과를 만들 수 없거나, 모델이 진단을 지원하지 않음.	모델 지원을 확인하고 다른 최근 비교를 시도해요. 응답을 정상적으로 사용해도 됨.

토큰 수 해석하기

cache_hit은 비교에 대해 캐시 미스가 감지되지 않았음을 의미해요. 새 입력은 여전히 처리가 필요할 수 있어요. 예를 들어 2,500 입력 토큰 요청이 비교 응답의 2,000 토큰 접두부를 재사용하고 500개의 새 토큰을 처리하면 cache_hit을 보고할 수 있어요.

cache_miss의 경우:

comparison_reusable_tokens은, 존재할 때, 비교 응답의 재사용 가능한 접두부의 원시 토큰 수예요.
cache_missed_tokens는 그 중 얼마나 많은 토큰이 재사용되지 않았는지 추정해요.

이 진단 수는 사용량 수와 다를 수 있어요. 보고되는 캐시 재사용과 청구를 측정하려면 현재 응답의 usage 필드를 사용해요.

캐시 미스 고치기

prompt_cache_diagnostics.reason을 사용해 캐시 미스의 원인과 아래 표의 권장 수정 사항을 찾아요.

모델 전환이나 대화 압축 같은 일부 변경은 의도적인 것일 수 있어요. 캐시 재사용을 줄이더라도 유지하기로 선택할 수 있어요.

이유	무엇이 바뀌었나	재사용 개선 방법
`model_changed`	라우팅, A/B 테스트, 또는 폴백으로 다른 모델이 요청을 처리함.	의도하지 않은 전환을 위해 모델 선택을 확인해요. 캐시된 접두부를 공유하려는 요청에는 같은 모델을 사용해요. 캐시에 영향을 주는 설정 참고.
`prompt_cache_key_changed`	요청 사이에 공급된 키가 바뀜. 물리적 캐시 미스 없이 응답 `usage`에서 캐시 미스로 보고될 수 있음.	애플리케이션이 고객이나 사용자별로 분리된 캐시 회계가 필요하지 않다면 `prompt_cache_key`를 생략해요. 키를 사용한다면 각 그룹 안에서 안정적인 키를 유지해요. 캐시 키로 분리 회계하기 참고.
`service_tier_changed`	요청을 처리하는 데 사용된 서비스 티어가 바뀜.	접두부를 공유할 것으로 예상되는 요청에 대해 서비스 티어를 일관되게 유지해요. 반환된 `service_tier`를 확인해요. 요청된 값과 다를 수 있어요. 지원 값과 동작은 `service_tier` 참고.
`tools_changed`	도구가 추가, 제거, 또는 재배열되었거나 설명, 스키마, 구성이 바뀜.	도구 정의와 순서를 안정적으로 유지해요. 공급된 도구 목록을 바꾸지 않고 도구를 비활성화하려면 `tool_choice: "none"`을, 실행할 수 있는 도구를 제한하려면 `allowed_tools`를 사용해요. Append-only 업데이트로 도구 관리하기 참고.
`text_format_changed`	출력 형식이나 그 스키마가 바뀜.	필수 출력 구조가 그대로일 때 `text.format`과 스키마를 일관되게 유지해요. Structured Outputs 참고.
`reasoning_effort_changed`	추론 노력이 바뀜.	접두부를 공유하려는 요청에서 `reasoning.effort`를 일관되게 유지해요. 캐시에 영향을 주는 설정 참고.
`verbosity_changed`	응답 verbosity가 바뀜.	접두부를 공유하려는 요청에서 `text.verbosity`를 일관되게 유지해요. 캐시에 영향을 주는 설정 참고.
`context_compacted`	압축이 이전 대화 콘텐츠를 대체함.	안정적인 지침을 보존하고 이후 턴이 압축된 컨텍스트 위에 구축되게 해요. 총 입력 비용을 비교해요: 캐시 재사용이 낮아도 입력 토큰이 적으면 비용을 절약할 수 있어요. Compaction 참고.
`input_changed`	지침에 타임스탬프나 요청 ID가 포함되거나 이전 메시지가 편집·재배열·제거되는 등 이전 입력이 바뀜.	변경되는 콘텐츠를 재사용 가능한 접두부와 그 캐시 중단점 뒤로 옮겨요. 이전 메시지와 도구 결과를 보존하고 새 턴을 추가해요. 대화 기록 보존하기 참고.

개선 확인하기

변경 후:

다른 대표적인 요청을 보내고 의도한 기준 응답과 비교해요.
남은 차이가 있는지 진단 결과를 확인해요.
여러 요청에서 cached_tokens, cache_write_tokens, 총 비용을 비교해요.

사용량 지표와 비용 계산은 캐시 성능 모니터링을 참고해요.

가격과 비율 한도

프롬프트 캐시 진단에는 추가 비용이 없고 비율 한도에 별도로 집계되지 않아요. Responses API에 대한 추가 기준 또는 재시도 요청은 정상적으로 청구되며 비율 한도에 집계돼요.

제로 데이터 보존 (Zero Data Retention)

프롬프트 캐시 진단은 Zero Data Retention과 호환돼요. OpenAI는 이 기능에 대해 원시 프롬프트나 모델 출력을 저장하지 않아요. 진단 레코드에는 구성 메타데이터, 토큰 수 추정, 캐시 민감 콘텐츠를 비교하는 데 사용되는 해시가 포함돼요. 이 레코드는 조직 범위로 지정되고, 짧은 기간 후 만료되며, 프롬프트 캐시 히트나 미스를 설명하는 데만 사용돼요.

comparison_response_id를 설정한다고 해서 이전 응답의 콘텐츠를 검색하거나 보존하지는 않아요. OpenAI의 데이터 제어는 Your data를 참고해요.

제한 사항

진단은 Responses API에서 GPT-5.6 및 이후의 지원되는 모델에 제공돼요.
진단 레코드는 짧은 기간 후 만료돼요. 만료된 레코드는 응답이 API를 통해 여전히 사용 가능해도 comparison_response_not_found를 반환해요.
진단은 첫 번째로 분류된 이유를 보고해요. 이를 해결한 다음 다른 원인이 있는지 비교를 반복해요.
진단은 best-effort이며 모든 미스를 분류하지 못할 수 있어요. unavailable 결과는 히트나 미스를 나타내지 않으며, 비교가 준비되지 않았을 때 반환돼요.
진단은 요청을 차단하거나 실패시키지 않고, 모델이 출력을 생성하는 방식을 바꾸지 않아요.