Claude Platform Docs
모델 및 가격Claude Sonnet 5

Claude Sonnet 5로 마이그레이션하기

이전 Claude 모델에서 Claude Sonnet 5로 마이그레이션하기: 모델 ID, 호환성이 깨지는 변경 사항, 마이그레이션 체크리스트.

Claude Sonnet 5는 Claude 모델 제품군에서 속도와 지능의 가장 뛰어난 조합을 제공합니다. Claude Sonnet 4.6을 기반으로 구축되었습니다.

Claude Sonnet 5는 Claude Sonnet 4.6을 그대로 대체할 수 있는 업그레이드이며, 가격은 입력/출력 토큰 백만 개당 $2/$10 USD입니다. 자세한 내용은 가격을 참조하세요. 이미 Claude Sonnet 4.6에서 실행 중인 코드에 대해 호환성이 깨지는 API 변경 사항이 두 가지 있습니다. 첫째, adaptive thinking(적응형 사고)이 기본적으로 켜져 있으며 수동 "extended thinking"(확장 사고)(thinking: {type: "enabled", budget_tokens: N})은 400 오류를 반환합니다. 따라서 사고 없이 실행되던 요청이 이제 첫 번째 text 블록 앞에 thinking 블록을 반환할 수 있으며, 위치로 콘텐츠를 읽는 코드는 type으로 콘텐츠 블록을 선택해야 합니다. 둘째, 기본값이 아닌 값으로 설정된 샘플링 파라미터(temperature, top_p, top_k)는 400 오류를 반환합니다. 사고 깊이를 제어하려면 effort 파라미터와 함께 적응형 사고를 사용하세요. Claude Sonnet 5는 1M 토큰 컨텍스트 윈도우, 적응형 사고, 프롬프트 캐싱, 배치 처리, Files API, PDF 지원, 비전, 그리고 서버 측 및 클라이언트 측 도구 전체를 포함하여 Claude Sonnet 4.6과 동일한 기능 세트를 지원합니다. Claude API 및 Google Cloud에서 Claude Sonnet 5는 안정 버전 computer_toolset_20260801 툴셋으로 컴퓨터 사용을 지원하고, 웹페이지 내부 작업을 위한 브라우저 사용 도구도 지원합니다. 이 두 가지는 Claude Sonnet 4.6에서는 지원되지 않습니다. 이전 computer_20251124 버전을 사용하는 기존 통합은 두 모델 모두에서 변경 없이 계속 작동합니다. 기존 통합을 업그레이드하려면 computer_20251124에서 마이그레이션하기를 참조하세요. Priority Tier는 Claude Sonnet 5에서 사용할 수 없습니다. Claude Sonnet 5는 또한 새로운 토크나이저를 사용합니다.

Claude Sonnet 4.6에서 Claude Sonnet 5로 마이그레이션하기

모델 이름 업데이트

# Sonnet 마이그레이션
model = "claude-sonnet-4-6"  # Before
model = "claude-sonnet-5"  # After

변경된 사항

다음 목록의 4번과 5번 항목은 호환성이 깨지는 변경 사항입니다. max_tokens는 여전히 총 출력(사고 + 응답 텍스트)에 대한 엄격한 한도이므로, Claude Sonnet 4.6에서 사고 없이 실행되던 워크로드에 대해서는 이를 다시 검토하세요.

  1. 새로운 토크나이저: Claude Sonnet 5는 새로운 토크나이저를 사용합니다. 동일한 입력 텍스트가 Claude Sonnet 4.6보다 약 30% 더 많은 토큰을 생성합니다. 정확한 증가량은 콘텐츠에 따라 다릅니다. 요청, 응답, 스트리밍 이벤트는 동일한 형태를 유지하며 코드 변경은 필요하지 않지만, 토큰 단위로 측정하거나 예산을 책정하는 모든 것이 달라집니다. 동일한 텍스트에 대한 usage 필드와 토큰 카운팅 결과가 더 높아지고, 1M 토큰 컨텍스트 윈도우에 담을 수 있는 텍스트가 줄어들며, Claude Sonnet 4.6에 맞춰 조정된 max_tokens 한도는 동등한 출력을 잘라낼 수 있습니다. 토큰당 가격은 더 낮지만(Claude Sonnet 4.6의 입력/출력 토큰 백만 개당 $3/$15 USD 대비 $2/$10 USD), 동등한 요청의 비용이 정비례로 감소하지는 않습니다. 이전 모델에서 측정한 카운트를 재사용하지 말고 Claude Sonnet 5에 대해 토큰 카운팅을 다시 실행하세요.

  2. 128k 최대 출력 토큰(변경 없음): Claude Sonnet 5는 Claude Sonnet 4.6과 동일하게 최대 128k 출력 토큰을 지원합니다. 기존 max_tokens 값은 그대로 유효합니다. 크기를 정할 때 새로운 토크나이저를 고려하세요.

  3. 어시스턴트 메시지 프리필(변경 없음): 어시스턴트 메시지를 프리필하면 Claude Sonnet 4.6과 마찬가지로 Claude Sonnet 5에서도 400 오류가 반환됩니다. Claude Sonnet 4.6으로 마이그레이션할 때 프리필을 제거했다면 추가 변경은 필요하지 않습니다. 대신 구조화된 출력, 시스템 프롬프트 지침 또는 output_config.format을 사용하세요.

  4. 적응형 사고 기본 활성화: Claude Sonnet 4.6에서는 thinking 필드가 없는 요청이 사고 없이 실행되지만, Claude Sonnet 5에서는 동일한 요청이 적응형 사고와 함께 실행됩니다. 사고를 끄려면 thinking: {type: "disabled"}를 전달하세요. 수동 확장 사고(thinking: {type: "enabled", budget_tokens: N})는 지원되지 않으며 400 오류를 반환합니다. 사고 깊이를 제어하려면 effort 파라미터(기본값 high)를 사용하세요.

    사고가 켜져 있으면 응답이 첫 번째 text 블록 앞에 하나 이상의 thinking 블록으로 시작할 수 있으며, 기본값 display: "omitted"에서는 빈 thinking 필드와 함께 반환됩니다. content[0].text와 같이 위치로 응답을 읽는 코드나 첫 번째 콘텐츠 블록을 텍스트로 취급하는 스트림 핸들러는 대신 type 필드로 콘텐츠 블록을 선택해야 하며, 도구 사용 루프는 thinking 블록을 도구 결과와 함께 완전하고 수정되지 않은 상태로 다시 전달해야 합니다(사고 블록 보존 참조). 사고 토큰은 사고 텍스트가 반환되지 않더라도 출력 토큰으로 청구됩니다. Claude Sonnet 4.6에서 사고를 사용하고 반환된 사고 텍스트를 표시했다면, thinking.display의 기본값이 Claude Sonnet 4.6에서는 "summarized"였고 Claude Sonnet 5에서는 "omitted"라는 점에 유의하세요. 읽을 수 있는 요약을 계속 받으려면 다음 예제처럼 display: "summarized"를 설정하세요(사고 표시 제어 참조).

    client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    output_config={"effort": "high"},
    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}")

  5. 샘플링 파라미터 제거: 기본값이 아닌 값으로 설정된 샘플링 파라미터(temperature, top_p, top_k)는 허용되지 않으며 400 오류를 반환합니다.

  6. 사이버 보안 안전장치: Claude Sonnet 5는 실시간 사이버 보안 안전장치를 갖춘 최초의 Sonnet 등급 모델입니다. 금지되거나 고위험 사이버 보안 주제와 관련된 요청은 거부될 수 있습니다. 거부는 오류가 아니라 stop_reason: "refusal"이 포함된 성공적인 HTTP 200 응답으로 반환됩니다. 안전장치가 차단하는 내용과 합법적인 보안 작업이 Cyber Verification Program에 신청하는 방법은 Claude Opus 및 Sonnet의 실시간 사이버 안전장치를 참조하세요.

마이그레이션 체크리스트

  • 모델 이름을 claude-sonnet-4-6에서 claude-sonnet-5로 업데이트하세요.
  • Claude Sonnet 5에 대해 토큰 카운팅을 다시 실행하세요. 새로운 토크나이저는 동일한 텍스트에 대해 약 30% 더 많은 토큰을 생성하므로, 토큰당 가격이 더 낮더라도 요청당 비용이 달라질 수 있습니다. 정확한 증가량은 콘텐츠와 워크로드 형태에 따라 다릅니다.
  • 예상 출력 길이에 가깝게 설정된 max_tokens 한도를 다시 검토하고, 유용한 경우 최대 128k(Claude Sonnet 4.6과 동일)까지 높이세요.
  • thinking: {type: "enabled", budget_tokens: N} 구성을 제거하세요(400 오류 반환). 적응형 사고는 기본적으로 켜져 있습니다. 끄려면 {type: "disabled"}를 전달하거나, 깊이를 제어하려면 effort 파라미터를 사용하세요.
  • content[0].text와 같이 위치로 콘텐츠를 읽는 응답 파싱을 업데이트하세요. 사고가 켜져 있으면 thinking 블록이 text 블록보다 먼저 도착합니다. 대신 type으로 콘텐츠 블록을 선택하고, 도구 사용 루프에서 thinking 블록을 수정하지 않은 상태로 다시 전달하세요. 수정된 블록은 400 오류를 반환합니다.
  • thinking 필드를 파싱하는 모든 코드가 이를 표시용 텍스트로만 취급하는지 확인하세요. thinking.display는 Claude Sonnet 5에서 기본값이 "omitted"이므로(Claude Sonnet 4.6에서는 "summarized"가 기본값이었음) 사고 블록이 빈 thinking 필드와 함께 도착합니다. 읽을 수 있는 요약을 받으려면 display: "summarized"를 설정하세요. 사고 표시 제어를 참조하세요.
  • 기본값이 아닌 값으로 설정된 temperature, top_p, top_k 파라미터를 제거하세요(Claude Sonnet 5에서 400 오류를 반환합니다).
  • 워크로드가 사이버 보안 주제를 다룰 수 있다면 stop_reason: "refusal"에 대한 처리를 추가하세요.
  • 프로덕션 배포 전에 일반적인 워크로드에서 비용 기준선을 다시 설정하세요.
  • 이전에 사고 없이 실행되던 워크로드에 대해 max_tokens를 검토하세요.

Claude Sonnet 4.5 및 이전 Sonnet 모델에서 Claude Sonnet 5로 마이그레이션하기

Claude Sonnet 4.5 또는 이전 Sonnet 모델에서 Claude Sonnet 5로 직접 마이그레이션하는 경우, Claude Sonnet 4.6에서 Claude Sonnet 5로 마이그레이션하기의 변경 사항과 이 섹션의 변경 사항을 함께 적용하세요.

호환성이 깨지는 변경 사항

Sonnet 4.5에서 마이그레이션하는 경우

  1. 어시스턴트 메시지 프리필이 더 이상 지원되지 않음

    어시스턴트 메시지를 프리필하면 Claude Sonnet 5를 포함한 Claude Sonnet 4.6 이후 모델에서 400 오류가 반환됩니다. 대신 구조화된 출력, 시스템 프롬프트 지침 또는 output_config.format을 사용하세요.

    일반적인 프리필 사용 사례 및 마이그레이션:

    • 출력 형식 제어(JSON/YAML 출력 강제): 구조화된 출력을 사용하거나, 분류 작업의 경우 enum 필드가 있는 도구를 사용하세요.

    • 서두 제거("Here is..." 문구 제거): 시스템 프롬프트에 직접적인 지침을 추가하세요: "Respond directly without preamble. Do not start with phrases like 'Here is...', 'Based on...', etc."

    • 부적절한 거부 방지: Claude는 이제 적절한 거부를 훨씬 더 잘 수행합니다. 프리필 없이 사용자 메시지에서 명확하게 프롬프트하는 것으로 충분합니다.

    • 이어쓰기(중단된 응답 재개): 이어쓰기를 사용자 메시지로 옮기세요: "Your previous response was interrupted and ended with [previous_response]. Continue from where you left off."

    • 컨텍스트 하이드레이션 / 역할 일관성(긴 대화에서 컨텍스트 새로 고침): 이전에 프리필된 어시스턴트 리마인더였던 내용을 대신 사용자 턴에 주입하세요.

  2. 도구 파라미터 JSON 이스케이프가 다를 수 있음

    도구 파라미터의 JSON 문자열 이스케이프가 이전 모델과 다를 수 있습니다. 표준 JSON 파서는 이를 자동으로 처리하지만, 사용자 정의 문자열 기반 파싱은 업데이트가 필요할 수 있습니다.

확장 사고 변경 사항: Claude Sonnet 4.5의 budget_tokens 구성(thinking: {type: "enabled", budget_tokens: N})은 Claude Sonnet 5에서 지원되지 않으며 400 오류를 반환합니다. 적응형 사고가 기본적으로 켜져 있으므로 대부분의 워크로드는 thinking 구성이 전혀 필요하지 않습니다. 사고 깊이를 제어하려면 effort 파라미터를 사용하세요. 확장 사고 없이 Claude Sonnet 4.5를 실행했다면 해당 동작을 유지하기 위해 thinking: {type: "disabled"}를 전달하세요.

Claude 3.x에서 마이그레이션하는 경우

  1. 샘플링 파라미터 제거

    기본값이 아닌 값으로 설정된 샘플링 파라미터(temperature, top_p, top_k)는 Claude Sonnet 5에서 400 오류를 반환합니다. 요청에서 이를 제거하고, 대신 프롬프트를 사용하여 모델의 동작을 안내하세요.

  2. 도구 버전 업데이트

    최신 도구 버전(text_editor_20250728, code_execution_20260521)으로 업데이트하세요. undo_edit 명령을 사용하는 모든 코드를 제거하세요.

  3. refusal 중지 사유 처리

    refusal 중지 사유를 처리하도록 애플리케이션을 업데이트하세요.

  4. 동작 변경에 맞춰 프롬프트 업데이트

    Claude 4 모델은 더 간결하고 직접적인 커뮤니케이션 스타일을 가지고 있습니다. 최적화 지침은 프롬프트 모범 사례를 검토하세요.

Claude Haiku 4.5에서 Claude Sonnet 5로 마이그레이션하기

Claude Haiku 4.5와 Claude Sonnet 5는 같은 등급 내의 인접 모델들보다 API 수준에서 더 많은 차이가 있습니다. Claude Haiku 4.5는 수동 확장 사고(기본적으로 꺼짐), 200k 토큰 컨텍스트 윈도우, 최대 64k 출력 토큰을 사용하는 반면, Claude Sonnet 5는 기본적으로 적응형 사고가 켜진 상태로 실행되고, 기본적으로 1M 토큰 컨텍스트 윈도우를 제공하며, 최대 128k 출력 토큰을 지원합니다.

모델 이름 업데이트

model = "claude-haiku-4-5-20251001"  # Before
model = "claude-sonnet-5"  # After

변경된 사항

  1. 사고 구성: Claude Haiku 4.5는 수동 확장 사고(thinking: {type: "enabled", budget_tokens: N})를 지원하고 thinking: {type: "adaptive"}를 거부합니다. Claude Sonnet 5에서는 지원이 반대입니다. 적응형 사고가 기본적으로 켜져 있고, 수동 확장 사고는 400 오류를 반환합니다. thinking: {type: "enabled", budget_tokens: N} 구성을 제거하고 기본값에 의존하거나, 사고를 끄려면 thinking: {type: "disabled"}를 전달하세요. budget_tokens에는 직접적인 대체 항목이 없습니다. 사고 깊이를 제어하려면 effort 파라미터를 사용하세요. Effort는 Claude Haiku 4.5에서는 사용할 수 없으며 Claude Sonnet 5에서는 기본값이 high입니다.

    두 종류의 Claude Haiku 4.5 요청 모두에 대해 응답 형태가 변경됩니다. 확장 사고 없이 실행되던 요청은 이제 첫 번째 text 블록 앞에 하나 이상의 thinking 블록을 반환할 수 있으므로, content[0].text와 같이 위치로 응답을 읽는 코드는 대신 type 필드로 콘텐츠 블록을 선택해야 하며, 도구 사용 루프는 thinking 블록을 도구 결과와 함께 완전하고 수정되지 않은 상태로 다시 전달해야 합니다(사고 블록 보존 참조). 확장 사고를 사용하던 요청은 계속 thinking 블록을 받지만, thinking.display의 기본값이 Claude Sonnet 5에서는 "summarized"가 아닌 "omitted"이므로 해당 블록이 빈 thinking 필드와 함께 도착합니다. 읽을 수 있는 요약을 계속 받으려면 display: "summarized"를 설정하세요(사고 표시 제어 참조). 사고 토큰은 사고 텍스트가 반환되지 않더라도 출력 토큰으로 청구됩니다.

  2. 샘플링 파라미터 제거: temperature와 top_p는 Claude Haiku 4.5에서 작동합니다(둘 다가 아닌 한 번에 하나씩). Claude Sonnet 5에서는 temperature, top_p 또는 top_k를 기본값이 아닌 값으로 설정하면 400 오류가 반환됩니다. 이러한 파라미터를 제거하고 프롬프트를 사용하여 모델의 동작을 안내하세요.

  3. 어시스턴트 프리필 제거: 어시스턴트 메시지 프리필은 Claude Haiku 4.5에서는 작동하지만 Claude Sonnet 5에서는 400 오류를 반환합니다. 대신 구조화된 출력, 시스템 프롬프트 지침 또는 output_config.format을 사용하세요.

  4. 더 큰 컨텍스트 윈도우 및 출력: Claude Sonnet 5는 기본적으로 1M 토큰 컨텍스트 윈도우를 제공하며(Claude Haiku 4.5의 200k 토큰에서 증가), 최대 128k 출력 토큰을 지원합니다(64k에서 증가). Claude Sonnet 5는 또한 다른 토크나이저를 사용하므로, Claude Haiku 4.5에서 측정한 카운트를 재사용하지 말고 토큰 카운팅을 다시 실행하세요.

  5. 가격: Claude Haiku 4.5의 가격은 입력/출력 토큰 백만 개당 $1/$5 USD입니다. Claude Sonnet 5의 가격은 입력/출력 토큰 백만 개당 $2/$10 USD입니다. Claude 가격을 참조하세요.

  6. 사이버 보안 안전장치: Claude Sonnet 5에는 실시간 사이버 보안 안전장치가 있습니다. 금지되거나 고위험 사이버 보안 주제와 관련된 요청은 거부될 수 있으며, stop_reason: "refusal"이 포함된 성공적인 HTTP 200 응답으로 반환됩니다. 안전장치가 차단하는 내용과 합법적인 보안 작업이 Cyber Verification Program에 신청하는 방법은 Claude Opus 및 Sonnet의 실시간 사이버 안전장치를 참조하세요.

마이그레이션 체크리스트

  • 모델 이름을 claude-haiku-4-5-20251001(또는 claude-haiku-4-5 별칭)에서 claude-sonnet-5로 업데이트하세요.
  • thinking: {type: "enabled", budget_tokens: N} 구성을 제거하세요(400 오류 반환). 적응형 사고는 기본적으로 켜져 있습니다. 사고 없는 동작을 유지하려면 thinking: {type: "disabled"}를 전달하고, 사고 없이 실행되던 워크로드에 대해 max_tokens를 다시 검토하세요.
  • content[0].text와 같이 위치로 콘텐츠를 읽는 응답 파싱을 업데이트하세요. 사고가 켜져 있으면 thinking 블록이 text 블록보다 먼저 도착합니다. 대신 type으로 콘텐츠 블록을 선택하고, 도구 사용 루프에서 thinking 블록을 수정하지 않은 상태로 다시 전달하세요. 수정된 블록은 400 오류를 반환합니다.
  • UI에서 사고 콘텐츠를 표시한다면 display: "summarized"를 설정하세요. thinking.display는 Claude Sonnet 5에서 기본값이 "omitted"이므로, 그렇지 않으면 사고 블록이 빈 thinking 필드와 함께 도착합니다. 사고 표시 제어를 참조하세요.
  • 사고 깊이와 토큰 소비를 제어하려면 effort 파라미터(기본값 high)를 사용하세요. Claude Haiku 4.5에서는 사용할 수 없으므로 이어받을 기존 설정이 없습니다.
  • temperature 및 top_p 설정을 제거하세요(기본값이 아닌 값은 Claude Sonnet 5에서 400 오류를 반환합니다).
  • 모든 어시스턴트 메시지 프리필을 제거하세요(Claude Sonnet 5에서 400 오류를 반환합니다).
  • Claude Sonnet 5에 대해 토큰 카운팅을 다시 실행하고, 최대 128k까지 높일 수 있는 max_tokens 한도를 다시 검토하세요.
  • 워크로드가 사이버 보안 주제를 다룰 수 있다면 stop_reason: "refusal"에 대한 처리를 추가하세요.
  • 프로덕션 배포 전에 일반적인 워크로드에서 비용 기준선을 다시 설정하세요. 토큰당 가격이 다릅니다.

Was this page helpful?