ML 파이프라인 구축

이 튜토리얼에서 무엇을 배우나요?

이 튜토리얼은 Runway 위에서 ML 파이프라인을 처음부터 실행해보는 실습입니다.

풍력 터빈 데이터로 발전량을 예측하는 모델을 예제로 사용하지만, 모델 자체보다 파이프라인이 어떻게 돌아가는지가 핵심입니다.

튜토리얼을 마치면 아래 경험을 직접 해볼 수 있습니다:

• Gitea에 코드를 올리면 Airflow가 자동으로 인식하는 구조
• Airflow DAG가 무엇인지, 코드로 어떻게 구성하는지
• DAG의 각 Task가 단계별로 실행되며 학습이 진행되는 흐름
• MLflow에 학습 결과를 기록하는 코드 구성 방식
• 학습된 모델을 Endpoint로 배포하고 추론 요청을 보내는 과정

시작 전 확인 — 이런 경험이 있어야 합니다

• Python 기초: 함수, 클래스, 라이브러리 import 수준의 코드를 읽고 수정할 수 있어야 합니다.
• Git 기본 사용: git add, git commit, git push 명령을 직접 실행할 수 있어야 합니다.
• 머신러닝 기초 개념: 학습/검증 데이터 분리, 모델 학습, 평가 지표(RMSE 등)의 개념을 알고 있어야 합니다.
• 터미널 사용: 명령줄에서 기본 명령을 실행할 수 있어야 합니다.

위 항목이 낯설다면 입문 수준의 Python 및 Git 학습 후 진행하는 것을 권장합니다.

용어 알아보기

• Gitea: 오픈소스 Git 저장소 서비스. GitHub과 유사하며, 이 튜토리얼에서는 DAG 코드를 저장하고 Airflow와 연동하는 용도로 사용합니다.
• Airflow: 워크플로우 스케줄링 도구. DAG 파일을 읽어 Task를 순서대로 실행하고 상태를 모니터링합니다.
  • DAG (Directed Acyclic Graph): 방향이 있고 순환이 없는 그래프 구조. Airflow에서는 데이터 파이프라인의 전체 흐름을 DAG로 정의하며, 각 단계를 Task로 표현합니다.
  • Task: DAG를 구성하는 개별 실행 단위. 데이터 로드, 모델 학습, 결과 저장 등 각 단계가 하나의 Task로 정의됩니다.
• MLflow: 머신러닝 실험 추적 및 모델 관리 도구. 학습 파라미터, 메트릭, 모델 파일을 기록하고 버전을 관리합니다.
• Argo CD: GitOps 기반 배포 자동화 도구. Runway에서 Inference Endpoint 배포 상태 관리에 사용됩니다.
• PVC (Persistent Volume Claim): Kubernetes에서 영구 저장소를 요청하는 단위. 컨테이너가 재시작되어도 데이터가 유지됩니다.
• S3: 오브젝트 스토리지 서비스 규격. Runway에서는 MLflow 모델 아티팩트 저장에 S3 호환 스토리지를 사용합니다.

---

이 튜토리얼에서 사용하는 도구

Runway는 ML 워크플로우에 필요한 오픈소스 도구들을 플랫폼 안에서 통합 제공합니다. 각 도구가 어떤 역할을 하는지, 사용자가 실제로 접하는 화면은 무엇인지 미리 파악해두세요.

플랫폼 앱 — Runway 워크스페이스 > 플랫폼 앱 메뉴에서 제공되는 오픈소스 애플리케이션입니다.

플랫폼 앱	사용자 접근 방식	이 튜토리얼에서의 역할
Gitea	Code-server에서 git push	DAG 코드 저장 및 Airflow 연동
Airflow	Airflow UI	모델 학습 워크플로우 실행
MLflow	MLflow UI	학습 결과 및 모델 버전 확인
Argo CD	Argo CD UI (간접 사용)	Inference Endpoint 배포 상태 확인

Runway 기본 기능 — 별도 설치 없이 Runway에 내장되어 있습니다.

기능	사용자 접근 방식	이 튜토리얼에서의 역할
스토리지 (S3 / PVC)	Runway 메뉴에서 생성 · 코드에서 연동	모델 파일 저장
Inference Endpoint	Runway 메뉴 / REST API	배포된 모델에 예측 요청

---

Runway에서 ML 파이프라인이 동작하는 방식

Runway는 ML 워크플로우에 필요한 오픈소스 도구들을 하나의 플랫폼 안에서 연결해서 제공합니다. 이 튜토리얼에서 사용하는 도구의 흐름은 아래와 같습니다.

flowchart LR
    subgraph runway["Runway 플랫폼"]
        subgraph dev["개발 환경 (프로젝트)"]
            CS["Code-server\n코드 작성"]
        end

        subgraph platform["플랫폼 앱 (워크스페이스 공용)"]
            GT["Gitea\nDAG 코드 저장소"]
            AF["Airflow\n파이프라인 실행"]
            ML["MLflow\n실험 기록 & 모델 등록"]
            S3["S3\n모델 파일 저장"]
        end
    end

    CS -->|"git push"| GT
    GT -->|"자동 동기화"| AF
    AF -->|"Task 순차 실행"| ML
    AF -->|"모델 파일 저장"| S3
    ML -.->|"아티팩트 경로 참조"| S3

---

왜 이렇게 연결되어 있나요?

각 도구가 연결된 이유를 하나씩 짚어봅니다.

Gitea → Airflow: 코드를 올리면 파이프라인이 준비된다

Runway에서 각 프로젝트는 생성될 때 Airflow 전용 Gitea 레포지토리(airflow-dag)를 자동으로 받습니다. Airflow는 이 레포지토리를 지속적으로 바라보고 있어서, 코드를 push하면 별도 설정 없이 Airflow가 DAG를 인식합니다.

코드 수정 → git push → Gitea → (자동 동기화) → Airflow에 DAG 반영

Airflow Task: 각 단계는 독립된 실행 단위다

Airflow의 파이프라인(DAG)은 여러 Task로 구성됩니다. 중요한 점은 각 Task가 독립적으로 실행된다는 것입니다. 한 Task가 끝나면 그 안에서 만든 임시 데이터는 기본적으로 사라집니다.

Task 1 실행·종료   →   Task 2 실행·종료   →   Task 3 실행·종료
 [데이터 로드]           [모델 학습]             [결과 평가]
      │                      ↑
      └── /tmp 경로로 전달 ───┘

그래서 Task 간에 데이터를 전달할 때는 임시 경로(/tmp)를 사용하고, 파이프라인이 끝난 뒤에도 남겨야 하는 결과물(학습된 모델 등)은 반드시 외부 저장소에 저장해야 합니다.

복잡해 보이지만, 직접 설정할 건 많지 않습니다

Gitea와 Airflow의 연결, MLflow와 S3의 연동은 Runway가 이미 구성해두었습니다. 이 튜토리얼에서 직접 해야 할 일은 코드에 인증 정보를 입력하고 Gitea에 push하는 것이 전부입니다.

MLflow + S3: 결과를 남기는 두 가지 저장소

학습 결과는 성격에 따라 두 곳에 나눠 저장합니다.

저장소	저장되는 것	역할
MLflow	하이퍼파라미터, 메트릭(RMSE 등), 모델 버전 정보	실험 기록장 — 어떤 조건으로 학습했고 성능이 어떤지 비교
S3	실제 모델 파일	파일 보관함 — 모델을 나중에 꺼내 쓸 수 있도록 보존

MLflow에서 모델을 등록하면 실제 파일은 S3에 저장되고, MLflow는 그 위치를 기록해둡니다.

---

전체 흐름

flowchart TD
    A["시작 전 준비 (공통)\nWorkspace · Project ID 확인 · 액세스 키 발급"]
    B["1 단계. 환경 준비\n스토리지 생성 · Code-server 배포 · Gitea 연결"]
    C["2 단계. 코드 준비\nDAG 파일 설정 · Gitea에 push"]
    D["3 단계. 파이프라인 실행\nAirflow DAG 트리거 · 실행 상태 확인"]
    E["4 단계. 결과 확인\nMLflow 실험 결과 · 모델 등록 확인"]
    F["5 단계. 모델 배포 & 추론\nEndpoint 생성 · 모델 배포 · 추론 요청"]

    A --> B --> C --> D --> E --> F