모델 등록

볼륨에 저장된 모델 파일을 NuFi에 등록하여 컴파일·평가·서빙에서 사용할 수 있도록 합니다. 모델은 직접 등록하거나, Hugging Face 또는 MLflow에서 가져올 수 있습니다.

---

방법 A: 직접 다운로드한 모델 등록

03. 모델 다운로드에서 볼륨에 다운로드한 모델을 등록하는 방법입니다.

1. 모델 등록 메뉴 이동

좌측 사이드바에서 Resources > Models를 클릭하고 Register Model 버튼을 누릅니다.

2. 모델 정보 입력

필드	예시 값	설명
Model Name	qwen-instruct-tutorial	모델 식별 이름
Description	-	모델 설명 (선택)
Author	-	작성자 (선택)

3. 아티팩트 추가

모델 등록 후 목록에서 등록한 모델을 클릭하여 상세 화면으로 이동합니다. Add Version 버튼을 클릭하여 아티팩트를 추가합니다.

필드	설명
Version	아티팩트 버전
Volume	모델 파일이 저장된 볼륨 선택
Path	볼륨 내 모델 파일 경로. 입력창 옆 폴더 아이콘을 클릭하면 경로 목록이 표시되며, 선택 버튼을 누르면 하단 Validate 버튼이 활성화됨
Format	모델 포맷 (예: SafeTensors)
Description	버전 설명 (선택)
Author	작성자 (선택)

Validate 버튼이 초록색으로 활성화되면 등록 버튼을 클릭합니다.

4. 등록 확인

Models 목록에서 등록한 모델을 클릭하면 추가된 아티팩트를 확인할 수 있습니다.

---

방법 B: NFS 경로의 모델 등록

NAS에 이미 모델 파일이 있는 경우, NFS 볼륨을 연결하여 바로 등록하는 방법입니다.

사전 조건

01. 볼륨 생성에서 NAS 경로가 연결된 NFS 볼륨이 생성되어 있어야 합니다.

1, 2단계는 방법 A와 동일합니다. Model Name은 qwen-instruct-tutorial-nfs로 입력합니다.

3. 아티팩트 추가

방법 A와 동일하게 진행하되, Volume에서 NFS 볼륨(tutorial-volume-nfs)을 선택합니다.

4. 등록 확인

추가된 아티팩트를 확인할 수 있습니다.

---

방법 C: Hugging Face Import

Hugging Face Hub의 모델 repository를 NuFi 볼륨에 다운로드하고, Model Registry에 자동 등록하는 방법입니다. 03. 모델 다운로드 단계를 직접 수행하지 않고 대시보드에서 가져올 때 사용합니다.

사전 조건

• 모델을 저장할 Volume이 생성되어 있어야 합니다. 이 튜토리얼에서는 tutorial-volume을 사용합니다.
• 비공개 Hugging Face 모델을 가져오려면 프로젝트 설정에서 Hugging Face token을 먼저 저장해야 합니다.

1. Hugging Face Integration 메뉴 이동

좌측 사이드바에서 Resources > Models를 클릭하고 Integration 버튼을 누릅니다. 상단에서 Hugging Face 탭을 선택한 뒤 Import from Hugging Face 버튼을 클릭합니다.

2. Hugging Face Import 정보 입력

필드	예시 값	설명
Repository	Qwen/Qwen2.5-0.5B-Instruct	owner/name 형식의 Hugging Face 모델 repository
Target Model	New model	새 모델을 만들지, 기존 모델에 버전을 추가할지 선택
Target Model 이름	qwen-instruct-tutorial-hf	NuFi에 등록될 모델 이름
Target Version	v1	새로 등록할 버전. 기존 버전과 중복될 수 없습니다
Model Description	HF imported model	새 모델 생성 시 사용할 설명 (선택)
Volume	tutorial-volume	모델 파일을 다운로드할 볼륨

상단의 Hugging Face token 상태가 설정됨이면 private repository도 가져올 수 있습니다. 미설정이어도 public repository는 가져올 수 있습니다.

3. Import 시작

Start Import 버튼을 클릭하면 백그라운드 Import Job이 생성됩니다. Import가 진행되는 동안 모델 파일이 선택한 Volume에 다운로드되고, 완료되면 Model Registry에 모델 버전과 아티팩트가 생성됩니다.

4. Import 완료 확인

Hugging Face 탭의 Import History에서 작업 상태가 Succeeded로 바뀌었는지 확인합니다. Source Mapping 탭에서는 Hugging Face repository와 NuFi artifact URI의 연결을 확인할 수 있습니다.

5. 모델 등록 확인

좌측 사이드바에서 Resources > Models로 돌아가면 qwen-instruct-tutorial-hf 모델이 등록되어 있습니다. 모델 상세에서 v1 버전을 열고 Artifacts 탭에서 다운로드된 원본 아티팩트를 확인합니다.

팁

Hugging Face Import는 Hub에서 모델을 다운로드하는 작업까지 NuFi가 처리합니다. 이미 Lab에서 직접 다운로드한 모델을 등록하는 경우에는 방법 A를 사용하세요.

---

방법 D: MLflow Integration

MLflow Tracking Server에 등록된 모델을 NuFi로 가져오는 방법입니다.

MLflow에서 실험을 진행하고 mlflow.log_model() 등으로 모델을 등록해 두었다면, NuFi의 MLflow Integration 기능으로 해당 모델을 볼륨에 다운로드하고 바로 등록할 수 있습니다. MLflow UI에서 모델의 Tracking URI, 모델명, 버전을 미리 확인해 두세요.

사전 조건

MLflow 서버가 NuFi 클러스터 내에서 접근 가능해야 합니다.

1. MLflow Integration 메뉴 이동

좌측 사이드바에서 Resources > Models를 클릭하고 Integration 버튼을 누릅니다. MLflow 탭에서 Add Webhook 버튼을 클릭하여 MLflow 정보를 입력합니다.

2. MLflow 정보 입력

필드	예시 값	설명
Name	tutorial-webhook	Webhook 이름
MLflow URL	http://192.168.10.160:5000	MLflow Tracking Server 주소
Target Model	Qwen2.5-0.5B-Instruct	MLflow에 등록된 모델명
Storage PVC	tutorial-volume	모델 파일이 저장될 볼륨
Auto Import	true	모델 버전 생성 시 자동 import 여부

Webhook이 등록되면 Receive URL이 생성됩니다. 이 URL을 복사해 둡니다.

3. MLflow에 Receive URL 등록

Webhook 등록 후, NuFi의 Receive URL을 MLflow에 등록해야 합니다. MLflow에서 모델 버전이 생성될 때 NuFi로 알림을 보내도록 연결합니다.

from mlflow import MlflowClient

client = MlflowClient(tracking_uri="http://192.168.10.160:5000")
webhook = client.create_webhook(
    name="tutorial-webhook",
    url="https://api.nufi.me/api/v1/models/integration/mlflow/webhooks/11/receive",  # Receive URL
    events=["model_version.created"],
    description="NuFi MLflow model_version.created webhook",
)
print(f"webhook_id={webhook.webhook_id}")
print("[OK] 완료")

4. Integration 완료 확인

MLflow에서 모델이 등록되면 NuFi로 자동으로 가져옵니다. Import Job 상태가 Succeeded로 바뀌면 선택한 볼륨에 모델 파일이 저장되고, Models 목록에 자동으로 등록됩니다.

---

다음 단계

→ 05. NPU 컴파일 — RNGD NPU용 바이너리로 컴파일
→ 06. 모델 서빙 배포 — 컴파일 없이 GPU 서빙만 할 경우