Thinking / 추론
Thinking / 추론 (Thinking / Reasoning)
모델이 응답하기 전에 얼마나 추론할지 제어해요. OpenAI, Anthropic, Google Gemini, AWS Bedrock, Docker Model Runner에서 동작해요.
출처: 문서
본문
Thinking이란 무엇인가? (What Is Thinking?)
여러 현대 모델은 보이는 출력을 만들기 전에 일어나는 확장 추론 단계를 지원해요. 이 단계 동안 모델은 계획하고, 옵션을 평가하고, 문제를 풀어나가요 — 내부적으로, 기본적으로 응답에 표시되지 않아요. 이것은 일반적으로 코딩, 수학, 다단계 계획 같은 복잡한 작업에서 정확도를 개선하며, 더 높은 토큰 사용량과 대기 시간을 대가로 해요.
Docker Agent는 어떤 이름 있는 모델이든 단일 thinking_budget 필드로 이것을 노출해요. 값 형식은 제공자마다 조금 다르지만 의미는 같아요: 더 높은 effort는 더 철저한 추론을 의미해요.
Note Think 도구 vs. thinking 버짓
think도구는 네이티브 추론이 없는 모델을 위한 스크래치패드예요. 모델이thinking_budget을 지원한다면think도구가 필요 없어요.
빠른 참조 (Quick Reference)
| Provider | Format | Values | Default |
|---|---|---|---|
| OpenAI | string | none, minimal, low, medium, high, xhigh, max; xhigh 는 gpt-5.2+, none / max 는 gpt-5.6+에서만, minimal 은 gpt-5.6+에서 제거됨 |
medium (API 기본) |
| Anthropic | int or str | 1024–32768 토큰, 또는 minimal – max, adaptive, adaptive/<effort>, none |
off |
| Gemini 2.5 | int | 0 (off), -1 (dynamic), 또는 토큰 수 (최대 24576 / 32768) | -1 (dynamic) |
| Gemini 3 | string | minimal, low, medium, high |
API 기본 (모델별) |
| AWS Bedrock | int or str | 1024–32768 토큰 (minimal – max 는 토큰으로 매핑); Opus 4.6+는 adaptive, adaptive/<effort> (이전 Claude 모델은 거부) |
off |
| Docker Model Runner | int or str | 토큰 수, minimal – max(토큰으로 매핑), adaptive(무제한), none |
엔진 기본 |
문자열 값은 대소문자를 구분하지 않아요. 받아들여지는 전체 문자열 집합은 none, minimal, low, medium, high, xhigh, max, adaptive, adaptive/<effort> — 하지만 각 제공자는 위에 나열된 하위 집합만 존중해요. 지원되지 않는 값은 요청 시 실패하거나(OpenAI) 아래 제공자별 설명대로 매핑/무시돼요.
thinking_budget 은 위 제공자들이 만 적용해요. 다른 OpenAI 호환 제공자(xAI, Mistral, Ollama 등)는 현재 무시해요 — xAI and Mistral 참고.
OpenAI
OpenAI 추론 모델(o-series, gpt-5, gpt-5-mini, gpt-5.6 계열)은 reasoning_effort API 파라미터에 매핑되는 문자열 effort 레벨을 사용해요. xhigh 레벨은 gpt-5.2+가 필요하고, none 과 max 는 gpt-5.6+(Sol/Terra/Luna)가 필요하며, minimal 은 gpt-5.6+에서 제거돼요.
models:
gpt-thinker:
provider: openai
model: gpt-5.6
thinking_budget: high # none | minimal | low | medium | high | xhigh | max
Effort 레벨:
| Level | Description |
|---|---|
none |
추론 없음. gpt-5.6+에서 그대로 전송(실제 API 값); 이전 모델에서는 로컬 thinking_budget 만 비활성화(API 자체 기본값은 여전히 적용). |
minimal |
가장 빠름; 가장 가벼운 추론 패스. gpt-5.6+에서 받아들여지지 않음(API에서 제거됨). |
low |
단순 작업용 빠른 추론. |
medium |
균형 잡힌 기본값. |
high |
더 철저함; 복잡한 작업에 권장. |
xhigh |
거의 최대 effort; 더 느리지만 가장 정확. gpt-5.2+ 필요. |
max |
최대 effort. gpt-5.6+ 필요. |
토큰 수, adaptive, adaptive/<effort> 는 요청 시 구성 오류로 거부돼요. xhigh 는 gpt-5.2 이상의 마이너 버전(예: gpt-5.2, gpt-5.4-mini)에서만 지원됩니다; none 과 max 는 gpt-5.6 이상(Sol/Terra/Luna)에서만 지원되고, minimal 은 gpt-5.6+에서 받아들여지지 않아요. 이전 모델(o1, o3-mini)은 low / medium / high 만 받아들여요 — 지원되지 않는 레벨을 보내면 API 에러가 반환돼요.
Warning Tokens와 max_tokens 이전 OpenAI 추론 모델은 항상 내부적으로 추론해요 —
thinking_budget: none에도max_tokens에 포함되는 숨겨진 추론 토큰이 있어요. gpt-5.6+(Sol/Terra/Luna)에서none은 추론을 진짜로 비활성화하는 실제 API 값이에요. Docker Agent는 내부 저-effort 호출(예: 제목 생성)에 대해 출력 토큰 바닥을 자동으로 올려 숨겨진 추론이 보이는 텍스트 출력을 굶기지 않게 해요.
Anthropic
Anthropic Claude는 두 가지 thinking 모드를 지원해요: 토큰 버짓(이전 모델)과 adaptive/effort 기반 thinking(더 새로운 모델).
토큰 버짓 (Claude 4 이전) — Token budget
명시적 thinking 토큰 수(1024–32768)를 설정해요. 이것은 max_tokens 보다 작아야 해요:
models:
claude-thinker:
provider: anthropic
model: claude-sonnet-4-5
thinking_budget: 16384 # tokens reserved for internal reasoning
Docker Agent는 thinking 버짓을 설정했지만 max_tokens 를 기본값에 둘 때 자동으로 max_tokens 를 조정해요. max_tokens 를 명시적으로 설정하면 thinking_budget 보다 커야 해요.
적응형 thinking (Opus 4.6+ 및 Sonnet 4.6) — Adaptive thinking
더 새로운 Claude 모델은 모델이 얼마나 생각할지 결정하는 adaptive thinking을 지원해요. Claude Opus 4.6, 4.7, 4.8, Sonnet 4.6은 adaptive thinking만 지원해요 — 토큰 기반 버짓을 거부해요. adaptive, adaptive/<effort>, 또는 맨 effort 레벨을 사용하세요 — Anthropic에서는 high 같은 맨 effort 레벨이 그 effort에서 adaptive thinking의 약칭이에요:
models:
claude-adaptive:
provider: anthropic
model: claude-opus-4-6
thinking_budget: adaptive # model decides effort (defaults to high)
claude-adaptive-low:
provider: anthropic
model: claude-opus-4-6
thinking_budget: low # same as adaptive/low
claude-adaptive-max:
provider: anthropic
model: claude-opus-4-6
thinking_budget: adaptive/max # adaptive/low | adaptive/medium | adaptive/high | adaptive/xhigh | adaptive/max
적응형 effort 레벨과 모델별 지원:
| Level | Opus 4.5 | Sonnet 4.5 / Haiku | Sonnet 4.6 | Opus 4.6 | Opus 4.7 / 4.8 | Fable 5 | Mythos 5 | Mythos preview |
|---|---|---|---|---|---|---|---|---|
low |
✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
medium |
✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
high |
✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
xhigh |
— | — | — | — | ✓ | ✓ | ✓ | — |
max |
— | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
minimal 은 low 로 취급돼요(맨 형태만). adaptive 를 effort 레벨 없이 사용하면 high 가 기본값이에요.
Warning Effort 문자열은 adaptive 가능 모델이 필요해요 Anthropic의 모든 문자열 effort 값은 adaptive thinking(
output_config.effort)으로 보내지며, 더 새로운 Claude 모델(Opus 4.6+, Sonnet 4.6)만 받아들여요. Sonnet 4.5 같은 이전 모델에는 정수 토큰 버짓을 대신 사용하세요. 반대로 adaptive thinking만 지원하는 모델(Opus 4.6, 4.7, 4.8, Sonnet 4.6)은 토큰 버짓이 자동으로 adaptive로 강제 변환돼요(경고가 로그됨).
thinking 비활성화 (Disabling thinking)
thinking_budget: none # or 0
인터리브 thinking (Interleaved thinking)
인터리브 thinking은 모델이 도구 호출 사이에 추론하게 해요 — 복잡한 에이전트 작업에 유용해요. Docker Agent는 Claude 모델에 thinking 버짓이 구성될 때마다 자동으로 활성화하므로, 끄기 위해서만 명시적으로 설정하면 돼요:
models:
claude-interleaved:
provider: anthropic
model: claude-sonnet-4-5
thinking_budget: 16384
# interleaved_thinking is auto-enabled; disable it explicitly if needed:
provider_opts:
interleaved_thinking: false
Note Temperature와 top_p extended thinking이 활성화되면 Anthropic은 temperature=1.0 을 요구해요. Docker Agent는 구성한 temperature나 top_p 설정을 자동으로 억제해요 — thinking이 활성화된 동안 조용히 무시돼요.
Thinking 표시 (Thinking display)
더 새로운 Claude 모델(Opus 4.7+, Fable 5)은 API 레벨에서 기본적으로 thinking 콘텐츠를 숨겨요. 추론을 보이게 하려면 Docker Agent는 명시적 thinking_display 없이 adaptive/effort 기반 thinking이 사용될 때마다 요약된 thinking을 요청해요. provider_opts 의 thinking_display 를 사용해 재정의해요:
models:
opus-47:
provider: anthropic
model: claude-opus-4-7
thinking_budget: adaptive
provider_opts:
thinking_display: omitted # summarized | omitted (display: pre-4.6 models only)
| Value | Behavior |
|---|---|
summarized |
텍스트 요약과 함께 thinking 블록 반환 (adaptive thinking용 Docker Agent 기본값). |
display |
표시용 전체 thinking 블록 반환. pre-4.6 토큰 thinking 모델에서만 — Opus/Sonnet 4.6+, Sonnet 5, Fable 5에서 거부 (Docker Agent가 구성 오류로 빠르게 실패). |
omitted |
thinking 블록 숨김 — 서명만 반환. |
thinking_display 와 무관하게 전체 thinking 토큰이 청구돼요.
작업 버짓 (Anthropic) — Task budget
task_budget 은 전체 다단계 에이전트 작업(thinking + 도구 호출 + 출력 모두 결합)에서 총 토큰을 상한 짓는 것이에요:
models:
opus-bounded:
provider: anthropic
model: claude-opus-4-7
thinking_budget: adaptive
task_budget: 128000 # total token ceiling for the whole task
상세는 Anthropic 제공자 페이지 참고.
Google Gemini
Gemini 2.5와 Gemini 3은 다른 형식을 사용해요.
Gemini 2.5 (토큰 버짓)
models:
gemini-off:
provider: google
model: gemini-2.5-flash
thinking_budget: 0 # disable thinking
gemini-dynamic:
provider: google
model: gemini-2.5-flash
thinking_budget: -1 # let the model decide (default)
gemini-fixed:
provider: google
model: gemini-2.5-flash
thinking_budget: 8192 # fixed token budget (max 24576 for Flash, 32768 for Pro)
Gemini 3 (레벨 기반)
models:
gemini3-flash:
provider: google
model: gemini-3-flash
thinking_budget: medium # minimal | low | medium | high
gemini3-pro:
provider: google
model: gemini-3-pro
thinking_budget: high # low | high (Pro supports fewer levels)
AWS Bedrock (Claude)
Bedrock Claude는 Anthropic처럼 토큰 버짓을 사용해요. 문자열 effort 레벨(minimal – max)은 자동으로 매핑돼요:
| Effort level | Token budget |
|---|---|
| minimal | 1,024 |
| low | 2,048 |
| medium | 8,192 |
| high | 16,384 |
| xhigh / max | 32,768 |
models:
bedrock-claude-thinker:
provider: amazon-bedrock
model: global.anthropic.claude-sonnet-4-5-20250929-v1:0
thinking_budget: 8192 # or use an effort level: medium
provider_opts:
region: us-east-1
bedrock-claude-interleaved:
provider: amazon-bedrock
model: global.anthropic.claude-sonnet-4-5-20250929-v1:0
thinking_budget: high
provider_opts:
region: us-east-1
# interleaved_thinking is auto-enabled when thinking_budget is set
Bedrock의 Claude Opus 4.6+는 adaptive thinking이 필요해요 — 이 모델들은 thinking.type=enabled(토큰 버짓)를 거부해요. adaptive 또는 adaptive/<effort> 로 구성하세요; Docker Agent는 이 모델들에서 토큰 버짓과 effort 레벨을 경고와 함께 자동 강제 변환해요:
models:
bedrock-opus-adaptive:
provider: amazon-bedrock
model: global.anthropic.claude-opus-4-8
thinking_budget: adaptive/high
provider_opts:
region: us-east-1
Warning Bedrock thinking 요구 사항 Bedrock Claude는 토큰 기반
thinking_budget값이 1024 이상이고max_tokens보다 작을 것을 요구해요. Docker Agent는 두 조건 중 어느 것이라도 위반되면 경고를 로그하고 버짓을 무시해요. 인터리브 thinking은 Docker Agent가 자동으로 추가하는interleaved-thinking-2025-05-14베타 헤더를 필요로 해요; 그것은 Bedrock 호스팅 Claude 모델에 토큰 thinking 버짓이 설정될 때마다 자동 활성화돼요(adaptive thinking은 스스로 인터리브함).
Docker Model Runner (로컬 모델)
로컬 모델의 경우 thinking_budget 이 추론 엔진으로 전달돼요. 토큰 수와 effort 문자열 모두 동작하고, effort 문자열은 Bedrock과 같은 토큰 눈금(minimal=1024 … xhigh/max=32768)에 매핑되며, adaptive 는 무제한을 뜻해요:
models:
local:
provider: dmr
model: ai/qwen3
thinking_budget: medium # llama.cpp: reasoning-budget=8192; vLLM: thinking_token_budget=8192
- llama.cpp: 모델 구성 시
reasoning-budget으로 전송. - vLLM: 각 요청에서
thinking_token_budget으로 전송. - MLX / SGLang: reasoning-budget 노브가 없어서 값이 조용히 무시됨.
상세는 Docker Model Runner 제공자 페이지 참고.
xAI (Grok)과 Mistral
xAI와 Mistral은 Docker Agent의 OpenAI 호환 클라이언트를 통해 실행되지만, reasoning_effort 파라미터는 OpenAI 추론 모델 이름(o-series, gpt-5)에 대해서만 보내져요. Grok이나 Mistral 모델에 thinking_budget 을 설정하는 것은 현재 효과가 없어요 — 값은 구성 검증에서 받아들여지지만 API에 결코 보내지지 않아요.
Grok과 Mistral 추론 모델(예: grok-3-mini, magistral)은 스스로 추론을 관리해요; 비추론 모델에는 think 도구를 대신 고려하세요.
Thinking 비활성화 (Disabling Thinking)
어떤 제공자든 thinking을 비활성화하려면 none 이나 0 을 사용해요:
models:
fast-model:
provider: openai
model: gpt-5-mini
thinking_budget: none
gemini-no-think:
provider: google
model: gemini-2.5-flash
thinking_budget: 0
none 과 0 은 Docker Agent의 thinking 구성을 지워요 — thinking 파라미터가 보내지지 않아요. 항상 추론하는 모델(OpenAI o-series, gpt-5부터 gpt-5.5, Gemini 3)은 그다음 API의 기본 동작으로 폴백하고 여전히 내부적으로 추론해요; gpt-5.6+(Sol/Terra/Luna)는 none 을 추론을 진짜로 비활성화하는 실제 API 값으로 보내요. 선택적 thinking이 있는 모델(Gemini 2.5, Claude, 로컬 모델)도 완전히 비활성화돼요.
Effort 레벨 선택 (Choosing an Effort Level)
| Task complexity | Recommended level |
|---|---|
| 간단한 사실 Q&A | none / minimal |
| 일반 목적 채팅 | low / medium |
| 코딩, 디버깅, 분석 | medium / high |
| 복잡한 추론, 계획 | high / xhigh |
| 연구, 어려운 수학/로직 | xhigh / max |
| 긴 에이전트 작업 (Anthropic) | adaptive |
런타임에 Thinking 레벨 변경 (Changing Thinking Level at Runtime)
TUI에서 실행하는 동안 Shift+Tab을 눌러 YAML 구성을 편집하지 않고 현재 모델의 thinking effort 레벨을 순환하거나, /effort <level> 을 입력해 특정 레벨로 바로 가세요(예: /effort high). 인자 없이 /effort 를 실행하면 현재 모델이 지원하는 레벨을 나열하는 선택기가 열려요:
- 레벨은 모델의 지원 범위(모델별)를 단계적으로 순환하며 감싸요 — 예를 들어 OpenAI gpt-5/o-series에서
none → minimal → low → medium → high → none, gpt-5.2+에서none → minimal → low → medium → high → xhigh → none, gpt-5.6+에서none → low → medium → high → xhigh → max → none(minimal없음), Anthropic Opus 4.6과 Sonnet 4.6에서none → low → medium → high → max → none, Anthropic Opus 4.7+, Fable 5, Mythos 5에서none → low → medium → high → xhigh → max → none. 토큰 버짓만 받는 이전 Anthropic 모델(예: Sonnet 4.5)에서는 effort-문자열 순환이 효과가 없어요 — YAML 구성에서 정수thinking_budget을 대신 사용하세요. - 현재 레벨은 사이드바에 모델 이름 옆에 표시돼요(예:
openai/gpt-5 • high). - 이것은 세션 재정의로 적용돼요 — 구성 파일에 저장되지 않아요. 다음 세션은 YAML에서 정의된 레벨에서 시작해요.
- 추론을 지원하지 않는 모델과 원격 런타임에서는 Shift+Tab이 no-op이고 정보성 메시지가 표시돼요.
/effort는 현재 모델이 지원하는 레벨만 받아요; 지원되지 않는 레벨을 요청하면 모델의 지원 목록이 표시돼요. Shift+Tab처럼 비추론 모델과 원격 런타임에는 사용할 수 없어요./effort와 공백 뒤에 Tab을 누르면 현재 모델의 지원 범위에서 레벨을 완성해요; 선택기가 보여주는 것과 같은 레벨을 나열해요(그리고 선택기처럼 비추론 모델이나 원격 런타임에는 후보를 제공하지 않아요).
Thinking 구성 공유 (Sharing Thinking Config Across Models)
기본 thinking_budget 으로 제공자를 정의하면 그것을 참조하는 모든 모델이 상속해요:
providers:
deep-anthropic:
provider: anthropic
thinking_budget: adaptive/high
max_tokens: 32768
models:
claude-smart:
provider: deep-anthropic
model: claude-opus-4-6 # inherits thinking_budget: adaptive/high
claude-faster:
provider: deep-anthropic
model: claude-opus-4-6
thinking_budget: low # overrides to adaptive/low
전체 예제 (Full Example)
모든 제공자를 다루는 실행 가능한 구성은 examples/thinking_budget.yaml 참고.