확장된 사고로 구축하기
확장된 사고는 Claude 3.7 Sonnet에 복잡한 작업을 위한 향상된 추론 능력을 제공하며, 최종 답변을 제시하기 전에 단계별 사고 과정의 투명성도 제공합니다.
확장된 사고의 작동 방식
확장된 사고가 활성화되면, Claude는 내부 추론을 출력하는 thinking
콘텐츠 블록을 생성합니다. Claude는 최종 응답을 작성하기 전에 이 추론의 통찰력을 통합합니다.
API 응답에는 thinking
과 text
콘텐츠 블록이 모두 포함됩니다.
다중 턴 대화에서는 도구 사용 세션이나 마지막 메시지 위치의 assistant
턴과 관련된 사고 블록만 Claude에게 표시되고 입력 토큰으로 청구됩니다. 이전 assistant
메시지와 관련된 사고 블록은 샘플링 중에 Claude에게 표시되지 않으며 입력 토큰으로 청구되지 않습니다.
확장된 사고 구현하기
API 요청에 thinking
매개변수와 확장된 사고에 사용할 지정된 토큰 예산을 추가하세요.
budget_tokens
매개변수는 Claude가 내부 추론 프로세스에 사용할 수 있는 최대 토큰 수를 결정합니다. 더 큰 예산은 복잡한 문제에 대해 더 철저한 분석을 가능하게 하여 응답 품질을 향상시킬 수 있지만, 특히 32K 이상의 범위에서는 Claude가 할당된 전체 예산을 사용하지 않을 수 있습니다.
budget_tokens
는 항상 지정된 max_tokens
보다 작아야 합니다.
API 응답에는 사고와 텍스트 콘텐츠 블록이 모두 포함됩니다:
사고 블록 이해하기
사고 블록은 Claude의 내부 사고 과정을 나타냅니다. Claude가 안전 기준과 상태가 없는 API를 유지하면서 최소한의 내부 제한으로 문제를 해결할 수 있도록 하기 위해 다음과 같이 구현했습니다:
- 사고 블록에는
signature
필드가 포함됩니다. 이 필드는 사고 블록이 Claude에 의해 생성되었음을 확인하는 암호화 토큰을 보유하며, 사고 블록이 API로 다시 전달될 때 확인됩니다. 응답을 스트리밍할 때 서명은content_block_stop
이벤트 직전에content_block_delta
이벤트 내의signature_delta
를 통해 추가됩니다. 도구 사용과 확장된 사고를 함께 사용할 때만 사고 블록을 다시 보내는 것이 엄격히 필요합니다. 그렇지 않으면 이전 턴의 사고 블록을 생략하거나, API가 이를 제거하도록 할 수 있습니다. - 때때로 Claude의 내부 추론이 안전 시스템에 의해 플래그가 지정될 수 있습니다. 이런 경우,
thinking
블록의 일부 또는 전체를 암호화하여redacted_thinking
블록으로 반환합니다. 이러한 수정된 사고 블록은 API로 다시 전달될 때 복호화되어 Claude가 컨텍스트를 잃지 않고 응답을 계속할 수 있습니다.
다음은 일반 및 수정된 사고 블록을 모두 보여주는 예시입니다:
출력에서 수정된 사고 블록을 보는 것은 예상된 동작입니다. 모델은 안전 가드레일을 유지하면서 이 수정된 추론을 사용하여 응답을 계속할 수 있습니다.
애플리케이션에서 수정된 사고 처리를 테스트해야 하는 경우, 다음 특별 테스트 문자열을 프롬프트로 사용할 수 있습니다: ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB
다중 턴 대화에서 thinking
및 redacted_thinking
블록을 API로 다시 전달할 때, 마지막 assistant 턴에 대한 완전한 수정되지 않은 블록을 포함해야 합니다.
이는 모델의 추론 흐름을 유지하는 데 중요합니다. 모든 사고 블록을 항상 API로 다시 전달하는 것을 권장합니다. 자세한 내용은 사고 블록 보존 섹션을 참조하세요.
프로덕션에서 수정된 사고 처리를 위한 제안
확장된 사고를 사용하는 고객 대면 애플리케이션을 구축할 때:
- 수정된 사고 블록에는 사람이 읽을 수 없는 암호화된 콘텐츠가 포함되어 있음을 인지하세요
- “Claude의 일부 내부 추론이 안전상의 이유로 자동으로 암호화되었습니다. 이는 응답의 품질에 영향을 미치지 않습니다.”와 같은 간단한 설명을 제공하는 것을 고려하세요
- 사고 블록을 사용자에게 보여줄 때, 일반 사고 블록은 유지하면서 수정된 블록은 필터링할 수 있습니다
- 확장된 사고 기능을 사용하면 일부 추론이 암호화될 수 있다는 점을 투명하게 공개하세요
- UI가 깨지지 않도록 수정된 사고를 우아하게 처리하는 적절한 오류 처리를 구현하세요
확장된 사고 스트리밍
스트리밍이 활성화되면, thinking_delta
이벤트를 통해 사고 콘텐츠를 받게 됩니다. 다음은 사고가 포함된 스트리밍을 처리하는 방법입니다:
스트리밍 출력 예시:
사고가 포함된 스트리밍 동작에 대하여
사고가 활성화된 상태에서 스트리밍을 사용할 때, 텍스트가 때때로 더 작은 토큰별 전달과 번갈아 가며 더 큰 청크로 도착하는 것을 볼 수 있습니다. 이는 특히 사고 콘텐츠에서 예상되는 동작입니다.
스트리밍 시스템은 최적의 성능을 위해 콘텐츠를 배치로 처리해야 하며, 이로 인해 이러한 “청크” 전달 패턴이 발생할 수 있습니다. 우리는 사고 콘텐츠가 더 부드럽게 스트리밍되도록 하는 데 중점을 둔 향후 업데이트를 통해 이 경험을 지속적으로 개선하고 있습니다.
redacted_thinking
블록은 관련된 델타가 없으며 단일 이벤트로 전송됩니다.
확장된 사고 사용 시 중요한 고려사항
사고 예산 작업: 최소 예산은 1,024 토큰입니다. 사용 사례에 대해 Claude가 잘 수행할 수 있는 최적의 범위를 찾기 위해 최소값에서 시작하여 사고 예산을 점진적으로 늘리는 것을 제안합니다. 더 높은 토큰 수를 사용하면 더 포괄적이고 미묘한 추론을 달성할 수 있지만, 작업에 따라 수익이 감소할 수도 있습니다.
- 사고 예산은 엄격한 제한이 아닌 목표입니다 - 실제 토큰 사용량은 작업에 따라 다를 수 있습니다.
- 추론 프로세스에 필요한 추가 처리로 인해 잠재적으로 더 긴 응답 시간에 대비하세요.
max_tokens
가 21,333보다 큰 경우 스트리밍이 필요합니다.
32K 이상의 사고 예산의 경우: 네트워킹 문제를 피하기 위해 사고 예산이 32K 이상으로 설정된 워크로드에는 배치 처리를 사용하는 것이 좋습니다. 모델이 32K 토큰 이상 생각하도록 하는 요청은 시스템 타임아웃과 열린 연결 제한에 부딪힐 수 있는 장시간 실행 요청을 발생시킵니다.
다른 기능과의 사고 호환성:
- 사고는
temperature
,top_p
, 또는top_k
수정 및 강제 도구 사용과 호환되지 않습니다. - 사고가 활성화된 경우 응답을 미리 채울 수 없습니다.
- 사고 예산을 변경하면 메시지가 포함된 캐시된 프롬프트 접두사가 무효화됩니다. 그러나 캐시된 시스템 프롬프트와 도구 정의는 사고 매개변수가 변경되어도 계속 작동합니다.
확장된 사고에 대한 가격 책정 및 토큰 사용
확장된 사고 토큰은 컨텍스트 윈도우에 포함되며 출력 토큰으로 청구됩니다. 사고 토큰은 일반 출력 토큰으로 취급되므로 속도 제한에도 포함됩니다. API 사용을 계획할 때 이러한 증가된 토큰 사용량을 고려하세요.
Claude 3.7 Sonnet의 경우 가격은 다음과 같습니다:
토큰 사용 | 비용 |
---|---|
입력 토큰 | $3 / MTok |
출력 토큰 (사고 토큰 포함) | $15 / MTok |
프롬프트 캐싱 쓰기 | $3.75 / MTok |
프롬프트 캐싱 읽기 | $0.30 / MTok |
확장된 사고를 위한 배치 처리는 이 가격의 50% 할인된 가격으로 제공되며 종종 1시간 미만에 완료됩니다.
모든 확장된 사고 토큰(수정된 사고 토큰 포함)은 출력 토큰으로 청구되며 속도 제한에 포함됩니다.
다중 턴 대화에서 이전 assistant 메시지와 관련된 사고 블록은 입력 토큰으로 청구되지 않습니다.
확장된 사고가 활성화되면 이 기능을 지원하기 위해 28 또는 29 토큰의 특수 시스템 프롬프트가 자동으로 포함됩니다.
확장된 출력 기능 (베타)
Claude 3.7 Sonnet은 최대 128K 출력 토큰을 지원하여 다른 Claude 모델보다 15배 이상 긴 응답을 생성할 수 있습니다(베타). 이 확장된 기능은 복잡한 추론, 풍부한 코드 생성, 포괄적인 콘텐츠 생성과 관련된 확장된 사고 사용 사례에 특히 효과적입니다.
이 기능은 anthropic-beta
헤더에 output-128k-2025-02-19
를 전달하여 활성화할 수 있습니다.
더 긴 출력과 함께 확장된 사고를 사용할 때, 최종 응답을 위한 충분한 토큰을 남겨두면서도 더 철저한 추론을 지원하기 위해 더 큰 사고 예산을 할당할 수 있습니다.
이 확장된 출력 기능과 함께 스트리밍이나 배치 모드를 사용하는 것을 제안합니다. 자세한 내용은 긴 요청에 대한 네트워크 신뢰성 고려사항 가이드를 참조하세요.
프롬프트 캐싱과 함께 확장된 사고 사용하기
사고가 포함된 프롬프트 캐싱에는 몇 가지 중요한 고려사항이 있습니다:
캐시된 프롬프트에 사고 블록 포함
- 사고는 assistant 턴을 생성할 때만 포함되며 캐시되지 않습니다.
- 이전 턴의 사고 블록은 무시됩니다.
- 사고가 비활성화되면 API에 전달된 모든 사고 콘텐츠는 단순히 무시됩니다.
캐시 무효화 규칙
- 사고 매개변수 변경(활성화/비활성화 또는 예산 변경)은 메시지에 설정된 캐시 중단점을 무효화합니다.
- 시스템 프롬프트와 도구는 사고 매개변수가 변경되어도 캐싱을 유지합니다.
확장된 사고가 포함된 프롬프트 캐싱 예시
확장된 사고를 사용한 최대 토큰 및 컨텍스트 윈도우 크기
이전 Claude 모델(Claude 3.7 Sonnet 이전)에서는 프롬프트 토큰과 max_tokens
의 합이 모델의 컨텍스트 윈도우를 초과하면, 시스템이 자동으로 max_tokens
를 컨텍스트 제한 내에 맞도록 조정했습니다. 이는 큰 max_tokens
값을 설정하면 시스템이 필요에 따라 자동으로 이를 줄인다는 것을 의미했습니다.
Claude 3.7 Sonnet에서는 max_tokens
(사고가 활성화된 경우 사고 예산 포함)가 엄격한 제한으로 적용됩니다. 이제 프롬프트 토큰 + max_tokens
가 컨텍스트 윈도우 크기를 초과하면 시스템은 유효성 검사 오류를 반환합니다.
확장된 사고를 사용한 컨텍스트 윈도우 계산 방법
사고가 활성화된 상태에서 컨텍스트 윈도우 사용량을 계산할 때 알아야 할 몇 가지 고려사항이 있습니다:
- 이전 턴의 사고 블록은 제거되어 컨텍스트 윈도우에 포함되지 않습니다
- 현재 턴의 사고는 해당 턴의
max_tokens
제한에 포함됩니다
아래 다이어그램은 확장된 사고가 활성화된 경우의 특수한 토큰 관리를 보여줍니다:
유효한 컨텍스트 윈도우는 다음과 같이 계산됩니다:
특히 사고가 포함된 다중 턴 대화를 다룰 때는 특정 사용 사례에 대한 정확한 토큰 수를 얻기 위해 토큰 계산 API를 사용하는 것을 권장합니다.
더 자세한 내용은 컨텍스트 윈도우 가이드를 참조하세요.
확장된 사고를 사용한 토큰 관리
Claude 3.7 Sonnet과 같은 확장된 사고 모델의 새로운 컨텍스트 윈도우 및 max_tokens
동작으로 인해 다음과 같은 작업이 필요할 수 있습니다:
- 토큰 사용량을 더 적극적으로 모니터링하고 관리
- 프롬프트 길이가 변경됨에 따라
max_tokens
값 조정 - 토큰 계산 엔드포인트를 더 자주 사용
- 이전 사고 블록이 컨텍스트 윈도우에 누적되지 않는다는 점을 인지
이러한 변경은 특히 최대 토큰 제한이 크게 증가함에 따라 더 예측 가능하고 투명한 동작을 제공하기 위해 이루어졌습니다.
도구 사용과 함께 확장된 사고 사용
도구 사용과 함께 확장된 사고를 사용할 때 다음과 같은 동작 패턴을 알아야 합니다:
-
첫 번째 assistant 턴: 초기 사용자 메시지를 보내면 assistant 응답에 사고 블록과 도구 사용 요청이 포함됩니다.
-
도구 결과 턴: 도구 결과 블록이 있는 사용자 메시지를 전달하면, 후속 assistant 메시지에는 추가 사고 블록이 포함되지 않습니다.
여기서 확장하면, 사고가 포함된 도구 사용 대화의 일반적인 순서는 다음 단계를 따릅니다:
- 사용자가 초기 메시지를 보냄
- Assistant가 사고 블록과 도구 요청으로 응답
- 사용자가 도구 결과가 포함된 메시지를 보냄
- Assistant가 더 많은 도구 호출이나 텍스트로만 응답 (이 응답에는 사고 블록이 없음)
- 더 많은 도구가 요청된 경우 대화가 완료될 때까지 3-4단계를 반복
이 설계는 Claude가 도구 요청을 하기 전에 추론 과정을 보여주지만, 도구 결과를 받은 후에는 사고 과정을 반복하지 않도록 합니다. Claude는 다음 비-tool_result
user
턴이 있을 때까지 다른 사고 블록을 출력하지 않습니다.
아래 다이어그램은 도구 사용과 확장된 사고를 결합할 때의 컨텍스트 윈도우 토큰 관리를 보여줍니다:
사고 블록 보존하기
도구 사용 중에는 thinking
및 redacted_thinking
블록을 API로 다시 전달해야 하며, 완전한 수정되지 않은 블록을 API로 다시 포함해야 합니다. 이는 모델의 추론 흐름과 대화 무결성을 유지하는 데 중요합니다.
이전 assistant
역할 턴의 thinking
및 redacted_thinking
블록을 생략할 수 있지만, 다중 턴 대화의 경우 모든 사고 블록을 항상 API로 다시 전달하는 것을 제안합니다. API는:
- 제공된 사고 블록을 자동으로 필터링합니다
- 모델의 추론을 보존하는 데 필요한 관련 사고 블록을 사용합니다
- Claude에게 표시되는 블록의 입력 토큰만 청구합니다
사고 블록을 보존해야 하는 이유
Claude가 도구를 호출할 때, 외부 정보를 기다리기 위해 응답 구성을 일시 중지합니다. 도구 결과가 반환되면 Claude는 기존 응답 구성을 계속합니다. 이는 다음과 같은 이유로 도구 사용 중에 사고 블록을 보존해야 함을 필요로 합니다:
-
추론의 연속성: 사고 블록은 도구 요청으로 이어진 Claude의 단계별 추론을 캡처합니다. 도구 결과를 게시할 때 원래 사고를 포함하면 Claude가 중단된 지점에서 추론을 계속할 수 있습니다.
-
컨텍스트 유지: 도구 결과가 API 구조에서 사용자 메시지로 나타나지만, 이는 연속적인 추론 흐름의 일부입니다. 사고 블록을 보존하면 여러 API 호출에 걸쳐 이 개념적 흐름이 유지됩니다.
중요: thinking
또는 redacted_thinking
블록을 제공할 때, 연속적인 thinking
또는 redacted_thinking
블록의 전체 시퀀스는 원래 요청 중에 모델이 생성한 출력과 일치해야 합니다. 이러한 블록의 시퀀스를 재배열하거나 수정할 수 없습니다.
확장된 사고 모드를 최대한 활용하기 위한 팁
확장된 사고를 최대한 활용하려면:
-
적절한 예산 설정: 복잡한 작업의 경우 더 큰 사고 예산(16,000+ 토큰)으로 시작하고 필요에 따라 조정하세요.
-
사고 토큰 예산 실험: 모델은 다른 최대 사고 예산 설정에서 다르게 수행될 수 있습니다. 최대 사고 예산을 늘리면 지연 시간이 증가하는 대신 모델이 더 잘/더 열심히 생각할 수 있습니다. 중요한 작업의 경우 품질과 성능 사이의 최적의 균형을 찾기 위해 다른 예산 설정을 테스트하는 것을 고려하세요.
-
이전 사고 블록을 직접 제거할 필요가 없습니다: Anthropic API는 이전 턴의 사고 블록을 자동으로 무시하며 컨텍스트 사용량을 계산할 때 포함하지 않습니다.
-
토큰 사용량 모니터링: 비용과 성능을 최적화하기 위해 사고 토큰 사용량을 추적하세요.
-
특히 복잡한 작업에 확장된 사고 사용: 수학, 코딩, 분석과 같이 단계별 추론이 도움이 되는 작업에 사고를 활성화하세요.
-
확장된 응답 시간 고려: 사고 블록 생성이 전체 응답 시간을 증가시킬 수 있다는 점을 고려하세요.
-
스트리밍 적절하게 처리: 스트리밍할 때 사고와 텍스트 콘텐츠 블록이 도착하면 모두 처리할 준비를 하세요.
-
프롬프트 엔지니어링: Claude의 사고 능력을 최대화하려면 확장된 사고 프롬프팅 팁을 검토하세요.