프롬프트 캐싱 진단

프롬프트 캐싱 진단을 사용하면 요청에서 재사용한 토큰 수가 예상보다 적은 이유를 파악할 수 있습니다. 현재 요청을 이전 응답과 비교해 모델, 도구, 설정 또는 입력에서 어떤 변경 사항이 재사용을 막았는지 확인하세요.

Responses API에서는 GPT-5.6 및 진단을 지원하는 후속 모델에서 이 기능을 사용할 수 있습니다. 개별 요청은 진단 기능으로 조사하고, 애플리케이션 전반의 캐시 성능은 프롬프트 캐싱 대시보드에서 모니터링하세요.

작동 방식

프롬프트 캐싱 진단은 현재 요청을 이전 응답과 비교해 예상한 프롬프트 접두부를 재사용하지 못한 이유를 파악하는 데 도움을 줍니다. 접두부는 프롬프트의 시작 부분에 있는 내용입니다. 캐시를 재사용하려면 접두부가 정확히 일치하고 모델, 서비스 등급, 도구를 비롯한 요청 설정이 서로 호환되어야 합니다.

1. 기준 응답을 선택하세요. 같은 조직에서 최근에 완료된 응답 중 현재 요청에서 접두부를 재사용할 것으로 예상하는 응답을 선택하세요. 예를 들어 직전 대화 턴의 응답을 사용할 수 있습니다.
2. 비교를 요청하세요. prompt_cache_options.comparison_response_id에 기준 응답의 id를 지정하세요.
3. 결과를 확인하세요. 현재 응답의 prompt_cache_diagnostics를 확인하세요. 캐시 미스가 감지되면 진단 결과에 원인이 표시됩니다. 실제로 얼마나 재사용했는지는 usage.input_tokens_details.cached_tokens로 확인하세요.

comparison_response_id를 설정하면 진단만 요청합니다. 이전 대화를 불러오거나 캐싱 동작을 바꾸지는 않습니다. 현재 요청은 다른 요청에서 생성된 캐시 항목도 접두부가 일치하면 재사용할 수 있습니다.

사용 예시

다음 예시에서는 모델, 지침, 입력이 동일한 요청을 두 번 보내되 함수 도구의 이름을 get_time에서 get_date로 바꿉니다. 두 번째 요청에서는 첫 번째 응답을 기준으로 캐시 재사용 여부를 비교합니다.

support-policy.txt에는 자체 정책 문서를 넣으세요. 재사용할 접두부는 모델의 캐싱 가능한 최소 길이를 충족해야 합니다. GPT-5.6 및 후속 모델의 최소 길이는 1,024토큰입니다.

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
27from 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)

도구 변경으로 캐시 미스가 발생하면 다음과 같은 결과가 나올 수 있습니다. 토큰 수는 입력에 따라 달라집니다.

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

캐시를 계속 재사용하려면 요청 간에 도구 정의와 순서를 그대로 유지하세요. 목록 끝에 추가하는 방식으로 도구 관리하기를 참고하세요.

여러 턴으로 이어지는 대화

연속된 두 턴을 비교하려면 응답이 완료될 때마다 id를 저장하고, 다음 요청에서 이 값을 comparison_response_id로 지정해 prompt_cache_options에 전달하세요. 첫 번째 턴에서는 비교 ID를 생략하세요.

수정 사항을 테스트할 때는 비교 ID를 기준 응답의 ID로 유지하세요.

스트리밍

stream=True인 경우 prompt_cache_diagnostics는 event.response에 포함됩니다. response.completed 이벤트에서 이 값을 읽으세요.

응답 이해하기

prompt_cache_diagnostics.type에서 비교 결과를 확인하세요.

토큰 수 해석하기

cache_hit는 비교 결과 캐시 미스가 감지되지 않았다는 뜻입니다. 새 입력은 여전히 처리해야 할 수 있습니다. 예를 들어 입력 토큰이 2,500개인 요청에서 비교 대상 응답의 2,000토큰 접두부를 재사용하고 새 토큰 500개를 처리하면 cache_hit가 반환될 수 있습니다.

cache_miss인 경우 다음 값을 확인하세요.

• comparison_reusable_tokens가 있으면 이 값은 비교 대상 응답에서 재사용할 수 있는 접두부의 원래 토큰 수입니다.
• cache_missed_tokens는 그중 재사용하지 못한 토큰 수의 추정치입니다.

진단 결과의 토큰 수는 사용량에 집계된 토큰 수와 다를 수 있습니다. 보고된 캐시 재사용량과 청구 비용은 현재 응답의 사용량 필드를 기준으로 확인하세요.

캐시 미스 해결하기

prompt_cache_diagnostics.reason의 값에 해당하는 캐시 미스 원인과 권장 해결 방법을 다음 표에서 확인하세요.

모델을 바꾸거나 대화의 컨텍스트를 압축하는 등 의도적으로 변경한 사항은 캐시 재사용률이 낮아지더라도 유지할 수 있습니다.

개선 효과 확인하기

변경 사항을 적용한 후 다음 단계를 따르세요.

1. 대표적인 요청을 다시 보내고 기준으로 삼은 응답과 비교하세요.
2. 진단 결과에서 여전히 차이가 있는지 확인하세요.
3. 여러 요청의 cached_tokens, cache_write_tokens, 총비용을 비교하세요.

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

요금 및 요청 한도

프롬프트 캐싱 진단에는 추가 비용이 없으며 요청 한도에도 별도로 집계되지 않습니다. 기준 응답을 얻거나 재시도하기 위해 Responses API에 추가로 보내는 요청에는 일반 요금이 적용되며 요청 한도에 포함됩니다.

데이터 비보관

프롬프트 캐싱 진단은 데이터 비보관 설정과 함께 사용할 수 있습니다. OpenAI는 이 기능을 위해 프롬프트 원문이나 모델 출력값을 저장하지 않습니다. 진단 기록에는 설정 메타데이터, 토큰 수 추정치, 캐시 재사용에 영향을 주는 내용을 비교하기 위한 해시가 포함됩니다. 진단 기록은 조직별로 구분되며 짧은 기간이 지나면 만료됩니다. 이 기록은 프롬프트 캐싱에서 캐시 히트 또는 미스가 발생한 이유를 설명하는 데만 사용됩니다.

comparison_response_id를 설정해도 이전 응답의 내용을 불러오거나 저장하지 않습니다. OpenAI의 데이터 관리 옵션은 사용자 데이터를 참고하세요.

제한 사항

• Responses API에서는 GPT-5.6 및 진단을 지원하는 후속 모델에서 이 기능을 사용할 수 있습니다.
• 진단 기록은 짧은 기간이 지나면 만료됩니다. 기록이 만료되면 API를 통해 응답을 여전히 조회할 수 있어도 comparison_response_not_found가 반환됩니다.
• 진단 결과에는 처음으로 분류된 원인이 표시됩니다. 해당 원인을 해결한 뒤 다시 비교해 다른 원인이 있는지 확인하세요.
• 진단은 가능한 범위에서 수행되므로 일부 캐시 미스의 원인은 분류하지 못할 수 있습니다. 비교 결과가 아직 준비되지 않으면 unavailable이 반환되며, 이 값으로는 캐시 히트인지 미스인지 알 수 없습니다.
• 진단 때문에 요청이 차단되거나 실패하는 일은 없으며, 모델이 출력값을 생성하는 방식도 바뀌지 않습니다.