이 가이드는 Claude 4.5 모델로의 두 가지 주요 마이그레이션 경로를 다룹니다:
  • Claude Sonnet 3.7 → Claude Sonnet 4.5: 최고 수준의 추론, 코딩, 장기 실행 에이전트 기능을 갖춘 가장 지능적인 모델
  • Claude Haiku 3.5 → Claude Haiku 4.5: 실시간 애플리케이션과 대용량 지능형 처리를 위한 최전선급 성능을 제공하는 가장 빠르고 지능적인 Haiku 모델
두 마이그레이션 모두 구현 업데이트가 필요한 주요 변경사항을 포함합니다. 이 가이드는 단계별 지침과 명확히 표시된 주요 변경사항과 함께 각 마이그레이션 경로를 안내합니다. 마이그레이션을 시작하기 전에 Claude 4.5의 새로운 기능을 검토하여 확장된 사고, 컨텍스트 인식, 행동 개선을 포함한 이러한 모델에서 사용할 수 있는 새로운 기능과 역량을 이해하는 것을 권장합니다.

​
Claude Sonnet 3.7에서 Claude Sonnet 4.5로 마이그레이션

Claude Sonnet 4.5는 추론, 코딩, 장기 실행 자율 에이전트에 대해 최고 수준의 성능을 제공하는 가장 지능적인 모델입니다. 이 마이그레이션에는 구현 업데이트가 필요한 여러 주요 변경사항이 포함됩니다.

​
마이그레이션 단계

  1. 모델 이름 업데이트: 
    # 이전 (Claude Sonnet 3.7)
model="claude-3-7-sonnet-20250219"

# 이후 (Claude Sonnet 4.5)
model="claude-sonnet-4-5-20250929"
  2. 샘플링 매개변수 업데이트
    이는 Claude Sonnet 3.7에서의 주요 변경사항입니다.
    temperature 또는 top_p 중 하나만 사용하고, 둘 다 사용하지 마세요: 
    # 이전 (Claude Sonnet 3.7) - Sonnet 4.5에서 오류 발생
response = client.messages.create(
    model="claude-3-7-sonnet-20250219",
    temperature=0.7,
    top_p=0.9,  # 둘 다 사용할 수 없음
    ...
)

# 이후 (Claude Sonnet 4.5)
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    temperature=0.7,  # temperature 또는 top_p 중 하나만 사용
    ...
)
  3. 새로운 refusal 중지 이유 처리 refusal 중지 이유를 처리하도록 애플리케이션을 업데이트하세요: 
    response = client.messages.create(...)

if response.stop_reason == "refusal":
    # 거부를 적절히 처리
    pass
  4. 텍스트 편집기 도구 업데이트 (해당하는 경우)
    이는 Claude Sonnet 3.7에서의 주요 변경사항입니다.
    text_editor_20250728 (타입)과 str_replace_based_edit_tool (이름)로 업데이트하세요. undo_edit 명령을 사용하는 모든 코드를 제거하세요. 
    # 이전 (Claude Sonnet 3.7)
tools=[{"type": "text_editor_20250124", "name": "str_replace_editor"}]

# 이후 (Claude Sonnet 4.5)
tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]
    자세한 내용은 텍스트 편집기 도구 문서를 참조하세요.
  5. 코드 실행 도구 업데이트 (해당하는 경우) code_execution_20250825로 업그레이드하세요. 레거시 버전 code_execution_20250522는 여전히 작동하지만 권장되지 않습니다. 마이그레이션 지침은 코드 실행 도구 문서를 참조하세요.
  6. 토큰 효율적 도구 사용 베타 헤더 제거 토큰 효율적 도구 사용은 Claude 3.7의 베타 기능입니다. 모든 Claude 4 모델에는 내장된 토큰 효율적 도구 사용이 있으므로 더 이상 베타 헤더를 포함하지 않아야 합니다. 요청에서 token-efficient-tools-2025-02-19 베타 헤더를 제거하세요: 
    # 이전 (Claude Sonnet 3.7)
client.messages.create(
    model="claude-3-7-sonnet-20250219",
    betas=["token-efficient-tools-2025-02-19"],  # 이것을 제거
    ...
)

# 이후 (Claude Sonnet 4.5)
client.messages.create(
    model="claude-sonnet-4-5-20250929",
    # token-efficient-tools 베타 헤더 없음
    ...
)
  7. 확장 출력 베타 헤더 제거 확장 출력을 위한 output-128k-2025-02-19 베타 헤더는 Claude Sonnet 3.7에서만 사용할 수 있습니다. 요청에서 이 헤더를 제거하세요: 
    # 이전 (Claude Sonnet 3.7)
client.messages.create(
    model="claude-3-7-sonnet-20250219",
    betas=["output-128k-2025-02-19"],  # 이것을 제거
    ...
)

# 이후 (Claude Sonnet 4.5)
client.messages.create(
    model="claude-sonnet-4-5-20250929",
    # output-128k 베타 헤더 없음
    ...
)
  8. 행동 변화에 대한 프롬프트 업데이트 Claude Sonnet 4.5는 더 간결하고 직접적인 의사소통 스타일을 가지며 명시적인 지시가 필요합니다. 최적화 지침은 Claude 4 프롬프트 엔지니어링 모범 사례를 검토하세요.
  9. 복잡한 작업에 대한 확장된 사고 활성화 고려 코딩 및 추론 작업에서 상당한 성능 향상을 위해 확장된 사고를 활성화하세요 (기본적으로 비활성화됨): 
    response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[...]
)
    확장된 사고는 프롬프트 캐싱 효율성에 영향을 미칩니다.
  10. 구현 테스트 모든 주요 변경사항이 적절히 처리되었는지 확인하기 위해 프로덕션에 배포하기 전에 개발 환경에서 테스트하세요.

​
Sonnet 3.7 → 4.5 마이그레이션 체크리스트

  • 모델 ID를 claude-sonnet-4-5-20250929로 업데이트
  • 주요 변경: 샘플링 매개변수를 temperature 또는 top_p 중 하나만 사용하도록 업데이트
  • 애플리케이션에서 새로운 refusal 중지 이유 처리
  • 주요 변경: 텍스트 편집기 도구를 text_editor_20250728과 str_replace_based_edit_tool로 업데이트 (해당하는 경우)
  • 주요 변경: undo_edit 명령을 사용하는 모든 코드 제거 (해당하는 경우)
  • 코드 실행 도구를 code_execution_20250825로 업데이트 (해당하는 경우)
  • token-efficient-tools-2025-02-19 베타 헤더 제거 (해당하는 경우)
  • output-128k-2025-02-19 베타 헤더 제거 (해당하는 경우)
  • Claude 4 모범 사례에 따라 프롬프트 검토 및 업데이트
  • 복잡한 추론 작업에 대한 확장된 사고 활성화 고려
  • model_context_window_exceeded 중지 이유 처리 (Sonnet 4.5 전용)
  • 장기 실행 에이전트에 대한 메모리 도구 활성화 고려 (베타)
  • 컨텍스트 편집을 위한 자동 도구 호출 지우기 사용 고려 (베타)
  • 프로덕션 배포 전 개발 환경에서 테스트

​
Claude Sonnet 3.7에서 제거된 기능

  • 토큰 효율적 도구 사용: token-efficient-tools-2025-02-19 베타 헤더는 지원되지 않음 (6단계 참조)
  • 확장 출력: output-128k-2025-02-19 베타 헤더는 지원되지 않음 (7단계 참조)
두 헤더 모두 요청에 포함될 수 있지만 효과가 없습니다.

​
Claude Haiku 3.5에서 Claude Haiku 4.5로 마이그레이션

Claude Haiku 4.5는 최전선급 성능을 제공하는 가장 빠르고 지능적인 Haiku 모델로, 대화형 애플리케이션과 대용량 지능형 처리를 위한 실시간 성능과 함께 프리미엄 모델 품질을 제공합니다. 이 마이그레이션에는 구현 업데이트가 필요한 여러 주요 변경사항이 포함됩니다. 새로운 기능에 대한 완전한 개요는 Claude 4.5의 새로운 기능을 참조하세요.
Haiku 4.5 가격은 입력 토큰 백만 개당 1,출력토큰백만개당1, 출력 토큰 백만 개당 5입니다. 자세한 내용은 Claude 가격을 참조하세요.

​
마이그레이션 단계

  1. 모델 이름 업데이트: 
    # 이전 (Haiku 3.5)
model="claude-3-5-haiku-20241022"

# 이후 (Haiku 4.5)
model="claude-haiku-4-5-20251001"
  2. 도구 버전 업데이트 (해당하는 경우)
    이는 Claude Haiku 3.5에서의 주요 변경사항입니다.
    Haiku 4.5는 최신 도구 버전만 지원합니다: 
    # 이전 (Haiku 3.5)
tools=[{"type": "text_editor_20250124", "name": "str_replace_editor"}]

# 이후 (Haiku 4.5)
tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]
    • 텍스트 편집기: text_editor_20250728과 str_replace_based_edit_tool 사용
    • 코드 실행: code_execution_20250825 사용
    • undo_edit 명령을 사용하는 모든 코드 제거
  3. 샘플링 매개변수 업데이트
    이는 Claude Haiku 3.5에서의 주요 변경사항입니다.
    temperature 또는 top_p 중 하나만 사용하고, 둘 다 사용하지 마세요: 
    # 이전 (Haiku 3.5) - Haiku 4.5에서 오류 발생
response = client.messages.create(
    model="claude-3-5-haiku-20241022",
    temperature=0.7,
    top_p=0.9,  # 둘 다 사용할 수 없음
    ...
)

# 이후 (Haiku 4.5)
response = client.messages.create(
    model="claude-haiku-4-5-20251001",
    temperature=0.7,  # temperature 또는 top_p 중 하나만 사용
    ...
)
  4. 새로운 속도 제한 검토 Haiku 4.5는 Haiku 3.5와 별도의 속도 제한을 가집니다. 자세한 내용은 속도 제한 문서를 참조하세요.
  5. 새로운 refusal 중지 이유 처리 거부 중지 이유를 처리하도록 애플리케이션을 업데이트하세요.
  6. 복잡한 작업에 대한 확장된 사고 활성화 고려 코딩 및 추론 작업에서 상당한 성능 향상을 위해 확장된 사고를 활성화하세요 (기본적으로 비활성화됨): 
    response = client.messages.create(
    model="claude-haiku-4-5-20251001",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 5000},
    messages=[...]
)
    확장된 사고는 프롬프트 캐싱 효율성에 영향을 미칩니다.
  7. 새로운 기능 탐색 컨텍스트 인식, 증가된 출력 용량 (64K 토큰), 더 높은 지능, 향상된 속도에 대한 자세한 내용은 Claude 4.5의 새로운 기능을 참조하세요.
  8. 구현 테스트 모든 주요 변경사항이 적절히 처리되었는지 확인하기 위해 프로덕션에 배포하기 전에 개발 환경에서 테스트하세요.

​
Haiku 3.5 → 4.5 마이그레이션 체크리스트

  • 모델 ID를 claude-haiku-4-5-20251001로 업데이트
  • 주요 변경: 도구 버전을 최신으로 업데이트 (예: text_editor_20250728, code_execution_20250825) - 레거시 버전 지원되지 않음
  • 주요 변경: undo_edit 명령을 사용하는 모든 코드 제거 (해당하는 경우)
  • 주요 변경: 샘플링 매개변수를 temperature 또는 top_p 중 하나만 사용하도록 업데이트
  • 새로운 속도 제한 검토 및 조정 (Haiku 3.5와 별도)
  • 애플리케이션에서 새로운 refusal 중지 이유 처리
  • 복잡한 추론 작업에 대한 확장된 사고 활성화 고려 (새로운 기능)
  • 긴 세션에서 더 나은 토큰 관리를 위한 컨텍스트 인식 활용
  • 더 큰 응답 준비 (최대 출력이 8K에서 64K 토큰으로 증가)
  • Claude 4 모범 사례에 따라 프롬프트 검토 및 업데이트
  • 프로덕션 배포 전 개발 환경에서 테스트

​
Sonnet 4.5와 Haiku 4.5 중 선택

Claude Sonnet 4.5와 Claude Haiku 4.5는 모두 서로 다른 강점을 가진 강력한 Claude 4 모델입니다:

​
Claude Sonnet 4.5 (가장 지능적) 선택 기준:

  • 복잡한 추론 및 분석: 정교한 작업을 위한 최고 수준의 지능
  • 장기 실행 자율 에이전트: 장기간 독립적으로 작업하는 에이전트에 대한 우수한 성능
  • 고급 코딩 작업: 고급 계획 및 보안 엔지니어링을 갖춘 가장 강력한 코딩 모델
  • 대용량 컨텍스트 워크플로: 메모리 도구 및 컨텍스트 편집 기능을 통한 향상된 컨텍스트 관리
  • 최대 기능이 필요한 작업: 지능과 정확성이 최우선인 경우

​
Claude Haiku 4.5 (가장 빠르고 지능적인 Haiku) 선택 기준:

  • 실시간 애플리케이션: 최전선급 성능을 갖춘 대화형 사용자 경험을 위한 빠른 응답 시간
  • 대용량 지능형 처리: 향상된 속도로 규모에서 비용 효율적인 지능
  • 비용에 민감한 배포: 더 낮은 가격대에서 최전선급 성능
  • 하위 에이전트 아키텍처: 다중 에이전트 시스템을 위한 빠르고 지능적인 에이전트
  • 규모에서 컴퓨터 사용: 비용 효율적인 자율 데스크톱 및 브라우저 자동화
  • 속도가 필요한 작업: 최전선급 지능을 유지하면서 낮은 지연 시간이 중요한 경우

​
확장된 사고 권장사항

Claude 4 모델, 특히 Sonnet과 Haiku 4.5는 코딩 및 복잡한 추론 작업에 확장된 사고를 사용할 때 상당한 성능 향상을 보입니다. 확장된 사고는 기본적으로 비활성화되어 있지만 까다로운 작업에 대해서는 활성화하는 것을 권장합니다. 중요: 확장된 사고는 프롬프트 캐싱 효율성에 영향을 미칩니다. 도구 결과가 아닌 콘텐츠가 대화에 추가되면 사고 블록이 캐시에서 제거되어 다중 턴 대화에서 비용이 증가할 수 있습니다. 성능 이점이 캐싱 트레이드오프를 능가할 때 사고를 활성화하는 것을 권장합니다.

​
기타 마이그레이션 시나리오

위에서 다룬 주요 마이그레이션 경로 (Sonnet 3.7 → 4.5 및 Haiku 3.5 → 4.5)는 가장 일반적인 업그레이드를 나타냅니다. 그러나 다른 Claude 모델에서 Claude 4.5로 마이그레이션할 수도 있습니다. 이 섹션에서는 이러한 시나리오를 다룹니다.

​
Claude Sonnet 4 → Sonnet 4.5에서 마이그레이션

주요 변경: 동일한 요청에서 temperature와 top_p를 모두 지정할 수 없습니다. 다른 모든 API 호출은 수정 없이 작동합니다. 모델 ID를 업데이트하고 필요한 경우 샘플링 매개변수를 조정하세요: 
# 이전 (Claude Sonnet 4)
model="claude-sonnet-4-20250514"

# 이후 (Claude Sonnet 4.5)
model="claude-sonnet-4-5-20250929"

​
Claude Opus 4.1 → Sonnet 4.5에서 마이그레이션

주요 변경사항 없음. 모든 API 호출이 수정 없이 작동합니다. 모델 ID만 업데이트하면 됩니다: 
# 이전 (Claude Opus 4.1)
model="claude-opus-4-1-20250805"

# 이후 (Claude Sonnet 4.5)
model="claude-sonnet-4-5-20250929"
Claude Sonnet 4.5는 최고 수준의 추론, 코딩, 장기 실행 에이전트 기능을 갖춘 가장 지능적인 모델입니다. 대부분의 사용 사례에서 Opus 4.1보다 우수한 성능을 제공합니다.

​
도움이 필요하신가요?

  • 자세한 사양은 API 문서를 확인하세요
  • 성능 비교는 모델 기능을 검토하세요
  • API 업데이트는 API 릴리스 노트를 검토하세요
  • 마이그레이션 중 문제가 발생하면 지원팀에 문의하세요