AI 모델의 버전 관리와 배포를 위한 경량화된 모델 레지스트리 시스템
Model Registry는 머신러닝 프로젝트에서 발생하는 모델 버전 관리, 메타데이터 추적, 배포 프로세스의 복잡성을 해결하기 위한 경량화된 솔루션입니다.
- ❌ 모델 버전 관리의 부재:
model_v1.pth,model_final.pth등 수동 파일명 관리 - ❌ 메타데이터 파편화: 학습 데이터, 성능 지표, 하이퍼파라미터가 여러 문서에 흩어짐
- ❌ 재현성 부족: 특정 시점의 모델 생성 환경 추적 어려움
- ❌ 배포 프로세스의 복잡성: 검증된 최신 버전 식별의 모호함
이 프로젝트는 MLflow Model Registry와 HuggingFace Hub의 핵심 디자인 패턴을 참고하되, 로컬 개발 및 소규모 팀에 최적화된 경량 구조를 추구합니다.
- Semantic Versioning (Major.Minor.Patch) 지원
- 자동 버전 번호 계산 및 충돌 방지
- Latest 태그를 통한 프로덕션 버전 추적
- Framework, Architecture, Input Shape, Dataset 정보 저장
- 성능 지표(Accuracy, F1-Score 등) JSON 형식 지원
- 버전별 변경 사항 메모 기능
- Streamlit 기반 웹 대시보드
- 모델 패밀리별 계층적 네비게이션
- 실시간 검색 및 필터링
- 웹 UI에서 즉시 모델 성능 테스트
- 샘플 이미지 또는 사용자 업로드 이미지 지원
- 실시간 예측 결과 및 신뢰도 시각화
- SQLite 기반 메타데이터 관리 (Serverless)
- 파일 시스템 기반 아티팩트 저장
- UUID를 통한 파일명 충돌 방지
등록된 모델 패밀리 목록 및 검색
모델별 버전 관리 및 Latest 태그
메타데이터 확인 및 실시간 모델 추론
시맨틱 버저닝 기반 모델 업로드
- Python 3.10 이상
- pip (Python 패키지 관리자)
- 저장소 클론
git clone https://github.com/yourusername/model-registry.git
cd model-registry- 의존성 설치
pip install -r requirements.txt- 환경 변수 설정 (선택 사항)
외부 스토리지 경로를 사용하려면 .env 파일을 생성하세요:
FALLBACK_PATH=["/path/to/external/storage", "/another/path"]streamlit run app.py브라우저에서 자동으로 http://localhost:8501이 열립니다.
앱 실행 후 사이드바에서 "Initialize Demo Data" 버튼을 클릭하면 샘플 모델이 자동으로 등록됩니다.
- 메인 대시보드에서 등록된 모델 패밀리 확인
- 검색창을 통해 모델 이름으로 필터링
- 모델 카드 클릭으로 버전 히스토리 이동
- 특정 버전 선택 시 메타데이터 확인
View Architecture Layers확장 메뉴에서 모델 구조 확인- 성능 지표 및 학습 데이터셋 정보 검토
- 샘플 이미지 사용: 기본 제공되는 테스트 이미지 선택
- 이미지 업로드: 직접 보유한 이미지 업로드
- Run Inference 버튼 클릭으로 실시간 예측 실행
- 예측 클래스 및 신뢰도 확인
- 모델 버전 목록에서 "New Version" 버튼 클릭
- 업데이트 유형 선택 (Major/Minor/Patch)
- Major: 호환되지 않는 변경 (아키텍처 변경 등)
- Minor: 기능 추가 및 성능 개선
- Patch: 버그 수정 및 미세 조정
- 자동 계산된 다음 버전 번호 확인
- 모델 파일(
.pth) 업로드 - 메타데이터 입력 (Framework, Architecture, Input Shape, Dataset, Metrics, Memo)
- "Register Version" 클릭하여 저장
Tip: 데모용 모델 파일은
assets/models/디렉토리에 제공됩니다.
📖 상세 사용 가이드: HOW_TO_USE.md
model-registry/
├── app.py # Streamlit 메인 애플리케이션
├── requirements.txt # Python 의존성
├── database/
│ ├── sqlite.py # Database DAO Layer
│ └── model_registry.db # SQLite 데이터베이스
├── src/
│ ├── registry.py # Registry Service (Business Logic)
│ ├── inference.py # Inference Engine
│ └── versioning.py # Semantic Versioning Logic
├── models/
│ ├── mobilenet.py # MobileNet 아키텍처 정의
│ └── UNet.py # U-Net 아키텍처 정의
├── artifacts/ # 모델 아티팩트 저장소
│ ├── mobilenet/
│ └── unet/
├── assets/
│ ├── models/ # 데모용 모델 파일
│ ├── readme/ # README 스크린샷
│ └── test/ # 추론 테스트용 샘플 이미지
└── docs/
├── HOW_TO_USE.md # 상세 사용 가이드
└── SYSTEM_DESIGN.md # 시스템 설계 문서
┌─────────────────────────────────────┐
│ Presentation Layer (Streamlit) │ ← 사용자 인터페이스
└───────────┬─────────────────────────┘
│
┌───────────▼─────────────────────────┐
│ Business Logic Layer │
│ ├─ Registry Service │ ← 모델 관리 로직
│ ├─ Inference Engine │ ← 추론 실행
│ └─ Versioning Logic │ ← 버전 계산
└───────────┬─────────────────────────┘
│
┌───────────▼─────────────────────────┐
│ Data Access Layer (DAO) │ ← 데이터베이스 CRUD
└───────────┬─────────────────────────┘
│
┌───────────▼─────────────────────────┐
│ Storage Layer │
│ ├─ SQLite (메타데이터) │
│ └─ File System (아티팩트) │
└─────────────────────────────────────┘
- 메타데이터와 아티팩트 분리: DB 부하 감소 및 I/O 효율 최적화
- 동적 모델 로딩: 새 아키텍처 추가 시 코드 수정 불필요
- UUID 기반 파일명: 충돌 방지 및 고유성 보장
📖 상세 아키텍처 문서: SYSTEM_DESIGN.md
| Category | Technology |
|---|---|
| Backend Framework | Python 3.10+ |
| Web Framework | Streamlit 1.51.0 |
| ML Framework | PyTorch 2.9.1, TorchVision 0.24.1 |
| Database | SQLite (Serverless) |
| Image Processing | Pillow 12.0.0 |
| Data Manipulation | Pandas 2.3.3 |
| Environment | python-dotenv 1.2.1 |
- HOW_TO_USE.md: 사용자 가이드 및 UI 워크플로우
- SYSTEM_DESIGN.md: 아키텍처 다이어그램 및 설계 결정 사항
이 프로젝트는 개발 전 과정에서 AI 코딩 어시스턴트(Cursor)를 적극적으로 활용하여 구현되었습니다.
이 프로젝트는 MIT 라이선스 하에 배포됩니다.
- MLflow - 모델 레지스트리 디자인 패턴 참고
- HuggingFace Hub - 모델 카드 및 추론 API 벤치마킹
Made with ❤️ using Cursor AI