Model Artifacts
NuFi Model Registry는 모델을 등록하고, 버전별 아티팩트를 관리하며, 등록된 아티팩트를 컴파일 또는 서빙 배포로 연결하는 화면입니다. 모델은 직접 등록할 수도 있고, MLflow 또는 Hugging Face에서 가져올 수도 있습니다.
모델은 3계층 구조로 관리됩니다.
| 계층 | 설명 |
|---|---|
| RegisteredModel | 모델 이름 단위의 최상위 그룹 |
| ModelVersion | 모델의 개별 버전. 하나의 모델에 여러 버전을 등록할 수 있습니다 |
| ModelArtifact | 버전에 연결된 실제 모델 파일 위치. pvc://{volume}/{path} 형식으로 저장됩니다 |
사전 조건
- NuFi 프로젝트가 생성되어 있어야 합니다.
- 모델 파일이 저장된 Volume(PVC)이 프로젝트에서 접근 가능한 상태여야 합니다.
- MLflow 연동을 사용하려면 접근 가능한 MLflow Tracking Server가 있어야 합니다.
- Hugging Face Import로 비공개 모델을 가져오려면 프로젝트 설정에 Hugging Face token을 저장해야 합니다.
모델 목록
좌측 사이드바에서 Models를 클릭합니다.
| 번호 | 설명 |
|---|---|
| ① | MLflow 및 Hugging Face 연동 관리 페이지로 이동합니다 |
| ② | 새 RegisteredModel을 생성합니다. 버전과 아티팩트는 모델 상세에서 추가합니다 |
| ③ | Quick Deploy 다이얼로그를 엽니다. 버전 또는 아티팩트가 없으면 사용할 수 없습니다 |
모델 목록 상단의 검색창에서 모델 이름을 검색할 수 있습니다. 모델 행을 클릭하면 해당 모델의 버전 목록으로 이동합니다.
컬럼
| 컬럼 | 설명 |
|---|---|
| Name | 등록된 모델 이름 |
| Versions | 등록된 버전 수 |
| Description | 모델 설명 |
| Created | 최초 등록 시간 |
모델 상세 — 버전 목록
모델 목록에서 모델 행을 클릭하면 버전 목록 페이지로 이동합니다.
| 컬럼 | 설명 |
|---|---|
| Version | 버전 문자열 (예: v1, 1.0.0) |
| State | 버전 상태 (예: Active) |
| Author | 버전 등록자 이름 |
| Source | 버전 출처 (예: manual, mlflow, huggingface) |
| Artifacts | 해당 버전에 연결된 아티팩트 수 |
| Description | 버전 설명 |
| Created | 버전 등록 시간 |
상단의 Add Version 버튼으로 현재 모델에 새 버전을 추가할 수 있습니다. 우측 상단의 Delete Model 버튼은 모델과 모든 버전/아티팩트를 삭제하므로 운영 중인 모델에서는 주의해야 합니다.
버전 상세
버전 행을 클릭하면 버전 상세 페이지로 이동합니다. 0.1.0에서는 Artifacts와 Compilations 탭을 제공합니다.
| 번호 | 설명 |
|---|---|
| ① | 해당 GPU 아티팩트로 NPU 컴파일 다이얼로그를 엽니다 |
| ② | 해당 아티팩트로 Quick Deploy 다이얼로그를 엽니다 |
Artifacts 탭
| 컬럼 | 설명 |
|---|---|
| Name | 아티팩트 이름 (예: original, rngd) |
| Format | 모델 포맷 (safetensors, other) |
| Platform | 실행 대상 플랫폼. GPU 원본은 GPU, NPU 결과물은 디바이스 플랫폼으로 표시됩니다 |
| URI | 아티팩트 파일 위치. PVC URI는 클릭하면 Volume 파일 브라우저로 이동합니다 |
| Size | 아티팩트 크기 |
| Compilation | 컴파일 결과물인 경우 연결된 컴파일 실행으로 이동합니다 |
Compilations 탭
Compilations 탭에서는 이 모델 버전과 연결된 NPU 컴파일 실행 목록을 확인합니다. 성공한 컴파일은 결과 아티팩트를 Model Registry에 자동 추가하며, 기존 컴파일 설정으로 다시 실행할 수 있습니다.
모델 등록 흐름
모델은 모델 생성 → 버전 추가 → 아티팩트 추가 또는 컴파일 결과 자동 등록 순서로 관리합니다.
1. 모델 생성
모델 목록 페이지 우측 상단의 Register Model 버튼을 클릭합니다.
| 필드 | 설명 |
|---|---|
| Model Name | 모델 그룹 이름. 문자, 숫자, ., _, -를 사용할 수 있으며 문자 또는 숫자로 시작/끝나야 합니다 |
| Description | 모델 설명 |
| Author | 모델 등록자 이름 |
2. 버전 추가
모델 상세 페이지에서 Add Version 버튼을 클릭합니다. Add Version은 버전 정보와 GPU 기반 원본 아티팩트 위치를 함께 등록합니다.
| 필드 | 설명 |
|---|---|
| Version | 버전 문자열. 같은 모델 안에서 유일해야 합니다 |
| Volume | 원본 모델 파일이 저장된 Volume(PVC) |
| Path | Volume 내부 모델 파일 또는 디렉터리 경로 |
| Format | 모델 포맷. Validate 성공 시 자동 감지된 값으로 갱신됩니다 |
| Description | 버전 설명 |
| Author | 버전 등록자 이름 |
탐색 버튼을 누르면 Volume 디렉터리 브라우저가 열립니다. 모델 루트처럼 보이는 폴더에는 배지가 표시되며, 폴더를 선택하면 Validate가 자동 실행됩니다.
Validate 결과
하나의 버전에는 하나의 GPU 모델 아티팩트만 존재해야합니다. 버전 추가 시에는 GPU 모델 아티팩트만 등록이 가능하고 아티팩트 추가 시에는 NPU 모델 아티팩트만 등록이 가능합니다.
| 결과 | 설명 |
|---|---|
| Validation successful | 등록 가능한 모델 루트를 찾았습니다. 실제 등록 URI가 선택 경로와 다르면 해소된 루트가 표시됩니다 |
| 여러 모델 감지 | 선택한 경로 아래에 여러 모델 루트가 있어 더 구체적인 폴더 선택이 필요합니다 |
| 확인했고 등록 강행 | 경고는 있지만 강제 등록 가능한 상태입니다. 내용을 확인한 뒤 강행할 수 있습니다 |
| Validation failed | 모델 파일을 찾지 못했거나 지원하지 않는 구조입니다. Path 또는 Volume을 수정해야 합니다 |
3. 아티팩트 추가
버전 상세의 Artifacts 탭에서 Add Artifact 버튼을 클릭합니다.
| 필드 | 설명 |
|---|---|
| Artifact Name | 아티팩트 이름. Kubernetes 리소스 이름 규칙에 맞게 소문자, 숫자, -만 사용할 수 있습니다 |
| Format | 모델 포맷 |
| Platform | 대상 실행 플랫폼. NPU 디바이스 플랫폼을 선택합니다 |
| Volume | 아티팩트 파일이 저장된 Volume(PVC) |
| Path | Volume 내부 아티팩트 파일 또는 디렉터리 경로 |
| Metadata (JSON) | Validate 결과에서 추출된 메타데이터. 필요 시 JSON으로 수정할 수 있습니다 |
버전의 Validate 결과와 같이 NPU 아티팩트에 대한 validation을 수행함으로 참고 부탁드립니다.
Quick Deploy
모델 목록·버전 목록·아티팩트 목록에서 Quick Deploy 버튼으로 즉시 배포 다이얼로그를 열 수 있습니다.
진입점별 동작
| 진입점 | 동작 |
|---|---|
| 모델 목록 | 모델을 미리 선택하고, 사용 가능한 버전/아티팩트를 이어서 선택합니다 |
| 버전 목록 | 모델과 버전을 미리 선택하고, 배포할 아티팩트를 선택합니다 |
| 아티팩트 목록 | 모델/버전/아티팩트가 미리 선택된 상태로 열립니다 |
Quick Deploy 다이얼로그는 선택된 아티팩트의 platform에 따라 가속기, 추론 엔진, 컨테이너 이미지 기본값을 결정합니다. rbln 플랫폼 아티팩트는 0.1.0에서 Quick Deploy 버튼이 비활성화됩니다.
| 필드 | 설명 |
|---|---|
| Model | 배포할 모델 |
| Version | 배포할 버전 |
| Artifact | 배포할 아티팩트 |
| Service Name | 생성될 Serving 이름 |
| Inference Engine | 추론 엔진 |
| Accelerator | 가속기 |
| Image | 컨테이너 이미지 |
Advanced 섹션에서는 CPU, Memory, 추가 Arguments, Environment Variables를 설정할 수 있습니다.
Integration
모델 목록 상단의 Integration 버튼을 클릭하면 외부 모델 소스 연동 페이지로 이동합니다. 0.1.0에서는 MLflow와 Hugging Face 탭을 제공합니다.
MLflow 탭
MLflow 탭은 Webhook 기반 Push Import와 수동 Pull Import를 제공합니다.
| 영역 | 설명 |
|---|---|
| Webhooks | MLflow Registry Webhook 수신 URL을 만들고 활성/비활성 상태를 관리합니다 |
| Import History | MLflow Import 작업의 상태와 대상 모델/버전, 생성/완료 시간을 확인합니다 |
| Import from MLflow | 특정 Run의 아티팩트를 NuFi 모델 버전으로 가져옵니다 |
Webhook 등록 시 Target Model은 선택 사항입니다. 비워두면 모든 모델 이벤트를 대상으로 처리하고, Storage PVC와 Auto Import 여부를 함께 지정합니다.
Import from MLflow 필드
| 필드 | 설명 | 필수 |
|---|---|---|
| MLflow Tracking URL | MLflow Tracking Server 주소 | ✓ |
| Run ID | 가져올 MLflow Run UUID | ✓ |
| MLflow Artifact Path | Run artifact root 기준 상대 경로 | ✓ |
| Target Model | NuFi에 등록할 모델 이름 | ✓ |
| Target Version | NuFi에 등록할 버전 | ✓ |
Hugging Face 탭
Hugging Face 탭에서는 Hub의 모델 repository를 NuFi 모델로 가져오고, 가져온 source mapping과 import history를 확인할 수 있습니다.
| 영역 | 설명 |
|---|---|
| Source Mapping | Hugging Face repository와 NuFi artifact URI의 매핑을 표시합니다 |
| Import History | Hugging Face Import 작업 상태, revision, commit, storage 정보를 표시합니다 |
| Import from Hugging Face | Hugging Face model repository를 Volume에 다운로드하고 모델 버전으로 등록합니다 |
Import from Hugging Face 필드
| 필드 | 설명 | 필수 |
|---|---|---|
| Repository | owner/name 형식의 Hugging Face 모델 repository | ✓ |
| Target Model | 기존 모델 선택 또는 새 모델 생성 선택 | ✓ |
| Target Version | 새로 등록할 버전. 기존 버전과 중복될 수 없습니다 | ✓ |
| Model Description | 새 모델을 생성할 때 사용할 설명 | - |
| Volume | 모델 파일을 저장할 Volume(PVC) | ✓ |
Hugging Face token 상태는 Import 다이얼로그 상단에 표시됩니다. 비공개 모델을 가져올 때 token이 없으면 프로젝트 설정에서 먼저 token을 저장하세요.
문제 해결
| 증상 | 확인 사항 |
|---|---|
| Validate가 실패함 | Volume과 Path가 실제 모델 루트를 가리키는지 확인합니다. MLflow 원본 구조라면 Integration Import 경로를 사용하는 것이 안전합니다 |
| 여러 모델이 감지됨 | 상위 폴더가 아니라 특정 모델 폴더를 선택합니다 |
| Quick Deploy가 비활성화됨 | 모델에 버전과 아티팩트가 있는지, 현재 platform이 0.1.0에서 배포 지원 대상인지 확인합니다 |
| Hugging Face Import가 실패함 | repository가 owner/name 형식인지, private 모델이면 프로젝트 Hugging Face token이 설정되어 있는지 확인합니다 |
| MLflow Import가 실패함 | Tracking URL, Run ID, Artifact Path가 올바른지 확인합니다 |