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_20250429
• 도구 이름: 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_20250429",
        "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 릴리스 노트를 검토하세요.
• 마이그레이션 중 문제가 발생하면 지원팀에 문의하세요.