Claude 4로 마이그레이션

이 페이지는 Claude 3.7 모델에서 Claude 4 모델(Opus 4 및 Sonnet 4)로 마이그레이션하는 방법에 대한 가이드를 제공합니다.

대부분의 경우 최소한의 변경으로 Claude 4 모델로 전환할 수 있습니다:

1. 모델 이름을 업데이트하세요:

   • 기존: claude-3-7-sonnet-20250219
   • 변경: claude-sonnet-4-20250514 또는 claude-opus-4-20250514

2. 기존 API 호출은 수정 없이 계속 작동해야 하지만, Claude 4 모델에서는 API 동작이 약간 변경되었습니다(자세한 내용은 API 릴리스 노트 참조).

​

Claude 4의 새로운 기능

​

새로운 거부 중단 이유

Claude 4 모델은 Claude 4 모델의 향상된 지능으로 인해 모델이 안전상의 이유로 생성을 거부하는 콘텐츠에 대한 새로운 refusal 중단 이유를 도입합니다:

{"id":"msg_014XEDjypDjFzgKVWdFUXxZP",
"type":"message",
"role":"assistant",
"model":"claude-sonnet-4-20250514",
"content":[{"type":"text","text":"I would be happy to assist you. You can "}],
"stop_reason":"refusal",
"stop_sequence":null,
"usage":{"input_tokens":564,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":22}
}

Claude 4로 마이그레이션할 때는 refusal 중단 이유를 처리하도록 애플리케이션을 업데이트해야 합니다.

​

요약된 사고

확장 사고가 활성화된 상태에서 Claude 4 모델의 Messages API는 Claude의 전체 사고 과정에 대한 요약을 반환합니다. 요약된 사고는 확장 사고의 완전한 지능적 이점을 제공하면서 오용을 방지합니다.

API는 Claude 3.7과 4 모델에서 일관되지만, 확장 사고에 대한 스트리밍 응답은 스트리밍 이벤트 간에 지연이 있을 수 있는 “청크” 전달 패턴으로 반환될 수 있습니다.

자세한 정보는 확장 사고 문서를 참조하세요.

​

인터리브 사고

Claude 4 모델은 도구 사용과 확장 사고의 인터리빙을 지원하여 도구 사용과 응답이 일반 메시지와 혼합될 수 있는 더 자연스러운 대화를 가능하게 합니다.

자세한 정보는 확장 사고 문서를 참조하세요.

​

업데이트된 텍스트 편집기 도구

텍스트 편집기 도구가 Claude 4 모델에 대해 다음과 같은 변경 사항으로 업데이트되었습니다:

• 도구 유형: text_editor_20250728
• 도구 이름: str_replace_based_edit_tool
• undo_edit 명령은 Claude 4 모델에서 더 이상 지원되지 않습니다.

Claude Sonnet 3.7에서 마이그레이션하고 텍스트 편집기 도구를 사용하는 경우:

# Claude Sonnet 3.7
tools=[
    {
        "type": "text_editor_20250124",
        "name": "str_replace_editor"
    }
]

# Claude 4
tools=[
    {
        "type": "text_editor_20250728",
        "name": "str_replace_based_edit_tool"
    }
]

자세한 정보는 텍스트 편집기 도구 문서를 참조하세요.

​

토큰 효율적 도구 사용 더 이상 지원되지 않음

토큰 효율적 도구 사용은 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 릴리스 노트를 검토하세요.
• 마이그레이션 중 문제가 발생하면 지원팀에 문의하세요.