이 페이지는 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 모델은 도구 사용과 확장된 사고를 교차하는 것을 지원하여, 도구 사용과 응답이 일반 메시지와 혼합될 수 있는 더 자연스러운 대화를 가능하게 합니다.

교차 사고 과정은 베타 상태입니다. 교차 사고 과정을 활성화하려면 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
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 릴리스 노트를 검토하세요.
  • 마이그레이션 중 문제가 발생하면 지원팀에 문의하세요.