Reasoning 모델

Reasoning 모델 (Reasoning Models)

모델이 응답을 내기 전에 내부 '사고'를 거치는 모델이 있어요. 이 reasoning 모델은 계획을 세우고, 도구를 효과적으로 쓰고, 대안을 검토하고, 모호함에서 회복하며, 여러 단계로 이어지는 어려운 작업을 더 잘 풀어요. 복잡한 문제 해결, 코딩, 과학적 추론, 다단계 에이전트 워크플로에 특히 강하죠. 대부분의 reasoning 작업은 gpt-6-astra로 시작하는 걸 권해요.

출처: Reasoning models - OpenAI Docs

시작하기

Responses API를 호출하면서 reasoning 모델과 reasoning effort를 지정해요.

from openai import OpenAI

client = OpenAI()

prompt = """
Write a bash script that takes a matrix represented as a string with
format '[1,2],[3,4],[5,6]' and prints the transpose in the same format.
"""

response = client.responses.create(
    model="gpt-6-astra",
    reasoning={"effort": "low"},
    input=[{"role": "user", "content": prompt}],
)

print(response.output_text)

reasoning 모델은 Responses API에서 더 잘 동작해요. Chat Completions도 지원하지만 Responses를 쓰면 모델 지능과 성능이 개선돼요.

Reasoning effort

reasoning.effort 파라미터는 작업을 수행할 때 모델이 얼마나 '생각'할지를 안내해요. 지원 값은 모델에 따라 다르며 none, minimal, low, medium, high, xhigh, max가 있어요. effort가 낮을수록 속도와 토큰 사용이 유리하고, 높을수록 더 완전하게 생각해 더 높은 품질의 응답을 내요. 모델은 effort에 걸쳐 적응형으로 추론해서, 단순한 작업엔 토큰을 적게 쓰고 복잡한 작업엔 더 깊게 생각해요.

기본값도 모델마다 달라요. 예를 들어 gpt-5.5는 medium이 기본이고요. 지연에 민감한 앱에서는 더 깊은 추론 전에 짧은 전조(preamble)를 생성하도록 요청하면 첫 표시 토큰까지 더 빨라져요. 일부 모델은 값 일부만 지원하니 모델 페이지를 확인하세요.

참고로 GPT-6 Astra는 none reasoning effort를 지원하지 않아요. reasoning.effort(Responses)나 reasoning_effort(Chat Completions)를 none으로 두면 HTTP 400이 나요.

Reasoning mode

GPT-5.6 모델은 Responses API에서 standard와 pro reasoning mode를 지원해요. 기본값은 standard이고, 더 어려운 작업에 reasoning.mode를 pro로 두면 더 많은 모델 작업을 하며 더 높은 지연·토큰 사용을 허용해요. mode와 effort는 독립적이에요. reasoning.effort를 생략하면 두 mode 모두 medium이 기본이고요. Pro mode는 수행한 모델 작업을 집계해 선택한 모델의 표준 토큰 요금으로 청구해요.

어떻게 동작하나

Reasoning 모델은 input·output 토큰에 더해 reasoning 토큰을 도입해요. 모델은 이 토큰으로 '생각'하며 프롬프트를 분해하고 여러 접근을 고려해요. gpt-5.5, gpt-5.4 같은 모델은 interleaved thinking을 지원해서 보이는 출력 토큰을 생각 전·중간에 생성하고, 도구 호출 사이에도 생각할 수 있어요.

reasoning 토큰은 API로는 보이지 않지만 컨텍스트 윈도우 공간을 차지하고 output 토큰으로 청구돼요. GPT-5.6 이전 모델의 다단계 대화 기본 동작은 이전 턴의 reasoning을 다음 샘플에 렌더링하지 않고, GPT-5.6 모델은 사용 가능한 reasoning을 렌더링해요. reasoning.context로 지원 모델에서 동작을 선택할 수 있어요.

비용 관리

reasoning 모델의 비용을 관리하려면 max_output_tokens 파라미터로 모델이 생성할 총 토큰 수(reasoning 토큰, 보이는 출력 토큰, 안 보이는 포맷 토큰 포함)를 제한할 수 있어요. 사용된 reasoning 토큰 수는 usage 객체의 output_tokens_details에서 확인할 수 있어요.

{
  "usage": {
    "input_tokens": 75,
    "output_tokens": 1186,
    "output_tokens_details": {
      "reasoning_tokens": 1024
    },
    "total_tokens": 1261
  }
}

생성된 토큰이 컨텍스트 윈도우 한계나 max_output_tokens에 닿으면 status가 incomplete이고 incomplete_details의 reason이 max_output_tokens인 응답을 받아요. 보이는 출력 토큰이 나오기 전에 발생할 수도 있어서 input·reasoning 토큰 비용을 내고도 응답을 못 받을 수 있어요. OpenAI는 이 모델들로 시작할 때 reasoning과 출력을 위해 최소 25,000 토큰을 예약하라고 권장해요.

추론 상태 보존하기

대화 상태와 reasoning 상태는 다른 목적을 가져요. 메시지를 전달하면 보이는 대화 기록이 주어지고, 지속된 reasoning은 지원 모델에서 이전 턴의 호환 reasoning 항목을 다음 컨텍스트로 렌더링해줘요. reasoning.context 값은 auto, current_turn, all_turns가 있어요.

• auto: 선택한 모델의 기본값 사용. 생략과 동일
• current_turn: 현재 턴의 reasoning만 사용. 이전 턴은 다음 샘플에 렌더링 안 함
• all_turns: 이전 턴의 사용 가능한 호환 reasoning 항목을 다음 샘플에 렌더링. GPT-5.6 모델이 지원

all_turns는 이전 응답 항목에 접근할 수 있을 때만 효과가 있어요. previous_response_id를 쓰거나 응답을 대화에 연결하거나 전체 기록을 수동 재생하면 돼요. 지속된 reasoning은 같은 모델 계열 안에서만 재사용돼요. 예를 들어 gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna는 서로의 reasoning을 재사용하지만 GPT-5.6과 GPT-5.5 계열 사이엔 옮겨지지 않아요.

client = OpenAI()
model = "gpt-5.6"

first = client.responses.create(
    model=model,
    input="Inspect this repository and identify the likely bug.",
    reasoning={"context": "current_turn"},
)

second = client.responses.create(
    model=model,
    previous_response_id=first.id,
    input="Now patch the bug and explain the change.",
    reasoning={"context": "all_turns"},
)

print(second.output_text)

함수 호출을 할 때는 마지막 함수 호출과 함께 반환된 reasoning 항목도 함께 넘겨주는 걸 강력히 권장해요. 연속으로 여러 함수를 호출하면 마지막 user 메시지 이후의 모든 reasoning·함수 호출·함수 호출 출력 항목을 넘기면 돼요. 이렇게 하면 모델이 추론 과정을 이어가 토큰 효율적으로 더 나은 결과를 내요.

참고로 stateless mode(store: false 또는 ZDR)에서는 output의 reasoning 항목에 기본적으로 encrypted_content 속성이 포함돼요. all_turns를 쓰려면 모든 출력 항목을 보존하고, 다음 user 메시지를 붙이고 전체 기록을 재생해야 해요.

대화 중에 reasoning 바꾸기

configuration_update 항목으로 어려운 작업은 effort를 높이고, 일상적인 후속 작업은 낮출 수 있어요. 요청 수준의 reasoning.effort는 그대로 두고 다음 user 메시지 앞에 항목을 추가해요. 이 방식은 GPT-6 Astra(gpt-6-astra) 표준 단일 에이전트 모드에서만 지원되고, reasoning effort만 바꿔요.

{
  "type": "configuration_update",
  "reasoning": {
    "effort": "high"
  }
}

대화 기록에서 configuration_update 항목 두 개를 바로 붙여놓지 마세요. API가 인접한 업데이트를 거부해요. 자동 압축·자동 절단과도 조합하지 말고, /responses/compact 엔드포인트도 이 항목이 있는 기록을 거부해요.

Reasoning 요약

모델이 낸 raw reasoning 토큰은 노출하지 않지만, summary 파라미터로 reasoning 요약을 볼 수 있어요. 모델에 따라 지원 설정이 달라요. 예를 들어 computer use 모델은 concise 요약기를, o4-mini는 detailed를 지원해요. 가장 상세한 요약기를 쓰려면 auto로 설정해요. 요약 출력은 reasoning output 항목의 summary 배열에 들어오고, 명시적으로 요청해야만 포함돼요.

response = client.responses.create(
    model="gpt-6-astra",
    input="What is the capital of France?",
    reasoning={"effort": "low", "summary": "auto"},
)

phase 파라미터

GPT-5.5·GPT-5.4로 길게 실행되거나 도구가 많은 흐름에서는 어시스턴트 메시지 phase 필드를 써서 조기 종료 같은 오동작을 피할 수 있어요. phase: "commentary"는 도구 호출 전 전조 같은 중간 갱신에, phase: "final_answer"는 완성된 답변에 써요. user 메시지에는 phase를 넣지 마세요. previous_response_id를 쓰면 이전 어시스턴트 상태가 보존돼 가장 단순하고, 기록을 수동 재생한다면 각 phase 값을 보존하세요.

프롬프트 조언

reasoning 모델을 프롬프팅할 땐 다음을 고려해요. reasoning.effort를 품질 회복의 주 수단으로 보지 말고 조정 손잡이로 보고, 에이전트·연구 중심 워크플로에서는 '완료'가 무엇인지와 모델이 작업을 어떻게 검증할지를 정의해요. reasoning 모델 모범 사례는 이 가이드를 참고하세요.

더 알아보기

• Reasoning best practices - 추론 모델 모범 사례
• Text generation - 텍스트 생성 기본
• Token counting - 출력 토큰 수 이해
• Migrate to Responses API