한 줄 정의
reasoning.effort는 OpenAI 추론 모델이 답을 내기 전에 얼마나 오래 생각할지 조절하는 요청 시점 설정이야. 같은 모델을 써도 이 값을 어떻게 두느냐에 따라 품질, 지연 시간, reasoning 토큰 사용량이 같이 바뀌므로, 단순한 취향 옵션보다 운영 파라미터에 가깝다고 보면 돼.
어떻게 작동하나
Responses API에서는 reasoning: { effort: "medium" }처럼 reasoning 객체 안에 넣고, chat-completions 경로에서는 같은 축을 밑줄 표기 필드로 보낸다. 표기만 다르고 역할은 같다. 2026년 5월 3일 기준 OpenAI 공식 API 참조에서 지원하는 단계는 여섯 가지야.
none: 추론 단계를 사실상 끄는 쪽이야.minimal: 아주 짧게 생각하고 빨리 답하는 쪽이야.low: 속도와 비용을 아끼되 최소한의 검토는 남기는 쪽이야.medium: 기본 균형값이야.high: 더 오래 검토하게 해서 복잡한 작업 쪽으로 기울여.xhigh: 가장 긴 추론 예산을 주는 단계야.
낮출수록 빨리 답하고 추론 토큰을 덜 쓰는 쪽으로 가고, 높일수록 더 오래 검토하고 도구 호출도 더 적극적으로 쓰는 쪽으로 간다. 모델마다 제한도 조금씩 달라서 단계 이름만 보고 끝내면 안 돼.
- GPT-5.1: 기본값이
none이고 지원 범위도none,low,medium,high까지만 열려 있어. gpt-5-pro:high만 지원해.gpt-5.1이전 모델: 기본값이medium이고none을 지원하지 않아.
그래서 이 용어를 보면 “높게 둘까 낮게 둘까”보다 먼저 “지금 붙인 모델이 어떤 단계를 실제로 받는가”를 같이 봐야 해.
왜 중요한가
이 설정이 중요한 이유는 추론 모델을 도입할 때 가장 먼저 부딪히는 현실 문제가 성능 자체보다 운영 감각이기 때문이야. 간단한 분류나 짧은 코드 수정처럼 정답 경로가 짧은 요청에 high나 xhigh를 기본으로 두면, 응답은 느려지고 비용은 늘었는데 품질 차이는 거의 안 나는 경우가 많아. 반대로 여러 파일을 읽고 계획을 세우는 agentic-coding 작업이나 도구를 몇 번 부르는 에이전트 루프에서는 effort를 너무 낮게 두면 검색을 덜 하거나 검증 단계를 생략해서 결과가 쉽게 흔들릴 수 있어.
OpenAI도 이 값을 고정 답안처럼 쓰지 말고 eval로 맞추라고 설명해. 실무에선 보통 low나 medium으로 기준선을 잡고, 실패 사례를 본 뒤에만 더 올리는 편이 안정적이야. 그래서 reasoning.effort는 “모델이 똑똑한가”를 말하는 용어가 아니라, 같은 모델을 어떤 업무에 어떤 비용과 속도로 붙일지 정하는 제어점이라고 읽는 게 맞아.
주의해서 볼 점
첫째, 점 표기와 밑줄 표기를 섞어 쓰면 구현 문맥이 흐려져. Responses API에서는 중첩 객체로 보내고, 채팅 경로에서는 밑줄 표기 단일 필드로 보낸다. 문서나 코드 리뷰에서 둘을 같은 문자열처럼 적어 버리면 마이그레이션할 때 헷갈리기 쉬워.
둘째, 높은 단계가 항상 정답은 아니야. OpenAI 공식 실무 가이드도 작업 난도에 맞춰 실험하라고 적고 있어. 짧은 Q&A, 단순 추출, 포맷 변환 같은 요청은 minimal이나 low가 더 나을 수 있어.
셋째, 이 설정은 추론 토큰과 지연 시간을 같이 바꾸므로 비용 정책과 붙여서 봐야 해. 특히 긴 문맥, 여러 번의 도구 호출, 후속 검증이 섞인 작업에선 effort를 한 단계 올리는 것만으로도 실행 시간이 꽤 달라질 수 있어. 그래서 제품 기본값을 정할 때는 “정확도가 조금 오르는가”만 보지 말고 “그 상승이 추가 지연과 토큰 비용을 감당할 만큼 큰가”까지 같이 재는 편이 맞아.