확장 사고 (Extended Thinking)

복잡한 문제를 풀 때 모델이 답만 내놓는 게 아니라, 답을 내기 전에 단계별로 '생각'하도록 만드는 기능이에요. 특히 수학·논리 추론처럼 여러 단계를 거쳐야 하는 작업에서 답 품질이 확 달라져요. 여기서는 요청별로 생각할 토큰을 직접 정하는 수동(manual) 확장 사고를 어떻게 쓰는지, 그리고 더 새 모델에서 권장하는 적응형 사고(adaptive thinking) 로 어떻게 옮기는지 살펴볼게요.

출처: https://platform.claude.com/docs/en/build-with-claude/extended-thinking

확장 사고란

'생각'은 모델이 최종 답을 시작하기 전에 들이는 내부 추론 과정이에요. 확장 사고를 켜면 API 응답에 생각(thinking) 블록과 텍스트 블록이 함께 들어와요. 수동 모드에서는 각 요청에 thinking: {type: "enabled", budget_tokens: N}처럼 생각 토큰 예산을 직접 지정해요. 이렇게 하면 예측 가능한 지연 시간이나 생각 비용을 정밀하게 통제하고 싶은 워크로드에 유리해요.

사용 방법

메시지 API에서 확장 사고를 켜 보면 이렇게 돼요. 요청에 thinking 객체를 추가하고 type을 enabled로, 그리고 생각에 쓸 토큰 수를 budget_tokens로 넣으면 돼요.

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  },
  "messages": [
    {
      "role": "user",
      "content": "n mod 4 == 3인 소수가 무한히 많은가요?"
    }
  ]
}

budget_tokens는 모델의 내부 추론에 얼마나 많은 토큰을 쓸 수 있는지 정하는 목표값이에요. 값이 클수록 복잡한 문제를 더 깊이 분석해서 답 품질이 좋아질 수 있어요.

응답은 생각 블록과 텍스트 블록으로 나뉘어요. Python SDK에서는 block.type이 thinking인지 text인지 보고 각각 출력하면 돼요.

for block in response.content:
    if block.type == "thinking":
        print(f"Thinking summary: {block.thinking}")
    elif block.type == "text":
        print(f"Response: {block.text}")

예산 규칙과 튜닝

budget_tokens는 몇 가지 제약을 지켜야 해요.

최소 1,024 토큰 — 더 작은 값은 API가 거부해요.
max_tokens보다 작아야 해요. 생각 토큰도 한 턴의 max_tokens 한도에 포함되니까, 최종 답을 낼 공간을 남겨 둬야 해요. 다만 인터리브(interleaved) 사고에서는 예외적으로 budget_tokens가 max_tokens보다 커질 수 있는데, 이 경우 한 턴 안의 모든 생각 블록에 예산이 걸쳐지기 때문이에요.
캐시 프리워밍은 못 써요. budget_tokens가 max_tokens보다 작아야 한다는 규칙 때문에, 캐시 프리워밍용 max_tokens: 0과는 함께 쓸 수 없어요.

이 예산은 엄격한 상한이 아니라 목표값이에요. 실제 사용량은 작업에 따라 달라지고, 모델이 예산을 다 쓰기 전에 일찍 멈출 수도 있어요. max_tokens는 그대로 총 출력의 하드 상한으로 남아요.

적응형 사고로 옮기기

Claude 4.6 모델에서는 budget_tokens 방식이 지원 중단되고, Claude 4.7 이후 모델에서는 type: "enabled"가 아예 400 오류를 돌려줘요. 반면 Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5처럼 확장 사고만 지원하는 모델은 type: "adaptive"를 받지 못하니, 그 모델을 쓸 때는 지금의 budget_tokens 설정을 그대로 두면 돼요.

적응형 사고로 옮길 때는 budget_tokens를 지우고 thinking: {type: "adaptive"}를 쓰면서, 생각 깊이는 토큰 예산 대신 output_config: {effort: ...}로 조절해요.

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "adaptive"
  },
  "output_config": {
    "effort": "high"
  }
}

effort: "high"는 API 기본값과 같아요. 고정 예산은 매 요청에서 항상 생각하지만, 적응형 사고는 요청마다 생각할지·얼마나 생각할지를 모델이 결정해요. 낮은 effort에서는 쉬운 입력에 아예 생각을 생략할 수도 있어요. 옮길 때는 문법만 바뀌는 게 아니라 동작도 달라진다는 점을 기억하세요.

더 알아보기

확장 사고를 어떤 모델이 지원하는지는 모델별 지원 표를 봐요.
생각 블록의 응답 구조, 스트리밍, 도구 사용과의 조합은 «Thinking» 문서를 봐요.
모델이 생각 깊이를 스스로 정하도록 하려면 적응형 사고 문서를 봐요.