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

# MLflow

**머신러닝 실험 관리 및 모델 레지스트리 플랫폼**입니다. 머신러닝/딥러닝 실험의 파라미터, 메트릭, 모델을 추적하고 비교할 수 있습니다.

## 어디에 쓰이나요?

* **실험 추적(Tracking)**: 학습 파라미터(learning rate, batch size 등), 메트릭(accuracy, loss 등), 모델 파일을 기록하고 비교
* **모델 레지스트리**: 학습된 모델의 버전을 관리하고, Staging → Production 단계 전환
* **모델 서빙**: 등록된 모델을 REST API로 배포
* **재현성**: 실험 환경(코드, 데이터, 파라미터)을 기록하여 동일 결과 재현

PyTorch, TensorFlow, scikit-learn, XGBoost, HuggingFace 등 주요 머신러닝 프레임워크와 통합됩니다.

## Docker Compose

```yaml docker-compose.yml theme={null}
services:
  mlflow:
    image: ghcr.io/mlflow/mlflow:latest
    container_name: mlflow
    restart: unless-stopped
    ports:
      - "5000:5000"
    environment:
      - MLFLOW_BACKEND_STORE_URI=sqlite:///mlflow/mlflow.db
      - MLFLOW_DEFAULT_ARTIFACT_ROOT=/mlflow/artifacts
    volumes:
      - mlflow_data:/mlflow
    command: >
      mlflow server
      --host 0.0.0.0
      --port 5000
      --backend-store-uri sqlite:///mlflow/mlflow.db
      --default-artifact-root /mlflow/artifacts

volumes:
  mlflow_data:
```

### PostgreSQL 연동 구성

```yaml docker-compose.yml theme={null}
services:
  mlflow:
    image: ghcr.io/mlflow/mlflow:latest
    container_name: mlflow
    restart: unless-stopped
    ports:
      - "5000:5000"
    volumes:
      - mlflow_artifacts:/mlflow/artifacts
    command: >
      mlflow server
      --host 0.0.0.0
      --port 5000
      --backend-store-uri postgresql://postgres:changeme@mlflow-db:5432/mlflow
      --default-artifact-root /mlflow/artifacts
    depends_on:
      mlflow-db:
        condition: service_healthy

  mlflow-db:
    image: postgres:17-alpine
    container_name: mlflow-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=changeme
      - POSTGRES_DB=mlflow
    volumes:
      - mlflow_db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 3s
      timeout: 3s
      retries: 10

volumes:
  mlflow_artifacts:
  mlflow_db_data:
```

## 실행

```bash theme={null}
docker compose up -d
```

## 접속 확인

브라우저에서 `http://localhost:5000`으로 접속합니다.

## 기본 정보

| 항목        | 값           |
| --------- | ----------- |
| 웹 UI 포트   | 5000        |
| 기본 데이터베이스 | SQLite (내장) |

## Python SDK 연동

```python theme={null}
import mlflow

mlflow.set_tracking_uri("http://localhost:5000")
mlflow.set_experiment("my-experiment")

with mlflow.start_run():
    mlflow.log_param("learning_rate", 0.001)
    mlflow.log_metric("accuracy", 0.95)
    mlflow.log_artifact("model.pkl")
```

## 라이선스

| 구분     | 내용                       |
| ------ | ------------------------ |
| 라이선스   | Apache License 2.0       |
| 개인 사용  | 자유롭게 사용 가능               |
| 상업적 사용 | 자유롭게 사용 가능, 수정/재배포 제한 없음 |

## 참고

* [MLflow 공식 문서](https://mlflow.org/docs/latest/index.html)
* [MLflow GitHub](https://github.com/mlflow/mlflow)

## 설치 점검 목록

* `docker compose up -d` 후 `docker compose ps`로 컨테이너 상태를 확인했습니다.
* 기본 포트/계정/비밀번호를 문서대로 점검했습니다.
* 운영용으로 사용할 때 기본 비밀번호/시크릿 값을 변경했습니다.
* 장애 분석을 위해 `docker compose logs -f` 확인 방법을 숙지했습니다.

## 문제 해결 가이드

* 컨테이너가 실행되지 않으면 `docker compose logs -f`로 오류 원인을 먼저 확인합니다.
* 포트 충돌이 나면 기존 프로세스를 종료하거나 포트 매핑 값을 변경합니다.
* 이미지 pull 실패 시 네트워크 연결 및 레지스트리 접근 권한을 확인합니다.
* 설정 변경 후 문제가 지속되면 `docker compose down` 후 다시 `up -d`로 재기동합니다.

## 관련 문서

<CardGroup cols={2}>
  <Card title="Setup 홈" icon="house" href="/setup/index">
    운영체제별 설치 흐름을 다시 확인합니다.
  </Card>

  <Card title="다음: ClearML" icon="arrow-right" href="/stacks/clearml">
    다음 설치 단계를 이어서 진행합니다.
  </Card>
</CardGroup>