Reasoning Effort 파라미터¶

이 문서는 Continuum Router가 다양한 LLM 백엔드에서 reasoning_effort 파라미터를 어떻게 처리하는지 설명합니다. 토큰 예산 변환 및 지원되는 effort 레벨을 포함합니다.

개요¶

reasoning_effort 파라미터는 모델이 응답을 생성하기 전에 추론에 사용하는 계산 노력의 양을 제어합니다. 각 백엔드는 이 기능을 다르게 구현합니다:

• OpenAI: O-series 및 GPT-5.2 thinking 모델에 대한 네이티브 reasoning_effort 파라미터
• Anthropic: 확장 사고(extended thinking)를 지원하는 Claude 모델의 thinking.budget_tokens로 변환, 또는 auto effort에 대해 {"type": "adaptive"}로 변환
• Gemini: OpenAI 호환 엔드포인트를 통한 thinking 모델에 대한 네이티브 reasoning_effort
• 기타 백엔드: 패스스루 (변환 없음)

파라미터 형식¶

Continuum Router는 두 가지 입력 형식을 지원하며, 내부적으로 정규화됩니다:

평면 형식 (Chat Completions API)¶

{
  "model": "o3-mini",
  "reasoning_effort": "high",
  "messages": [...]
}

중첩 형식 (Responses API)¶

{
  "model": "o3-mini",
  "reasoning": {
    "effort": "high"
  },
  "input": "..."
}

두 형식 모두 처리 전에 평면 reasoning_effort 형식으로 자동 정규화됩니다. 둘 다 존재하는 경우 평면 형식이 우선합니다.

토큰 예산 직접 지정¶

고급 사용 사례의 경우, reasoning_effort 레벨 대신 토큰 예산을 직접 지정할 수 있습니다:

Anthropic: thinking 파라미터 직접 사용¶

{
  "model": "claude-sonnet-4-20250514",
  "thinking": {
    "type": "enabled",
    "budget_tokens": 16000
  },
  "messages": [...]
}

적응형 사고(Adaptive Thinking)의 경우 (모델이 사고의 시점과 정도를 결정):

{
  "model": "claude-opus-4-6-20260205",
  "thinking": {
    "type": "adaptive"
  },
  "messages": [...]
}

Gemini: extra_body를 통한 thinking_budget 직접 지정¶

{
  "model": "gemini-2.5-pro",
  "extra_body": {
    "google": {
      "thinking_config": {
        "thinking_budget": 10000,
        "include_thoughts": true
      }
    }
  },
  "messages": [...]
}

백엔드별 동작¶

OpenAI 백엔드¶

OpenAI 모델은 reasoning_effort 파라미터를 네이티브로 지원합니다. 라우터는 값을 OpenAI API에 직접 전달합니다.

지원되는 Effort 레벨¶

reasoning_effort를 지원하는 모델¶

O-series 모델 (low, medium, high 지원):

• o1, o1-mini, o1-preview
• o3, o3-mini, o3-pro
• o4-mini

GPT-5.2 thinking 모델 (low, medium, high, xhigh 지원):

• gpt-5.2, gpt-5.2-thinking, gpt-5.2-latest
• gpt-5.2-pro

reasoning_effort를 지원하지 않는 모델¶

다음 모델들은 reasoning 파라미터를 지원하지 않습니다 (파라미터가 제거됨):

• GPT-4o, GPT-4o-mini, GPT-4-turbo, GPT-4
• GPT-5.2-chat-latest, GPT-5.2-instant (non-thinking 변형)
• GPT-5.1, GPT-5
• GPT-3.5-turbo
• 임베딩 모델, 이미지 모델

Anthropic 백엔드 (Claude)¶

Anthropic Claude 모델은 모델 세대에 따라 다른 메커니즘을 사용합니다:

• Claude Fable 5와 Mythos 5 (Mythos급; Mythos 5는 Fable 5에서 안전장치를 해제한 한정 출시 버전): 적응형 사고({"type": "adaptive"})와 output_config.effort를 사용합니다. Opus 4.8과 같은 요청 형식으로 레거시 budget_tokens는 HTTP 400으로 거부되고 temperature/top_p/top_k는 자동으로 제거되며 max effort를 지원합니다. 추가 제약으로 명시적 thinking.type == "disabled"를 HTTP 400으로 거부하기 때문에 라우터가 thinking 파라미터를 전달하지 않고 생략합니다.
• Claude 4.8+ 모델 (Opus 4.8): 적응형 사고({"type": "adaptive"})와 output_config.effort로 사고 깊이를 제어. 레거시 thinking.type: "enabled" + budget_tokens 형식은 HTTP 400으로 거부됩니다. temperature, top_p, top_k는 허용하지 않으며, 라우터가 자동으로 제거합니다. Effort 기본값은 high입니다.
• Claude 4.6+ 적응형 모델 (Opus 4.6, Sonnet 4.6, Opus 4.7): 적응형 사고({"type": "adaptive"})와 output_config.effort로 사고 깊이를 제어. Claude Opus 4.7은 이 API가 필수이며, 레거시 budget_tokens 형식을 보내면 HTTP 400 오류가 발생합니다.
• 4.6 이전 모델 (Opus 4.5, Sonnet 4 등): 확장 사고에 thinking.budget_tokens 사용

변환 테이블: Claude 4.6+ 모델 (적응형 사고)¶

Claude 4.6+ 적응형 모델(claude-opus-4-6-*, claude-sonnet-4-6-*, claude-opus-4-7-*, claude-opus-4-8-*, claude-fable-5-*, claude-mythos-5-*)은 budget_tokens 대신 output_config.effort를 사용합니다:

변환 테이블: 4.6 이전 Claude 모델 (Budget Tokens)¶

4.6 이전 모델은 thinking.budget_tokens를 사용합니다:

변환 예시: Claude 4.6+ (적응형 사고 + Effort)¶

입력 (OpenAI 형식):

{
  "model": "claude-opus-4-6-20260205",
  "reasoning_effort": "high",
  "messages": [...]
}

변환됨 (Anthropic 형식):

{
  "model": "claude-opus-4-6-20260205",
  "thinking": {
    "type": "adaptive"
  },
  "output_config": {
    "effort": "high"
  },
  "messages": [...]
}

Opus 4.6 또는 Opus 4.7에서 xhigh를 사용하면 output_config.effort가 "max"로 설정됩니다:

{
  "model": "claude-opus-4-6-20260205",
  "thinking": {"type": "adaptive"},
  "output_config": {"effort": "max"},
  "messages": [...]
}

변환 예시: 4.6 이전 Claude (Budget Tokens)¶

입력 (OpenAI 형식):

{
  "model": "claude-sonnet-4-20250514",
  "reasoning_effort": "high",
  "messages": [...]
}

변환됨 (Anthropic 형식):

{
  "model": "claude-sonnet-4-20250514",
  "thinking": {
    "type": "enabled",
    "budget_tokens": 32768
  },
  "messages": [...]
}

적응형 사고 (Auto)¶

reasoning_effort가 "auto"로 설정되면 라우터는 output_config.effort 없이 {"type": "adaptive"}를 생성합니다. 그러면 Anthropic이 기본 effort 레벨(현재 high)을 사용하고 모델이 언제, 얼마나 추론할지를 동적으로 결정합니다.

입력 (OpenAI 형식):

{
  "model": "claude-opus-4-6-20260205",
  "reasoning_effort": "auto",
  "messages": [...]
}

변환됨 (Anthropic 형식):

{
  "model": "claude-opus-4-6-20260205",
  "thinking": {
    "type": "adaptive"
  },
  "messages": [...]
}

output_config 직접 전달 (Pass-Through)¶

요청에 이미 명시적인 thinking 및 output_config 매개변수가 포함되어 있으면 변환 없이 직접 전달됩니다:

{
  "model": "claude-opus-4-6-20260205",
  "thinking": {"type": "adaptive"},
  "output_config": {"effort": "medium"},
  "messages": [...]
}

확장 사고를 지원하는 모델¶

확장 사고는 다음에서 지원됩니다:

• Claude Fable 5 / Mythos 5 (적응형 사고 + effort; max 지원; 샘플링 파라미터 제거; 명시적 비활성 thinking 생략): claude-fable-5-*(alias claude-fable-5-latest), claude-mythos-5-*(alias claude-mythos-5-latest, 한정 출시)
• Claude Opus 4.8 (적응형 사고 + effort; 샘플링 파라미터 미지원; effort 기본값 high): claude-opus-4-8-*, alias claude-opus-4-8-latest
• Claude Opus 4.7 (적응형 사고 + effort; 샘플링 파라미터 지원 중단): claude-opus-4-7-*
• Claude 4.6 계열 (적응형 사고 + effort): claude-opus-4-6-*, claude-sonnet-4-6-*
• Claude Opus 모델 (budget tokens): claude-opus-4-*, claude-opus-4-5-*
• Claude Sonnet 4 모델 (budget tokens): claude-sonnet-4-*, claude-sonnet-4-5-*

Gemini 백엔드¶

Gemini 모델은 OpenAI 호환 엔드포인트를 통해 reasoning_effort를 네이티브로 지원합니다. 라우터는 값을 검증하고 직접 전달합니다.

지원되는 Effort 레벨¶

Flash 모델 (none 지원)¶

• gemini-2.0-flash
• gemini-2.5-flash
• gemini-3-flash
• gemini-3.1-flash
• gemini-3.5-flash

Pro 모델 (none 미지원)¶

• gemini-2.5-pro
• gemini-3-pro

추가 기능¶

Gemini thinking 모델의 경우, 라우터는 자동으로:

1. reasoning content를 노출하기 위해 include_thoughts: true 설정
2. 지정되지 않은 경우 기본 max_completion_tokens: 16384 설정
3. 모델 기능에 대해 effort 레벨 검증

Generic/HTTP 백엔드¶

Generic HTTP 백엔드 (Ollama, vLLM, LocalAI, LM Studio 등에 사용)는 변환 없이 요청을 전달합니다.

llama.cpp 백엔드¶

llama.cpp 백엔드는 패스스루 동작을 사용합니다:

vLLM 백엔드¶

vLLM은 OpenAI 호환 API를 제공하지만 reasoning effort 지원은 모델에 따라 다릅니다:

요약 테이블¶

응답 형식¶

reasoning/thinking이 활성화되면 응답에 모델의 추론 과정이 포함됩니다:

OpenAI 형식 (reasoning_content 포함)¶

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "답은 42입니다.",
      "reasoning_content": "단계별로 생각해보겠습니다..."
    },
    "finish_reason": "stop"
  }]
}

Claude 확장 사고 (OpenAI 형식으로 변환됨)¶

라우터는 Claude의 thinking 블록을 reasoning_content 필드로 변환합니다:

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "답은 42입니다.",
      "reasoning_content": "여러 요소를 고려해야 합니다..."
    },
    "finish_reason": "stop"
  }]
}

모범 사례¶

1. 적절한 effort 레벨 사용: 높은 effort = 더 나은 추론이지만 더 느리고 비용이 많이 듬
2. 모델 지원 확인: 모든 모델이 reasoning 파라미터를 지원하지 않음
3. xhigh 신중히 처리: GPT-5.2 계열만 xhigh를 지원; 다른 모델에는 high 사용
4. 비용 고려: 확장 사고는 추가 토큰 소비 (특히 Anthropic의 budget_tokens)
5. 백엔드 테스트: Generic 백엔드는 지원 수준이 다양할 수 있음

관련 문서¶

• API 레퍼런스 - 채팅 완료
• API 레퍼런스 - Responses API
• 설정 가이드