Claude Haiku 4.5로 마이그레이션

Claude Haiku 4.5로 마이그레이션 (Migrating to Claude Haiku 4.5)

Claude Haiku 4.5는 가장 빠르면서 프론티어에 가까운 성능을 내는 Haiku 모델이에요. 대화형 애플리케이션과 대량 처리에서 프리미엄 모델 품질을 제공하죠. 이전 Haiku 모델에서 옮길 때 필요한 모델 ID, 하위 호환을 깨는 변경, 마이그레이션 체크리스트를 차근차근 정리해 드릴게요.

출처: 문서

본문

이 가이드는 [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages) 코드를 마이그레이션하는 내용을 다뤄요. [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)를 사용한다면 모델 이름을 업데이트하는 것 외에는 변경이 필요 없어요. **Claude API 스킬로 마이그레이션을 자동화하세요.** Claude Code에서 `/claude-api migrate`를 실행하면 번들로 제공되는 [Claude API 스킬](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill#migrating-to-a-newer-claude-model)을 호출해요. 이 스킬은 대상으로 하는 어떤 현재 Claude 모델에서도 동작해요: 
/claude-api migrate this project to claude-haiku-4-5

이 스킬은 코드베이스 전체에 걸쳐 대상 모델에 맞춰 모델 ID 교체와, 필요에 따라 하위 호환을 깨는 파라미터 변경, 프리필 대체, effort 보정을 적용한 다음, 수동으로 확인할 항목 목록을 만들어 줘요. 파일을 편집하기 전에 마이그레이션 범위(전체 작업 디렉터리, 하위 디렉터리, 또는 특정 파일 목록)를 확인하라고 요청해요. 이 스킬은 Amazon Bedrock과 AWS의 Claude Platform 클라이언트도 감지해서 그 플랫폼에 맞게 모델 ID 형식과 기능 변경을 조정해요.

Claude Haiku 4.5는 가장 빠르고 가장 지능적인 Haiku 모델로 프론티어에 가까운 성능을 제공하며, 대화형 애플리케이션과 대용량 처리를 위한 프리미엄 모델 품질을 전달해요.

기능에 대한 전체 개요는 모델 개요를 참고하세요.

Claude Haiku 4.5 가격은 [Claude 가격](https://platform.claude.com/docs/en/about-claude/pricing)을 참고하세요. 코딩과 추론 작업에서 상당한 성능 향상을 원한다면 `thinking: {type: "enabled", budget_tokens: N}`으로 확장 사고를 켜는 것을 고려해 보세요. 확장 사고는 [프롬프트 캐싱](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#caching-with-thinking-blocks) 효율에 영향을 미쳐요.

확장 사고는 Claude 4.6 모델에서 폐지되었고 Claude Opus 4.7에서 제거됐어요. 더 새로운 모델을 사용한다면 대신 적응형 사고를 사용하세요.

Claude Haiku 3.5 및 이전 Haiku 모델에서 Claude Haiku 4.5로 마이그레이션

모델 이름 업데이트:

# From Haiku 3.5
model = "claude-3-5-haiku-20241022"  # Before
model = "claude-haiku-4-5-20251001"  # After

새 요율 제한 검토: Haiku 4.5는 Haiku 3.5와 별개의 요율 제한을 가져요. 자세한 내용은 요율 제한 문서를 참고하세요.

새 기능 탐색: 컨텍스트 인식, 증가된 출력 용량(64k 토큰), 더 높은 지능, 개선된 속도에 대한 자세한 내용은 모델 개요를 참고하세요.

하위 호환을 깨는 변경 (Breaking changes)

이 하위 호환을 깨는 변경들은 Claude 3.x Haiku 모델에서 마이그레이션할 때 적용돼요.

  1. 샘플링 파라미터 업데이트

    이는 Claude 3.x 모델에서 마이그레이션할 때 하위 호환을 깨는 변경이에요.

    temperature 또는 top_p 중 하나만 사용하고 둘 다 쓰지 마세요. 둘 다 설정하면 Claude Haiku 4.5에서 400 오류를 반환해요.

  2. 도구 버전 업데이트

    이는 Claude 3.x 모델에서 마이그레이션할 때 하위 호환을 깨는 변경이에요.

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

  3. refusal 중지 이유 처리

    애플리케이션을 streaming refusal 처리로 업데이트하세요.

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

    Claude 4 모델은 더 간결하고 직접적인 의사소통 스타일을 가져요. 최적화 지침은 프롬프팅 모범 사례를 검토하세요.

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

  • 모델 ID를 claude-haiku-4-5-20251001로 업데이트
  • BREAKING: 도구 버전을 최신(text_editor_20250728, code_execution_20250825)으로 업데이트; 레거시 버전은 지원되지 않음
  • BREAKING: undo_edit 명령을 사용하는 코드 제거 (해당되는 경우)
  • BREAKING: 샘플링 파라미터를 temperature 또는 top_p 중 하나만 쓰도록 업데이트 (둘 다 설정하면 400 오류를 반환)
  • 애플리케이션에서 새 refusal 중지 이유 처리
  • 새 요율 제한 검토 및 조정 (Haiku 3.5와 별개)
  • 프롬프팅 모범 사례에 따라 프롬프트 검토 및 업데이트
  • 복잡한 추론 작업에는 확장 사고 활성화 고려
  • 프로덕션 배포 전 개발 환경에서 테스트

더 알아보기 (Learn more)