> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sifi.life/llms.txt
> Use this file to discover all available pages before exploring further.

# 기본 개념과 모델 등록 — 모델 레지스트리란?

> 이 문서는 **[머신러닝](/training/09-machine-learning/overview)** 섹션의 일부입니다.

## 모델 레지스트리란?

> **Model Registry(모델 레지스트리)** 는 학습된 ML 모델의 **버전을 관리** 하고, 프로덕션 승격(Promotion)을 제어하는 중앙 저장소입니다. Databricks에서는 **Unity Catalog** 와 통합되어, 모델에도 테이블과 동일한 거버넌스(권한, 리니지, 감사)가 적용됩니다.

***

## 1. 왜 모델 레지스트리가 필요한가

### 모델 관리 없이 운영할 때의 문제

실제 ML 운영 현장에서 레지스트리 없이 모델을 관리하면 다음과 같은 문제가 반복적으로 발생합니다.

**버전 혼란 (Version Chaos)**

* 파일 시스템에 `model_v2_final_FINAL.pkl` 같은 파일이 쌓입니다.
* 어떤 파일이 실제 프로덕션에 배포된 것인지 확인할 방법이 없습니다.
* 팀원이 실수로 구버전 모델을 배포하는 사고가 발생합니다.

**재현 불가 (Non-reproducibility)**

* 6개월 후 "이 모델을 어떻게 학습했지?"라는 질문에 답하기 어렵습니다.
* 어떤 데이터셋, 어떤 하이퍼파라미터로 학습했는지 추적이 끊깁니다.
* 동일한 코드로 재학습해도 결과가 달라지는 환경 의존성 문제가 생깁니다.

**감사 불가 (No Auditability)**

* 금융·의료 등 규제 산업에서는 "누가 이 모델을 승인했는가"를 입증해야 합니다.
* 모델 변경 이력이 없으면 컴플라이언스(Compliance) 감사를 통과할 수 없습니다.
* 인시던트(Incident) 발생 시 원인 추적이 불가능합니다.

| 문제               | Registry의 해결                                 |
| ---------------- | -------------------------------------------- |
| 어떤 버전이 프로덕션인지 모름 | **Alias** (champion, challenger)로 명확히 표시     |
| 이전 버전으로 롤백이 어려움  | 모든 **버전이 보존** 됨. Alias만 변경하면 롤백 완료           |
| 모델의 출처를 모름       | **Lineage(리니지)** 추적 — 어떤 데이터, 어떤 실험에서 생성되었는지 |
| 권한 관리가 어려움       | Unity Catalog의 **GRANT/REVOKE** 로 접근 제어      |
| 모델 변경 이력 추적      | 모든 변경이 **Audit Log(감사 로그)** 에 기록             |

***

## 2. Unity Catalog 기반 모델 레지스트리

### Workspace 레지스트리에서 UC 레지스트리로의 전환

Databricks는 원래 **Workspace Model Registry** 를 제공했습니다. 이는 Workspace 범위 내에서만 동작하는 격리된 레지스트리였습니다. 2023년부터 **Unity Catalog(UC) 기반 Model Registry** 가 권장 방식이 되었으며, 이유는 다음과 같습니다.

| 비교 항목         | Workspace 레지스트리  | UC 레지스트리                    |
| ------------- | ---------------- | --------------------------- |
| 범위            | 단일 Workspace     | Account 전체 (멀티 Workspace)   |
| 네임스페이스        | `model_name`     | `catalog.schema.model_name` |
| 권한 관리         | Workspace 수준 ACL | UC GRANT/REVOKE (세밀한 제어)    |
| 리니지 추적        | 제한적              | UC Lineage와 완전 통합           |
| Delta Sharing | 미지원              | 외부 조직과 모델 공유 가능             |
| 감사 로그         | Workspace 감사     | Account-level 통합 감사         |

### 3-Level Namespace (3단계 네임스페이스)

UC의 모든 오브젝트는 `catalog.schema.object` 형태의 3단계 네임스페이스를 사용합니다. 모델도 동일합니다.

```
ml_catalog                    ← Catalog (데이터 도메인 단위)
  └── fraud_detection         ← Schema (프로젝트/팀 단위)
        ├── tables/           ← 테이블
        ├── volumes/          ← 파일
        └── models/           ← ML 모델
              └── fraud_model ← 등록된 모델
```

모델의 전체 이름은 `ml_catalog.fraud_detection.fraud_model` 이 됩니다. 이 이름 하나로 버전 관리, 권한 부여, 리니지 추적이 모두 연결됩니다.

***

## 3. 모델 등록 방법

### 방법 1: 학습 중 직접 등록 (MLflow API)

```python theme={null}
import mlflow
from mlflow import MlflowClient

# Unity Catalog를 레지스트리로 지정
mlflow.set_registry_uri("databricks-uc")

# 실험(Experiment) 설정
mlflow.set_experiment("/Users/user@company.com/fraud-detection")

with mlflow.start_run(run_name="xgboost-v3") as run:
    # 모델 학습
    model.fit(X_train, y_train)

    # 메트릭 로깅
    mlflow.log_metric("accuracy", accuracy)
    mlflow.log_metric("f1_score", f1)

    # 모델 로깅 + 레지스트리 등록을 한 번에
    mlflow.sklearn.log_model(
        sk_model=model,
        artifact_path="model",
        registered_model_name="ml_catalog.fraud_detection.fraud_model"  # UC 3-level 이름
    )
```

### 방법 2: 기존 Run에서 사후 등록

```python theme={null}
# 이미 완료된 Run의 모델을 나중에 레지스트리에 등록
run_id = "a1b2c3d4e5f6..."
model_uri = f"runs:/{run_id}/model"

model_version = mlflow.register_model(
    model_uri=model_uri,
    name="ml_catalog.fraud_detection.fraud_model"
)
print(f"등록된 버전: {model_version.version}")
```

### 방법 3: UI에서 등록

1. Databricks 좌측 메뉴 → **Experiments** 진입
2. 실험 Run 클릭 → **Artifacts** 탭 선택
3. `model` 폴더 클릭 → **Register Model** 버튼 클릭
4. 모델 이름을 `catalog.schema.model_name` 형식으로 입력
5. **Register** 클릭 → 새 버전 자동 생성

### 방법 4: 자동 등록 (autolog)

```python theme={null}
# MLflow autolog 사용 시 모델도 자동 로깅
mlflow.sklearn.autolog(
    registered_model_name="ml_catalog.fraud_detection.fraud_model"
)

with mlflow.start_run():
    model.fit(X_train, y_train)
    # 학습이 끝나면 자동으로 모델 등록
```

***