버전 관리
버전 관리 (Versioning)
Vercel AI SDK의 버전 번호 체계와 API 안정성 정책을 정리한 문서예요. 어떤 버전이 어떻게 올라가는지, 실험적 API랑 지원 종료(Deprecated) API는 어떻게 다뤄야 안전한지가 핵심이에요. AI SDK를 업그레이드할 때마다 헷갈리던 부분을 한 번에 정리해드릴게요.
출처: 문서
본문
각 버전 번호는 MAJOR.MINOR.PATCH 형식을 따릅니다.
- Major: 코드 변경이 필요한, 호환성이 깨지는(Breaking) API 업데이트.
- Minor: 새 기능과 개선사항을 공개 릴리스로 묶어 이점을 강조하는 글.
- Patch: 새 기능과 버그 수정.
API 안정성 (API Stability)
우리는 API의 안정성을 다음과 같이 구분해서 안내합니다.
안정된 API (Stable APIs)
특별한 접두사가 없는 모든 API는 안정적이며 프로덕션에서 바로 사용할 수 있다고 간주합니다. 안정된 기능에 대해서는 하위 호환성(backward compatibility)을 유지하며, 호환성이 깨지는 변경은 메이저 릴리스에서만 도입합니다.
실험적 API (Experimental APIs)
experimental_ 또는 Experimental_ 접두사가 붙은 API(예: experimental_generateImage())는 개발 중인 기능으로, 어떤 릴리스에서든 변경될 수 있습니다. 실험적 API를 안전하게 사용하려면:
- 프로덕션이 아니라 개발 환경에서 먼저 테스트하세요
- 업그레이드 전에 릴리스 노트를 검토하세요
- 예상치 못한 코드 변경에 대비하세요
경고: 실험적 API를 사용한다면 AI SDK 버전 번호를 정확히 고정하세요(
^나~같은 버전 범위를 피하기). 뜻밖의 호환성 파괴 변경을 막을 수 있어요.
지원 종료된 API (Deprecated APIs)
deprecated로 표시된 API는 향후 메이저 릴리스에서 제거됩니다. 메이저 릴리스까지 기다렸다가 코드를 업데이트할 수 있습니다. 지원 종료를 다룰 때는:
- 권장되는 대체 API로 전환하세요
- 마이그레이션 가이드(메이저 릴리스와 함께 공개됨)를 따르세요
메이저 릴리스에서는 가능한 경우 코드를 새 버전으로 자동 마이그레이션해주는 codemod를 제공합니다.