Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
"zero data retention"(제로 데이터 보존), 즉 ZDR이 이 기능에 어떻게 적용되는지는 API 및 데이터 보존을 참조하세요.
Extended thinking(확장 사고) (thinking.type: "enabled" 및 budget_tokens)은 Claude 4.6 모델에서 더 이상 사용되지 않습니다(이를 사용하는 요청은 여전히 성공합니다). Claude 4.7 및 이후 모델은 이를 지원하지 않으며 이를 사용하는 요청을 거부하고 400 오류를 반환합니다. 사고를 지원하는 Claude 4.5 및 이전 모델에서는 확장 사고가 유일하게 사용 가능한 사고 모드입니다. Claude Mythos Preview는 두 모드를 모두 지원합니다. 두 모드를 모두 사용할 수 있는 경우 적응형 사고를 대신 사용하세요.
적응형 사고로 전환하려면 적응형 사고로 마이그레이션을 참조하세요. 모델이 확장 사고만 지원하는 경우, 이 페이지에서 지원되는 구성을 설명합니다. 최신 모델로 전환하기 전까지는 변경이 필요하지 않습니다.
요청이 "thinking.type.enabled" is not supported로 시작하는 메시지와 함께 400 오류로 실패하는 경우, 해당 모델은 적응형 사고를 대신 사용합니다. 사고 문제 해결을 참조하거나 적응형 사고로 마이그레이션으로 이동하세요.
수동 모드의 확장 사고는 Claude가 얼마나 사고할지를 직접 제어할 수 있게 해줍니다. 각 요청에서 thinking: {type: "enabled", budget_tokens: N}으로 사고 토큰 예산을 설정하면, Claude는 최종 답변을 시작하기 전에 해당 예산 내에서 사고합니다. 수동 모드는 워크로드에 예측 가능한 지연 시간이나 사고 비용에 대한 정밀한 제어가 필요한 경우 여전히 유용합니다. 이 페이지에서는 예산을 설정하고 조정하는 방법, 수동 모드가 인터리브 사고 및 프롬프트 캐싱과 상호작용하는 방식, 그리고 적응형 사고로 마이그레이션하는 방법을 다룹니다.
사고 블록과 응답 형태, display 매개변수, 스트리밍, 도구 사용과 함께하는 사고, 암호화를 포함하여 사고 자체가 작동하는 방식에 대해서는 사고 개요를 참조하세요.
확장 사고가 유일한 모드인 모델을 포함하여 모델별 확장 사고 가용성은 모델별 구성 표에 나열되어 있습니다.
다음은 Messages API에서 확장 사고를 사용하는 예시입니다:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[
{
"role": "user",
"content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
}
],
)
# 응답에는 요약된 사고 블록과 텍스트 블록이 포함됩니다
for block in response.content:
match block.type:
case "thinking":
print(f"\nThinking summary: {block.thinking}")
case "text":
print(f"\nResponse: {block.text}")수동 확장 사고를 켜려면 type을 enabled로 설정하고 budget_tokens 값을 포함한 thinking 객체를 추가하세요.
budget_tokens 매개변수는 Claude가 내부 추론 과정에 사용할 수 있는 토큰 수의 목표를 설정합니다. 더 큰 예산은 복잡한 문제에 대해 더 철저한 분석을 가능하게 하여 응답 품질을 향상시킬 수 있습니다.
budget_tokens는 다음 제약 조건을 충족해야 합니다:
max_tokens보다 작아야 합니다. 사고 토큰은 해당 턴의 max_tokens 제한에 포함되므로, 예산은 최종 응답을 위한 여유를 남겨야 합니다. 유일한 예외는 인터리브 사고로, 예산이 하나의 어시스턴트 턴 내의 모든 사고 블록에 걸쳐 적용되기 때문에 budget_tokens가 max_tokens를 초과할 수 있습니다.budget_tokens는 max_tokens보다 작아야 하므로, 확장 사고는 max_tokens: 0(캐시 사전 워밍)과 결합할 수 없습니다.예산은 엄격한 상한이 아니라 목표입니다. 실제 토큰 사용량은 작업에 따라 달라지며, Claude는 예산이 소진되기 훨씬 전에 추론을 중단할 수 있습니다. max_tokens는 총 출력에 대한 엄격한 상한으로 유지됩니다.
effort를 지원하는 유일한 확장 사고 전용 모델인 Claude Opus 4.5에서는 effort가 전체 응답을 형성하고 budget_tokens가 사고 깊이를 설정하므로, 둘 다 설정하세요.
예산을 조정하려면:
예산이 실제로 얼마나 비용이 드는지 추적하려면 응답의 usage.output_tokens_details.thinking_tokens 필드를 모니터링하세요. 이 필드는 청구된 출력 토큰 중 내부 추론에 사용된 토큰 수를 보고합니다. 스트리밍 시 이 세부 정보는 최종 message_delta 이벤트에만 나타납니다.
수동 예산에서 벗어날 준비가 되면 적응형 사고로 마이그레이션을 참조하세요.
인터리브 사고(interleaved thinking)는 Claude가 단일 어시스턴트 턴 내에서 도구 호출 사이에 사고하여, 다음에 무엇을 할지 결정하기 전에 각 도구 결과에 대해 추론할 수 있게 합니다. 개념, 턴 구조, 적응형 사고 모델에서의 동작 방식에 대해서는 사고 개요의 인터리브 사고를 참조하세요. 이 섹션에서는 수동 type: "enabled" 사고를 사용할 때 이를 활성화하는 방법을 다룹니다.
Claude Opus 4.5, Claude Sonnet 4.5 및 이전 Claude 4 모델(Claude Opus 4.1(지원 중단됨), Claude Opus 4, Claude Sonnet 4)에서는 API 요청에 interleaved-thinking-2025-05-14 베타 헤더를 추가하세요.
4.6 세대는 수동 모드에서 다음과 같이 나뉩니다:
type: "enabled"와 함께 사용하는 베타 헤더는 여전히 작동하지만 지원 중단되었습니다. 헤더 없이 자동으로 인터리브되는 적응형 사고를 사용하는 것이 좋습니다.thinking: {type: "adaptive"}로 전환하세요.Claude Haiku 4.5는 인터리브 사고를 지원하지 않습니다. Claude API에서는 베타 헤더가 허용되지만 무시됩니다.
수동 모드에서 인터리브 사고에 대한 두 가지 추가 고려 사항:
budget_tokens가 max_tokens를 초과할 수 있습니다. 예산 규칙에서 이 예외를 설명합니다.플랫폼마다 베타 헤더를 처리하는 방식이 다릅니다. Claude API와 Claude Platform on AWS는 모든 모델에서 interleaved-thinking-2025-05-14를 허용하고 지원되지 않는 경우 무시합니다. 허용이 효과와 동일한 것은 아닙니다. type: "enabled"를 거부하는 모델(4.7 이상)이나 수동 모드 인터리빙이 없는 모델(Claude Opus 4.6)에서는 헤더가 수동 모드에 아무런 효과가 없으며, 적응형 사고가 자동으로 인터리브됩니다.
파트너 운영 플랫폼(Amazon Bedrock 및 Google Cloud)도 마찬가지로 오류를 반환하지 않고 모든 모델에서 헤더를 허용하며, 인터리브 사고를 지원하지 않는 모델에서는 무시합니다.
단일 턴 도구 사용 루프, 턴 중간 충돌 처리, 턴 간 사고 전환을 포함한 일반적인 턴 구조 규칙은 도구 사용과 함께하는 사고에 있습니다.
수동 모드는 한 가지 요구 사항을 추가합니다. 사고가 활성화된 요청의 최종 어시스턴트 턴은 사고 블록으로 시작해야 합니다(적응형 사고는 이 요구 사항을 제거합니다). 턴 사이에 사고 구성을 변경하면 프롬프트 캐싱도 무효화됩니다. 다음 섹션을 참조하세요.
수동 모드는 사고와 프롬프트 캐싱에 설명된 모드 중립적 캐싱 동작 위에 한 가지 규칙을 추가합니다. 요청 간에 budget_tokens를 변경하면 사고 모드를 전환하는 것과 마찬가지로 캐시 중단점이 무효화됩니다. 예산 값이 프롬프트에 렌더링되기 때문입니다. 예산 변경 후 메시지 수준 중단점은 항상 미스가 발생하며, 도구 및 시스템 프롬프트 중단점도 미스가 발생하는지 여부는 모델이 구성을 렌더링하는 위치에 따라 달라집니다.
실제로는 예산을 선택하고 캐시된 대화가 지속되는 동안 안정적으로 유지하세요. Claude Sonnet 4.6에서 메시지 수준 캐싱으로 다중 턴 대화를 실행하고 세 번째 요청에서 예산을 4,000에서 8,000 토큰으로 변경하면 무효화를 직접 확인할 수 있습니다:
First request - establishing cache
First response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }
Second request - same thinking parameters (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }
Third request - different thinking budget (cache miss expected)
Third response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }세 번째 요청은 요청 간에 예산이 변경되었기 때문에 캐시를 다시 생성합니다(cache_creation_input_tokens=1370, cache_read_input_tokens=0). effort 수준이 여기서 budget_tokens가 하는 캐시 역할을 수행하는 적응형 모드에서 동일한 실험의 실행 가능한 버전은 스티어링 페이지의 프롬프트 캐싱을 참조하세요.
대부분의 사고 동작은 모드 중립적이며 사고 페이지에 한 번 문서화되어 있습니다. 거기에 있는 모든 내용은 수동 모드에도 적용됩니다:
모델이 확장 사고만 지원하는 경우(Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5 및 이전 Claude 4 모델), 지금은 조치가 필요하지 않습니다. 해당 모델에서는 적응형 사고를 사용할 수 없으며, type: "adaptive"는 400 오류를 반환합니다. 적응형 사고를 지원하는 모델로 전환할 때까지 budget_tokens를 유지한 다음, 아래의 매핑을 적용하세요.
다음의 경우 type: "enabled"에서 마이그레이션해야 합니다:
budget_tokens가 지원 중단된 Claude Opus 4.6 또는 Claude Sonnet 4.6을 사용하는 경우.type: "enabled"가 400 오류를 반환하는 Claude Opus 4.7, Claude Opus 4.8, Claude Opus 5, Claude Sonnet 5, Claude Fable 5 또는 Claude Mythos 5로 전환하는 경우.매핑은 간단합니다. budget_tokens를 제거하고, thinking: {type: "adaptive"}를 설정하고, 토큰 예산 대신 output_config: {effort: ...}로 추론 깊이를 제어하세요.
{
"model": "claude-sonnet-4-6",
"max_tokens": 16000,
"thinking": {
"type": "enabled",
"budget_tokens": 10000
}
}는 다음과 같이 변경됩니다:
{
"model": "claude-sonnet-4-6",
"max_tokens": 16000,
"thinking": {
"type": "adaptive"
},
"output_config": {
"effort": "high"
}
}effort: "high"는 API 기본값과 일치합니다. 여기서는 깊이 제어가 이제 어디에 있는지 보여주기 위해서만 표시되며, 생략해도 동일한 동작이 발생합니다.
단순한 구문 변경이 아니라 동작의 차이를 예상하세요. 고정 예산을 사용하면 Claude는 모든 요청에서 사고합니다. 적응형 사고를 사용하면 Claude가 각 요청에서 사고할지 여부와 얼마나 사고할지를 결정하며, 낮은 effort 설정에서는 쉬운 입력에 대해 사고를 완전히 건너뛸 수 있습니다. 마이그레이션 후에는 interleaved-thinking-2025-05-14 베타 헤더도 제거할 수 있습니다. 적응형 사고는 자동으로 인터리브되며, Claude API는 이러한 모델에서 헤더를 무시합니다. 사고 블록 보존도 변경됩니다. Claude Opus 4.5와 4.6 이상 번호의 모델은 이전 턴의 사고 블록을 컨텍스트에 유지하고 입력으로 청구하는 반면, Claude Sonnet 4.5, Claude Haiku 4.5 및 이전 모델은 이를 제거했습니다. 모델별 사고 블록 보존을 참조하세요.
모드 전환은 사고 구성 변경이므로, 전환 후 첫 번째 요청은 수동 모드의 프롬프트 캐싱에 설명된 대로 캐시 중단점을 무효화합니다.
전체 안내는 적응형 사고, effort 및 모델 마이그레이션 가이드를 참조하세요.
사고가 작동하는 방식을 알아보세요: 블록, 표시, 스트리밍 및 도구 사용.
Claude가 각 요청에서 언제, 얼마나 사고할지 결정하도록 하세요.
사고 블록을 보존하고 도구 호출 및 턴 전반에 걸쳐 사고를 관리하세요.
Was this page helpful?