전체 문서 색인은 llms.txt를 참조하세요. 문서 페이지 URL 끝에 .md 를 추가하면 해당 페이지의 Markdown 버전을 볼 수 있습니다.
기본 탐색 메뉴

프리픽스 유지하기

프리픽스를 변경하지 않으면 캐시를 더 많이 재사용하고 턴이 바뀌어도 추론을 유지할 수 있습니다.

에이전트 기반 애플리케이션이나 여러 턴에 걸쳐 대화하는 애플리케이션에서는 API 요청 간에 추론을 유지하고 새로운 동작과 지시를 항상 모델 컨텍스트의 끝에 추가할 때 모델 성능이 가장 좋습니다. 프리픽스를 그대로 유지하는 것은 오래전부터 프롬프트 캐싱의 권장 방식이었습니다. 캐시는 요청의 처음부터 일치 여부를 확인하므로 프리픽스가 바뀌면 변경 지점부터 캐시를 재사용하지 못할 수 있습니다. 변경 사항을 끝에 추가하면 대화에서 캐시를 재사용할 수 있는 부분이 늘어나 입력 비용을 크게 줄이고 응답 속도를 높일 수 있습니다.

새로운 프런티어 모델부터는 안전장치의 일환으로 API가 프리픽스 변경 지점 뒤에 있는 추론 항목을 제거합니다. 추론 항목이 제거되면 모델이 일부 추론을 다시 수행해야 할 수 있으며, 이로 인해 토큰 사용량과 비용이 늘고 지연 시간이 길어질 수 있습니다. 모델이 사라진 추론을 복구하지 못하면 출력 품질도 떨어질 수 있습니다.

모델의 성능을 최대한 활용하려면 프리픽스를 그대로 유지하고, 가능한 한 컨텍스트 끝에만 항목을 추가하는 방식으로 통합하세요.

프리픽스 변경이란?

추론 항목의 프리픽스는 해당 항목에 앞서 나오는 대화 기록입니다. 도구 결과를 줄이거나 개발자 메시지를 다시 쓰거나 이전 턴을 요약으로 대체하는 등 이 기록을 수정하면 프리픽스가 바뀝니다.

대화 기록 변경
원래 대화다음 요청 및 API 처리 방식
사용자 메시지원장의 합계를 확인해 주세요.동일한 메시지
도구 호출 전 추론 재사용 가능
도구 호출lookup_ledger()동일한 호출
도구 실행 결과[{"amount": 40}, {"amount": 50}]동일한 행
도구 실행 결과를 받은 후의 추론재사용 가능
Both reasoning items have the same history before them as in the original conversation.

프리픽스 변경을 피하도록 통합 수정하기

Responses API에서 tools나 text.format 같은 매개변수를 바꾸면 의도치 않게 프리픽스가 바뀔 수 있습니다. GPT-6.2 이전 모델에서는 instructions를 변경해도 프리픽스가 바뀔 수 있습니다. 이전 input 항목을 수정하면 모델 버전에 관계없이 프리픽스가 바뀔 수 있습니다. 통합에서 이런 변경이 일어나는지 점검하세요.

아래 표에는 통합에서 프리픽스가 바뀌는 흔한 경우와, 가능한 경우 컨텍스트 끝에 항목을 추가하여 같은 목적을 달성하는 방법이 나와 있습니다.

프리픽스가 바뀌는 흔한 경우 프리픽스 변경을 피하는 방법
추론 수준 변경 Responses API의 reasoning.effort 매개변수는 그대로 두고, 새 추론 수준을 담은 configuration_update 항목을 입력 항목 목록 끝에 추가하세요. 요청 수준의 기존 설정을 유지하세요.
구조화된 출력값 스키마 변경 Responses API의 text.format 매개변수는 그대로 두고, 새 스키마를 담은 configuration_update 항목을 입력 항목 목록 끝에 추가하세요. 요청 수준의 기존 설정을 유지하세요.
에이전트가 사용할 수 있는 도구 변경 Responses API의 tools 매개변수는 그대로 두세요. 도구를 추가하려면 additional_tools 항목을 사용하세요. 특정 턴에서 모델이 호출할 수 있는 도구를 제한하려면 tool_choice를 allowed_tools와 함께 사용하세요. 기존 도구 정의의 순서를 유지하세요. additional_tools에 developer 역할과 tools 배열을 지정해 끝에 추가하고, 이후 요청에서 이 항목을 다시 보낼 때는 처음 추가한 위치에 두세요.
개발자 지시 업데이트 재사용할 지시는 첫 번째 developer 메시지에 담아 input에 포함하세요. 이 지시를 업데이트하려면 첫 개발자 메시지는 그대로 두고 모델 컨텍스트 끝에 새 developer 메시지를 추가하세요.

GPT-6.2부터는 해당 턴에만 적용할 개발자 메시지를 최상위 instructions에 지정하세요. API는 이 메시지를 input 뒤에 추가하며, 메시지의 토큰에는 캐시되지 않은 입력 토큰 요금을 적용합니다.
컨텍스트 압축 컨텍스트 압축은 프리픽스를 바꾸므로 캐시 미스를 피하기 어렵습니다.

OpenAI 컨텍스트 압축. OpenAI 컨텍스트 압축을 /responses/compact 또는 context_management를 통해 사용하면 프리픽스가 바뀌어도 OpenAI 시스템이 변경 지점 이후의 추론 항목을 유지합니다. OpenAI 컨텍스트 압축 항목은 컨텍스트 내 어디에나 배치할 수 있습니다. /responses/compact를 호출할 때는 instructions를 생략하고, 반환된 컨텍스트 윈도우의 항목을 원래 순서대로 다음 요청에 전달하세요. context_management는 구성 업데이트와 개발자가 추가한 도구를 이후 요청에도 유지합니다. 명시적으로 컨텍스트를 압축하는 경우에는 다음 요청에서 이를 복원하세요.

자체 컨텍스트 압축. 다른 압축 방식을 사용하거나 직접 구현한 경우에는 압축된 항목을 최근 턴 앞이 아니라 모델 컨텍스트 끝에 배치하세요. 최근 턴 앞에 배치할 수도 있지만, 이 경우 원래 대화 기록에서 해당 항목 뒤에 있던 추론 항목이 제거됩니다.
이전 도구 출력 줄이기 또는 이전 파일이나 이미지 크기 줄이기 일부 통합에서는 컨텍스트 압축을 사용하는 대신 이전 도구 출력, 파일, 이미지 등의 항목을 잘라냅니다. 이렇게 수정하면 프리픽스가 바뀝니다. 컨텍스트 압축을 사용하거나, 긴 도구 출력을 줄이고 이미지나 파일의 크기를 줄이는 작업을 해당 항목을 모델에 처음 보내기 전에 수행하는 방식을 적극 권장합니다.

통합에서 프리픽스 변경 점검하기

프롬프트 캐시 진단을 사용해 캐시 미스가 발생한 시점을 확인하고 프리픽스 변경을 조사하세요. prompt_cache_options.comparison_response_id에 이전 응답 ID를 지정해 현재 요청을 이전 응답과 비교한 다음, 진단에 표시된 원인과 캐시된 토큰 수를 확인하세요. 이 정보를 활용해 통합에서 프리픽스가 바뀌는 일을 줄이세요. 진단은 확인 가능한 범위에서 처음 찾은 차이를 보고합니다. 모델이 추론을 재사용했는지는 진단으로 확인할 수 없습니다.

Responses API 응답의 input_transformations에서 API가 입력에서 어떤 추론 항목을 왜 제거했는지 확인하세요. prefix_mismatch로 추론 항목이 제거된 원인을 조사하려면 id를 이전 응답의 output에 있는 추론 항목과 대조하세요. 통합에서 이전 입력을 수정한 경우, 위에서 권장한 방식으로 통합을 수정해 추론을 유지할 수 있습니다.