Claude 4로 마이그레이션하기
이 페이지는 Claude 3.7 모델에서 Claude 4 모델(Opus 4 및 Sonnet 4)로 마이그레이션하는 방법에 대한 지침을 제공합니다.
대부분의 경우, 최소한의 변경으로 Claude 4 모델로 전환할 수 있습니다:
-
모델 이름 업데이트:
- 기존:
claude-3-7-sonnet-20250219
- 변경:
claude-sonnet-4-20250514
또는claude-opus-4-20250514
- 기존:
-
기존 API 호출은 수정 없이 계속 작동해야 하지만, Claude 4 모델에서는 API 동작이 약간 변경되었습니다(자세한 내용은 API 릴리스 노트 참조).
Claude 4의 새로운 기능
새로운 거부 중지 이유
Claude 4 모델은 Claude 4 모델의 향상된 지능으로 인해 안전상의 이유로 생성을 거부하는 콘텐츠에 대한 새로운 refusal
중지 이유를 도입합니다:
Claude 4로 마이그레이션할 때는 애플리케이션을 업데이트하여 refusal
중지 이유를 처리해야 합니다.
요약된 사고 과정
확장된 사고 과정이 활성화된 상태에서 Claude 4 모델용 Messages API는 Claude의 전체 사고 과정에 대한 요약을 반환합니다. 요약된 사고 과정은 확장된 사고의 모든 지능적 이점을 제공하면서 오용을 방지합니다.
API는 Claude 3.7과 4 모델 간에 일관성이 있지만, 확장된 사고에 대한 스트리밍 응답은 “덩어리” 전달 패턴으로 반환될 수 있으며, 스트리밍 이벤트 사이에 지연이 발생할 수 있습니다.
요약은 요청에서 대상으로 하는 모델과 다른 모델에 의해 처리됩니다. 사고 모델은 요약된 출력을 보지 않습니다.
자세한 내용은 확장된 사고 문서를 참조하세요.
교차 사고 과정
Claude 4 모델은 도구 사용과 확장된 사고를 교차하는 것을 지원하여, 도구 사용과 응답이 일반 메시지와 혼합될 수 있는 더 자연스러운 대화를 가능하게 합니다.
교차 사고 과정은 베타 상태입니다. 교차 사고 과정을 활성화하려면 API 요청에 베타 헤더 interleaved-thinking-2025-05-14
를 추가하세요.
자세한 내용은 확장된 사고 문서를 참조하세요.
업데이트된 텍스트 에디터 도구
텍스트 에디터 도구는 Claude 4 모델에서 다음과 같이 업데이트되었습니다:
- 도구 유형:
text_editor_20250429
- 도구 이름:
str_replace_based_edit_tool
undo_edit
명령은 Claude 4 모델에서 더 이상 지원되지 않습니다.
str_replace_editor
텍스트 에디터 도구는 Claude Sonnet 3.7에서 동일하게 유지됩니다.
Claude Sonnet 3.7에서 마이그레이션하고 텍스트 에디터 도구를 사용하는 경우:
자세한 내용은 텍스트 에디터 도구 문서를 참조하세요.
토큰 효율적 도구 사용 더 이상 지원되지 않음
토큰 효율적 도구 사용은 Claude Sonnet 3.7에서만 사용 가능합니다.
Claude Sonnet 3.7에서 마이그레이션하고 토큰 효율적 도구 사용을 사용하는 경우, 요청에서 token-efficient-tools-2025-02-19
베타 헤더를 제거하는 것이 좋습니다.
token-efficient-tools-2025-02-19
베타 헤더는 여전히 Claude 4 요청에 포함될 수 있지만, 아무 효과가 없습니다.
확장 출력 더 이상 지원되지 않음
확장 출력을 위한 output-128k-2025-02-19
베타 헤더는 Claude Sonnet 3.7에서만 사용 가능합니다.
Claude Sonnet 3.7에서 마이그레이션하는 경우, 요청에서 output-128k-2025-02-19
를 제거하는 것이 좋습니다.
output-128k-2025-02-19
베타 헤더는 여전히 Claude 4 요청에 포함될 수 있지만, 아무 효과가 없습니다.
성능 고려 사항
Claude Sonnet 4
- Claude Sonnet 3.7에 비해 향상된 추론 및 지능 기능
- 향상된 도구 사용 정확도
Claude Opus 4
- 우수한 추론 및 지능을 갖춘 가장 강력한 모델
- Sonnet 모델보다 느림
- 심층 분석이 필요한 복잡한 작업에 가장 적합
마이그레이션 체크리스트
- API 호출에서 모델 ID 업데이트
- 기존 요청 테스트(변경 없이 작동해야 함)
- 해당하는 경우
token-efficient-tools-2025-02-19
베타 헤더 제거 - 해당하는 경우
output-128k-2025-02-19
베타 헤더 제거 - 새로운
refusal
중지 이유 처리 - 텍스트 에디터 도구를 사용하는 경우 도구 유형 및 이름 업데이트
-
undo_edit
명령을 사용하는 코드 제거 - 확장된 사고를 통한 새로운 도구 교차 기능 탐색
- 최적의 결과를 위해 Claude 4 프롬프트 엔지니어링 모범 사례 검토
- 프로덕션 배포 전 개발 환경에서 테스트
도움이 필요하신가요?
- 자세한 사양은 API 문서를 확인하세요.
- 성능 비교는 모델 기능을 검토하세요.
- API 업데이트는 API 릴리스 노트를 검토하세요.
- 마이그레이션 중 문제가 발생하면 지원팀에 문의하세요.