공식 발표일: 2026년 9월 8일 · 확인일: 2026년 9월 9일
OpenAI가 Responses API에 Prompt Cache Diagnostics를 정식 공개했습니다. 긴 시스템 지시문, 도구 정의, 예시 문서가 반복되는 AI 에이전트는 프롬프트 캐시가 제대로 재사용되면 입력 비용과 처리 부담을 줄일 수 있습니다. 문제는 캐시 적중률이 갑자기 떨어져도 기존에는 모델 변경, 도구 스키마 수정, 키 변경, 대화 압축 중 무엇이 원인인지 찾기 어려웠다는 점입니다. 이번 기능은 현재 응답과 이전의 완료된 응답을 비교해 캐시 재사용을 막은 첫 번째 분류 원인과 놓친 토큰 규모를 알려줍니다.
지원 범위는 GPT-5.6 이상 호환 모델의 Responses API입니다. 진단 자체에는 추가 요금이 없지만 추가 기준 요청과 재시도는 정상 과금됩니다. 이 글은 직접 테스트가 아니며, 공식 OpenAI 문서와 독자가 재현할 측정 방법을 구분해 정리합니다.
왜 Prompt Cache Diagnostics가 중요한가
프롬프트 캐시는 답변을 저장하는 기능이 아니라 여러 요청 앞부분의 반복 토큰을 재사용하는 방식입니다. 고객 지원 정책, 코드 저장소 안내, 도구 정의, 평가 루브릭처럼 길고 안정적인 내용이 앞에 놓일수록 효과가 커질 수 있습니다.
요청 ID나 현재 시간이 고정 지시문 안에 들어가거나 도구 순서, 모델, 서비스 등급, 추론 강도가 바뀌면 기대한 접두부가 재사용되지 않을 수 있습니다. cached_tokens만으로는 원인을 알기 어렵지만 새 진단 필드는 먼저 확인할 차이를 알려줍니다.
| 기존에 보던 값 | 새 진단이 더해 주는 정보 | 운영 질문 |
|---|---|---|
cached_tokens |
실제 재사용된 입력 토큰 | 이번 요청에서 캐시를 얼마나 썼나? |
cache_write_tokens |
새로 캐시에 쓴 토큰 | 어느 정도의 문맥을 다음 요청용으로 기록했나? |
prompt_cache_diagnostics.reason |
첫 번째로 분류된 미스 원인 | 모델·키·도구·입력 중 무엇이 달라졌나? |
comparison_reusable_tokens |
기준 응답에서 재사용 가능했던 토큰 추정 | 비교 대상으로 삼은 접두부 규모는 얼마인가? |
cache_missed_tokens |
재사용되지 못한 기준 토큰 추정 | 이번 차이의 잠재적 비용 영향은 어느 정도인가? |
작동 방식: previous_response_id와 비교 ID를 구분하자
진단을 요청하려면 현재 요청의 prompt_cache_options.comparison_response_id에 최근 완료된 기준 응답 ID를 넣습니다. 이 ID는 현재 요청이 같은 접두부를 재사용할 것으로 기대했던 비교 대상입니다. 비교 응답은 같은 조직에서 생성된 최근의 완료 응답이어야 하며, 진단 기록은 짧은 기간만 유지됩니다.
자주 혼동하는 값이 previous_response_id입니다. 이것은 이전 대화 문맥을 현재 요청에 이어 주는 값이지, 캐시 진단을 요청하는 값이 아닙니다. 반대로 comparison_response_id는 비교 기준만 정하며 그 응답의 대화 내용을 불러오지 않습니다. 멀티턴 대화에서는 두 값에 같은 응답 ID를 넣을 수 있지만 역할은 다릅니다. 애플리케이션이 대화 기록을 직접 관리한다면 전체 기록을 input으로 보내고 비교 ID만 지정할 수도 있습니다.
| 필드 | 목적 | 하지 않는 일 |
|---|---|---|
previous_response_id |
이전 대화 상태를 이어서 사용 | 캐시 미스 원인을 분석하지 않음 |
comparison_response_id |
진단 기준 응답을 선택 | 이전 응답 내용을 불러오거나 캐시 사용 대상을 고정하지 않음 |
prompt_cache_key |
유사한 접두부 요청의 라우팅을 돕는 안정적 키 | 특정 서버에 고정하거나 캐시 적중을 보장하지 않음 |
GPT-5.6 이상에서 캐시 가능한 공통 접두부는 최소 1,024토큰을 충족해야 합니다. 짧은 지시문에 진단만 붙였는데 계속 적중이 없으면 먼저 입력 길이와 실제 공통 구간을 확인해야 합니다. 진단 기록이 만료된 경우에는 응답 자체가 API에서 조회되더라도 comparison_response_not_found가 나올 수 있습니다.
실제 성능과 비용: 확인된 사실, 계산 예시, 아직 모르는 것
이 기능이 모델의 정답률이나 생성 품질을 높인다는 공식 벤치마크는 공개되지 않았습니다. 진단은 요청의 생성 방식을 바꾸지 않으며, 비교가 준비되지 않아도 본 요청을 막거나 실패시키지 않습니다. OpenAI 문서는 진단 결과가 최선 노력 방식이며 모든 캐시 미스를 분류하지 못할 수 있다고 설명합니다. 따라서 “진단을 켜면 응답이 몇 퍼센트 빨라진다”는 수치를 만들면 안 됩니다.
| 항목 | 공식 확인 내용 | 측정 주체·조건 | 해석 한계 |
|---|---|---|---|
| 지원 모델 | GPT-5.6 이상 지원 모델 | OpenAI 문서, Responses API | 모든 모델·모든 API에 적용되는 것은 아님 |
| 최소 캐시 길이 | GPT-5.6 이상 1,024토큰 | OpenAI 프롬프트 캐싱 가이드 | 길이만 충족한다고 적중이 보장되지는 않음 |
| 진단 요금 | 추가 비용 없음, 별도 비율 제한 없음 | OpenAI 진단 문서 | 추가 기준 요청·재시도는 정상 과금 |
| 진단 신뢰성 | 최선 노력 방식, 첫 분류 원인만 반환 | OpenAI 진단 문서 | unavailable은 적중·미스를 뜻하지 않음 |
| 지연시간 개선 | 진단 기능 자체의 공개 수치 없음 | 공식 독립 평가 미확인 | 직접 워크로드로 p50·p95 측정 필요 |
비용 효과는 공식 단가의 상대 배수로 계산할 수 있습니다. OpenAI 가이드의 계산 예시는 일반 입력을 1로 둘 때 캐시 읽기를 0.1, 캐시 쓰기를 1.25로 반영합니다. 공통 접두부가 12,000토큰이고 총 10회 요청에서 첫 요청이 전부 캐시에 기록되고 다음 9회가 전부 재사용된다고 가정해 보겠습니다. 캐시가 없으면 입력 토큰 등가 비용은 12,000×10=120,000입니다. 캐시를 쓰면 12,000×1.25 + 12,000×0.1×9 = 25,800이므로 이 가정에서는 공통 접두부 입력 비용이 약 78.5% 줄어듭니다.
이는 실측이나 보장된 절감률이 아니라 완전 적중과 같은 처리 등급을 가정한 계산입니다. 실제 총비용에는 새 입력, 출력, 도구, 미스와 재시도를 포함해야 합니다. 모델·처리 등급·컨텍스트 길이에 따라 단가도 달라지므로 사용량과 전체 비용, p50·p95 지연시간을 함께 봅니다.
Python으로 첫 캐시 진단 요청 보내기
아래는 두 번째 요청이 첫 번째 응답을 대화와 진단의 기준으로 모두 사용하는 최소 예시입니다. API 키는 코드에 넣지 말고 OPENAI_API_KEY 환경 변수로 관리합니다. 고정 지시문은 실제로 1,024토큰 이상의 유용한 정책·예시 문서라고 가정합니다.
from openai import OpenAI
client = OpenAI()
policy = open("support-policy.txt", encoding="utf-8").read()
first = client.responses.create(
model="gpt-5.6",
instructions=policy,
input="환불 규정을 세 문장으로 요약해 주세요.",
prompt_cache_key="support-policy:v3",
)
second = client.responses.create(
model="gpt-5.6",
instructions=policy,
previous_response_id=first.id,
input="세일 상품에도 같은 규정이 적용되나요?",
prompt_cache_key="support-policy:v3",
prompt_cache_options={
"comparison_response_id": first.id,
},
)
diag = second.prompt_cache_diagnostics
print(diag)
print(second.usage.input_tokens_details.cached_tokens)스트리밍 요청에서는 완료 이벤트인 response.completed의 event.response.prompt_cache_diagnostics를 읽습니다. 첫 턴에는 비교할 응답이 없으므로 비교 ID를 빼고, 이후 턴부터 직전의 완료 응답 ID를 보관해 넘기면 됩니다. 고장 수정 전후를 비교할 때는 같은 기준 ID를 유지해야 변화의 효과를 보기 쉽습니다.
결과 유형과 캐시 미스 원인 8가지
prompt_cache_diagnostics.type은 네 가지 결과를 반환할 수 있습니다. cache_hit이면 비교에서 미스가 감지되지 않았다는 뜻이지만, 요청 전체가 캐시됐다는 뜻은 아닙니다. 실제 재사용량은 반드시 사용량 필드의 cached_tokens로 확인합니다. cache_miss에는 원인과 놓친 토큰 추정값이 따라올 수 있습니다. comparison_response_not_found는 기준 기록이 없거나 만료된 경우이고, unavailable은 결론을 낼 수 없거나 모델이 지원하지 않는 경우입니다.
| 원인 코드 | 주요 변화 | 우선 해결법 |
|---|---|---|
model_changed |
라우팅·A/B 테스트·폴백으로 모델이 달라짐 | 공통 접두부를 공유할 요청의 모델을 고정 |
prompt_cache_key_changed |
키에 요청 ID·시간을 넣어 매번 달라짐 | 문맥 버전 단위의 안정적인 키 사용 |
service_tier_changed |
실제 처리 등급이 변경됨 | 응답의 반환 등급까지 기록해 일관성 확인 |
tools_changed |
도구 추가·삭제·순서·설명·스키마가 변경됨 | 도구 목록을 안정적으로 유지하고 실행 제한만 조정 |
text_format_changed |
출력 형식이나 JSON 스키마가 변경됨 | 같은 업무에서는 스키마를 버전 고정 |
reasoning_effort_changed |
추론 강도가 달라짐 | 공유할 흐름에서는 같은 강도 유지 |
verbosity_changed |
응답 자세함 설정이 달라짐 | 고정 접두부 요청의 verbosity 통일 |
context_compacted·input_changed |
대화가 압축되거나 앞부분 입력이 수정됨 | 고정 문맥을 앞에 두고 새 내용은 뒤에 추가 |
진단은 첫 번째 분류 원인만 보고하므로 하나를 고친 뒤 같은 기준으로 다시 확인합니다. 대화 압축처럼 의도적인 변화는 미스가 생겨도 전체 입력과 총비용을 더 낮출 수 있습니다.
운영에 적용하는 단계별 방법
- 기준 워크로드를 고릅니다. 1,024토큰 이상의 고정 지시문을 반복하는 흐름을 선택합니다.
- 고정 부분을 앞에 둡니다. 정책·도구·예시를 먼저, 질문·시간·요청 ID는 뒤에 둡니다.
- 키 정책을 정합니다.
support-policy:v3처럼 버전을 나타내는 안정적 키를 씁니다. - 기준 응답 ID를 저장합니다. 최근 완료된 응답과 상태·시각을 함께 보관합니다.
- 진단과 사용량을 함께 기록합니다. 원인, 토큰, 모델, 등급, 지연시간을 한 로그에 남깁니다.
- 한 번에 한 원인만 고칩니다. 여러 설정을 동시에 바꾸지 않습니다.
- 여러 요청으로 확인합니다. 최소 30회의 비용, p50·p95, 미스율을 봅니다.
- 배포 전후를 비교합니다. 프롬프트와 도구 스키마 버전을 함께 기록합니다.
직접 재현하는 성능 테스트 절차
독립 공개 평가는 아직 확인되지 않았습니다. 다음 절차는 답변 품질이 아니라 캐시 미스 원인과 비용·지연시간 회귀를 찾는 능력을 확인합니다.
- 민감정보를 제거한 대표 요청 30개와 2,000~12,000토큰의 고정 접두부를 준비합니다.
- 모델, 추론 강도, verbosity, 도구 순서, 처리 등급, 지역, 동시성을 고정합니다.
- 진단을 끈 기준군과 같은 요청에 진단을 켠 비교군을 각각 3회 이상 반복합니다.
- 의도적으로 키, 도구 순서, 모델, 입력 앞부분을 하나씩 바꿔 올바른 원인 코드가 나오는지 확인합니다.
- 각 요청의
cached_tokens,cache_write_tokens, type, reason, p50·p95 지연시간, 전체 비용을 저장합니다. - 원인을 수정한 뒤 같은 비교 응답 ID로 다시 요청하고 놓친 토큰이 줄었는지 확인합니다.
unavailable과 만료 응답 비율을 별도로 집계해 진단 가능성 자체도 측정합니다.- 최종적으로 월간 입력 비용 절감액과 장애 분석 시간을 계산해 운영 가치가 있는지 판단합니다.
| 평가 지표 | 측정 방법 | 주의점 |
|---|---|---|
| 캐시 재사용률 | cached tokens ÷ 전체 입력 토큰 | 새 사용자 입력은 원래 캐시 대상이 아닐 수 있음 |
| 원인 분류 재현율 | 의도한 변화 중 기대 코드가 나온 비율 | 기능은 최선 노력 방식임 |
| 지연시간 | 같은 조건의 p50·p95 | 네트워크와 동시성 영향을 통제 |
| 총 입력 비용 | 일반·캐시 읽기·캐시 쓰기 토큰별 계산 | 출력과 도구 비용도 별도 합산 |
| 분석 시간 | 미스 감지부터 원인 확인까지 걸린 시간 | 팀의 기존 로그 수준과 함께 비교 |
배포 전 체크리스트
- GPT-5.6 이상 지원 모델과 Responses API를 사용하고 있는가?
- 공통 접두부가 최소 1,024토큰을 충족하는가?
- 변하는 시간·사용자 질문·요청 ID를 고정 지시문 뒤에 배치했는가?
prompt_cache_key가 요청마다 무작위로 바뀌지 않는가?- 모델, 서비스 등급, 추론 강도, verbosity, 도구 순서를 로그에 남기는가?
- 최근 완료된 같은 조직의 응답을 비교 기준으로 사용하는가?
cache_hit만 믿지 않고 실제cached_tokens를 확인하는가?- 추가 기준 요청과 재시도의 정상 비용을 예산에 포함했는가?
- 진단 기록의 짧은 보관 기간을 장애 대응에 반영했는가?
자주 생기는 실패와 해결법
comparison_response_not_found가 계속 나온다
기준 응답이 오래됐거나 완료되지 않았거나 다른 조직에서 만들어졌을 수 있습니다. 최근에 정상 완료된 같은 조직의 응답을 선택하고, ID 저장 시점과 상태를 함께 기록합니다. 응답 본문이 조회된다고 진단 기록도 남아 있다는 뜻은 아닙니다.
cache_hit인데 cached_tokens가 기대보다 작다
cache_hit은 비교 대상 접두부에서 미스가 감지되지 않았다는 뜻이지 전체 입력이 재사용됐다는 뜻은 아닙니다. 예를 들어 2,500토큰 요청에서 기준의 2,000토큰만 재사용되고 500토큰은 새 입력일 수 있습니다. 실제 과금 분석은 사용량 필드로 합니다.
원인을 고쳤는데 또 cache_miss가 나온다
진단은 첫 분류 원인만 알려줍니다. 키 변경을 고친 다음에는 도구 순서나 추론 강도 변화가 다음 원인으로 나타날 수 있습니다. 한 항목씩 수정하고 같은 기준으로 반복 비교합니다.
prompt_cache_key를 같게 했는데 적중하지 않는다
키는 관련 요청의 라우팅을 도울 뿐 캐시 적중을 보장하지 않습니다. 앞부분 토큰, 모델, 도구, 스키마, 서비스 등급을 함께 확인합니다. 트래픽이 다른 머신으로 넘치는 상황에서는 같은 키여도 첫 요청이 미스가 될 수 있습니다.
진단을 켠 뒤 응답이 실패할까 걱정된다
진단은 본 요청을 막지 않습니다. 비교가 준비되지 않으면 unavailable일 수 있으므로 진단 필드가 없어도 정상 응답을 처리합니다.
자주 묻는 질문
Prompt Cache Diagnostics는 Chat Completions API에서도 되나요?
공식 공개 범위는 GPT-5.6 이상 지원 모델의 Responses API입니다. 다른 API에서 같은 필드가 동작한다고 가정하지 말고 공식 변경 로그와 API 참조를 확인해야 합니다.
진단을 켜면 추가 요금이 붙나요?
진단 자체는 추가 비용이 없고 별도 비율 제한도 사용하지 않습니다. 다만 비교를 위해 새 기준 요청을 만들거나 수정 확인용 요청을 반복하면 그 요청은 일반 API 단가와 제한을 적용받습니다.
comparison_response_id가 이전 내용을 다시 불러오나요?
아닙니다. 비교 기준만 선택하며 이전 응답의 대화 내용을 불러오거나 저장하지 않습니다. 대화 연결이 필요하면 previous_response_id를 별도로 사용합니다.
Zero Data Retention 조직에서도 사용할 수 있나요?
공식 문서상 호환됩니다. 이 기능을 위해 원문 프롬프트나 모델 출력은 저장하지 않고, 구성 메타데이터·토큰 추정·캐시 민감 콘텐츠 비교용 해시가 조직 범위에서 짧은 기간 유지됩니다.
이 글의 비용 절감률은 직접 테스트 결과인가요?
아닙니다. 78.5% 예시는 공식 가이드의 캐시 읽기·쓰기 배수에 12,000토큰, 10회 요청, 완전 적중이라는 가정을 적용한 계산입니다. 실제 서비스의 지연시간과 비용은 제시한 재현 절차로 측정해야 합니다.
공식 확인 자료
- OpenAI API 변경 로그 — Prompt Cache Diagnostics GA 발표
- OpenAI 공식 Prompt Cache Diagnostics 가이드 — 필드·원인 코드·한계
- OpenAI 공식 Prompt Caching 가이드 — 캐시 동작·최적화·비용 계산
- OpenAI Responses API 요청 참조 — prompt_cache_options와 응답 필드
- OpenAI API 공식 가격표 — 입력·캐시 읽기·캐시 쓰기 단가
- OpenAI 공식 대화 상태 가이드 — previous_response_id 사용법
Prompt Cache Diagnostics는 자동 적중 기능이 아니라 재사용이 끊긴 이유를 추적하는 운영 도구입니다. 같은 모델과 설정, 안정적인 키, 변하지 않는 접두부를 유지하고 진단과 사용량을 함께 보세요. 긴 프롬프트를 반복하는 서비스의 최종 판단은 자신의 요청으로 측정한 비용과 p95 지연시간에 두는 것이 맞습니다.
