OpenAI 호환 모드: 추론 모델 출력

추론 모델은 답변하기 전에 “생각”합니다. 호환 모드로 호출하면, 출력에는 일반 모델보다 몇 가지 추가 항목이 포함됩니다. 이 페이지에서는 세 가지를 다룹니다. 추론을 가져오는 방법, 멀티턴을 처리하는 방법, 구조화된 출력을 신뢰성 있게 만드는 방법입니다.

이 페이지는 /v1/chat/completions 호환 모드에 중점을 둡니다. Claude의 기본 추론 블록(/v1/messages의 thinking 필드)에 대해서는 Claude Effort & Thinking Guide를 참조하십시오. Gemini의 기본 thinking_level와 thought_signature에 대해서는 Gemini Native Calls를 참조하십시오.

개요

호환 모드에서는 reasoning 모델이 “thinking text를 출력하는지”에 따라 세 그룹으로 나뉩니다.

유형	예시 모델	생각 내용	답변 받기
생각을 출력하지 않음	gpt-4.1-mini, gemini-3.1-flash-lite, claude-haiku-4-5	없음	일반 모델과 동일합니다
thinking text를 출력함	grok-4.3, qwen3.6-plus, glm-5.1	`reasoning_content` 필드	답변은 `content`에, 생각은 `reasoning_content`에
토큰만	gpt-5.4-mini	텍스트는 없고 `usage.reasoning_tokens`만 있음	일반 모델과 동일합니다

유형과 관계없이, 답변은 항상 content에 있습니다. content만 읽으면 모든 추론 모델이 일반 모델처럼 통합되며, 생각을 노출하고 싶을 때만 reasoning_content을 읽으면 됩니다.

추론 내용: reasoning_content

추론 텍스트를 내보내는 모델은 사고 과정을 reasoning_content에 넣으며, content와 병렬입니다. 비스트리밍 — message에는 둘 다 포함됩니다:

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "1+1 equals 2.",
      "reasoning_content": "The user is asking 1+1 ... (a chain of thought)"
    },
    "finish_reason": "stop"
  }]
}

msg = resp.choices[0].message
print("answer:", msg.content)
# thinking (only some models; may live in model_extra in the SDK)
print("thinking:", getattr(msg, "reasoning_content", None))

스트리밍 — delta.reasoning_content가 먼저 전송되고; 사고가 끝난 뒤에야 delta.content가 시작됩니다. 반드시 둘을 별도로 렌더링하십시오(사고는 접고, 답변은 스트리밍하십시오). 그렇지 않으면 UI에 먼저 생각의 벽이 번쩍 나타납니다:

for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)
    if reasoning:
        render_thinking(reasoning)   # collapsible / muted text
    if delta.content:
        render_answer(delta.content) # main answer area

추론과 콘텐츠의 스트리밍 “상호 배타성”은 세 모델마다 다릅니다 — 세 가지를 모두 허용하십시오:

grok-4.3: 사고 중에는 reasoning_content 키만 존재하고, 답변 중에는 content만 존재합니다(다른 키는 아예 나타나지 않습니다).
qwen3.6-plus: 두 키가 모두 존재합니다. 비활성인 쪽은 null입니다.
glm-5.1: 사고 중에는 content가 ""(빈 문자열)이고 reasoning_content에는 값이 있습니다.

공통 접근 방식: truthiness 검사(if reasoning: / if content:)로 읽어 세 가지 빈 상태 — 누락, null, "" — 를 모두 건너뜁니다.

추론 token은 답변을 압도할 수 있습니다. 테스트에서 사소한 “1+1” 질문은 grok-4.3에서 답변 token이 몇 개에 불과했음에도 reasoning_tokens 수백 개를 생성했습니다. 추론은 출력 token으로 과금되므로, 지연 시간과 비용에 민감한 사용 사례에서는 활성화 / 표시 여부를 평가하십시오.

사고 시그니처와 멀티턴

“thought signature”는 Gemini 네이티브 개념입니다. 네이티브 멀티모달 / 함수 호출에서는 모델이 암호화된 thought_signature를 반환하며, 추론 연속성을 유지하려면 이를 턴 간에 다시 전달해야 합니다(Gemini 네이티브 호출 및 Gemini 함수 호출 참조). /v1/chat/completions 호환 모드에서는 추론 모델이 무상태입니다:

멀티턴에는 이전 assistant 턴의 **content**만 메시지 히스토리에 넣으면 됩니다;
reasoning_content를 다시 전달할 필요가 없으며, 응답에는 시그니처 필드도 나타나지 않습니다;
테스트에서는 gemini-3.1-flash-lite와 grok-4.3이 모두 content만 다시 전달되었을 때도 멀티턴 컨텍스트를 올바르게 유지했습니다.

messages = [
    {"role": "user", "content": "Remember the number 42."},
    {"role": "assistant", "content": "Got it, I'll remember 42."},  # content only
    {"role": "user", "content": "What is that number times 2?"}
]
# grok-4.3 / gemini-3.1-flash-lite both answer 84 correctly

Gemini의 사고 시그니처를 턴 간에 유지해야 하거나, 멀티턴에서 Claude의 네이티브 thinking 블록을 사용해야 한다면, 호환 모드 대신 해당 native 엔드포인트로 전환하십시오.

구조화된 출력

response_format를 사용하여 모델이 JSON만 출력하게 합니다. 두 가지 유형입니다:

# 1) json_schema: strictly constrain fields by schema (OpenAI standard)
response_format = {
    "type": "json_schema",
    "json_schema": {
        "name": "city_info",
        "strict": True,
        "schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "population": {"type": "integer"},
                "is_capital": {"type": "boolean"}
            },
            "required": ["city", "population", "is_capital"],
            "additionalProperties": False
        }
    }
}

# 2) json_object: only guarantees valid JSON, no field constraints
response_format = {"type": "json_object"}

모델별 지원 여부(테스트됨)

json_schema 지원은 매우 다양합니다 — 이는 구조화된 출력에서 가장 큰 함정입니다:

Model	`json_schema`	`json_object`	`content`를 직접 파싱할 수 있습니까
gpt-4.1-mini	✅ 엄격히 준수됨	✅	✅ 순수 JSON
gemini-3.1-flash-lite	✅	✅	✅
grok-4.3	✅ (thinking도 함께 출력함)	✅	✅ 콘텐츠가 순수 JSON입니다
gpt-5.4-mini	⚠️ JSON은 올바르지만 `<think>…</think>`가 앞에 붙습니다	—	❌ 먼저 think 블록을 제거해야 합니다
qwen3.6-plus	⚠️ 400을 반환합니다: messages에는 “json”이라는 단어가 포함되어야 합니다	✅	✅
claude-haiku-4-5	❌ 스키마를 무시하고 Markdown을 반환합니다	—	❌
glm-5.1	❌ 스키마를 무시하고 산문을 반환합니다	✅	✅ json_object에서

모델 전반에서 JSON을 안정적으로 가져오는 방법

json_schema이 모든 모델에서 작동한다고 가정하지 마십시오. 모델 간 신뢰성을 높이려면 다음을 결합합니다:

json_object를 우선 사용하십시오 — json_schema보다 더 폭넓은 호환성을 가집니다;
프롬프트에서 “JSON만 반환하라”고 명시하고 “json”이라는 단어를 포함하십시오 (qwen에서는 필수이며, 다른 모델에서도 더 안정적입니다);
방어적으로 파싱합니다: 제거한 뒤 ```json code fences, strip a <think>…</think> prefix, then json.loads, 실패 시에는 우아하게 처리합니다.

import json, re

def parse_json_loose(content: str):
    # remove a <think>…</think> prefix (gpt-5.4-mini)
    content = re.sub(r"<think>.*?</think>", "", content, flags=re.S).strip()
    # remove ```json code fences
    content = re.sub(r"^```(json)?|```$", "", content, flags=re.M).strip()
    try:
        return json.loads(content)
    except json.JSONDecodeError:
        return None   # degrade: log raw / retry / switch model

기초

기본 API

이미지 API (공식)

동영상 API (공식)

멀티모달 이해 API

텍스트 API

OpenAI 호환 모드: 추론 모델 출력

개요

추론 내용: reasoning_content

사고 시그니처와 멀티턴

구조화된 출력

모델별 지원 여부(테스트됨)

모델 전반에서 JSON을 안정적으로 가져오는 방법

관련 링크

​개요

​추론 내용: reasoning_content

​사고 시그니처와 멀티턴

​구조화된 출력

​모델별 지원 여부(테스트됨)

​모델 전반에서 JSON을 안정적으로 가져오는 방법

​관련 링크

개요

추론 내용: reasoning_content

사고 시그니처와 멀티턴

구조화된 출력

모델별 지원 여부(테스트됨)

모델 전반에서 JSON을 안정적으로 가져오는 방법

관련 링크