CDP 실험 관리

S3 Naming Convention
& 실험 파이프라인

실험 설정을 어디에, 어떻게 저장할지 — 조직 표준을 이해합니다.

CDP 실험 관리

S3 파이프라인

실험 설정을 어디에, 어떻게 저장할지 — 조직 표준을 이해합니다.

S3가 MLOps에서 하는 역할

"S3는 실험 기록 창고입니다."

실험을 재현하려면 세 가지가 필요합니다.

무엇이 필요한가어디에 저장하는가
실험에 사용한 설정 (하이퍼파라미터, 환경)S3 — 실험별 input/
학습에 사용한 데이터S3 — data/{test_dt}/
학습 결과 (모델, 차트, 지표, 리포트)S3 — 실험별 output/

이 과정에서 사용하는 프레임워크

실습에서는 gsr_ml_lab_cdp (Bitbucket: DS_LAB/gsr_ml_lab_cdp) 프레임워크를 사용합니다.

"DS는 S3 경로를 직접 조립하지 않는다."

DS는 YAML 3개를 작성하고, ctx API로 데이터를 저장/읽고, ctx.finish()로 실험을 마무리합니다. 경로 생성, MLflow 등록, 리포트 생성, S3 업로드는 프레임워크가 자동으로 처리합니다.

[DS가 하는 일]              [프레임워크가 자동으로 하는 일]
YAML 3개 작성           →   S3 경로 생성 및 관리
ctx.save_data(df)       →   data/{test_dt}/ 에 저장 + S3 sync
ctx.save_step(model)    →   steps/{step_name}/ 에 저장 + S3 sync
ctx.finish(metrics=...) →   MLflow 등록 + 리포트 생성 + S3 업로드

프로젝트 로컬 디렉토리 구조

project/
├── project.yaml                          ← 팀 공통 설정 (버킷, 참여자, mlflow url)
└── {experiment_topic}_{algorithm}/       ← 내 실험 디렉토리
    ├── config/
    │   ├── model.yaml                    ← 실험 정의 (필수)
    │   └── user.yaml                     ← 실험 메모 (선택)
    ├── data/{test_dt}/                   ← 전처리 데이터 (ctx.save_data)
    │   ├── X_train.parquet
    │   └── y_train.parquet
    ├── steps/                            ← step 간 경량 아티팩트 (ctx.save_step)
    │   ├── 01_preprocess/
    │   ├── 02_train/
    │   └── 03_evaluate/
    └── runs/{run_id}/                    ← 최종 산출물 (ctx.finish)
        ├── input/
        │   ├── project.yaml
        │   └── model.yaml
        └── output/
            ├── run_manifest.yaml
            ├── run.log
            ├── metrics/
            ├── charts/
            ├── reports/
            └── model/

S3 경로 구조

S3의 구조는 로컬 디렉토리와 1:1로 대응됩니다. 프레임워크가 자동으로 sync합니다.

s3://{bucket}/{env_nm}/{project_nm}/{worker_id}/
└── {model_dir_name}/
    ├── data/{test_dt}/                   ← 전처리 데이터 (Tier 1)
    │   ├── X_train.parquet
    │   └── y_train.parquet
    ├── steps/{step_name}/latest/         ← step 아티팩트 (Tier 2)
    └── runs/{run_id}/                    ← 최종 산출물 (Tier 3)
        ├── input/
        └── output/
            ├── run_manifest.yaml
            ├── metrics/
            ├── charts/
            ├── reports/
            └── model/

경로를 구성하는 변수:

변수출처예시
bucketproject.yaml → environments.dev.bucketgs-cdp-mllab-dev
env_nmmodel.yaml → env_nmdev
project_nmproject.yaml → project_nmml_lab_titanic
worker_idmodel.yaml → worker_idhjsong
model_dir_name디렉토리명 (= experiment_topic + "_" + algorithm)titanic_survival_lightgbm
run_id프레임워크 자동 생성20260526_143012_a3f9bc
ℹ️ 이 변수들을 코드에서 직접 조합해 경로를 만들지 마세요. 프레임워크의 ctx API가 내부적으로 처리합니다.

YAML 설정 파일 작성법

실험은 세 개의 YAML 파일로 정의합니다.

project.yaml — 팀 공통 (프로젝트 시작 시 1회 작성)

📋 복사해서 붙여넣기

# project/project.yaml
project_nm: ml_lab_titanic           # S3 경로와 MLflow experiment_name에 사용

workers_id:                          # 참여 DS 목록 (목록에 없으면 실험 실행 불가)
  - hjsong
  - jylee

region: ap-northeast-2

environments:
  dev:
    bucket: gs-cdp-mllab-dev
    mlflow_url: https://dpa-mlflow.dp.gslook.com/
  prd:
    bucket: gs-cdp-mllab-prd
    mlflow_url: https://dpa-mlflow.dp.gslook.com/

model.yaml — 내 실험 정의 (실험마다 작성)

📋 복사해서 붙여넣기

# project/titanic_survival_lightgbm/config/model.yaml
worker_id: hjsong                    # 본인 ID (project.yaml workers_id에 있어야 함)
experiment_topic: titanic_survival   # 실험 주제
algorithm: lightgbm                  # 알고리즘

env_nm: dev                          # dev 또는 prd

data_sources:
  - name: train
    path: s3://gs-cdp-mllab-dev/titanic/data/train.csv

algorithm_params:                    # 하이퍼파라미터 — 코드에 하드코딩하지 않고 여기에 작성
  n_estimators: 300
  learning_rate: 0.05
  max_depth: 6

task_type: classification            # classification / regression / ranking / clustering
target_col: Survived
⚠️ 디렉토리명 규칙: experiment_topic + "_" + algorithm 이 디렉토리명과 일치해야 합니다. 위 예시에서 디렉토리는 반드시 titanic_survival_lightgbm/ 이어야 합니다. 불일치 시 ValueError 발생.

user.yaml — 실험 메모 (선택)

# project/titanic_survival_lightgbm/config/user.yaml
experiment_note: "encoding v2 적용 버전. 이전 대비 AUC +0.03"
reference_run: "20260520_143012_a3f9bc"

실험 실행 흐름 — ctx API

Step 1
01_preprocess
ctx.save_data()
→
Step 2
02_train
ctx.save_step()
→
Step 3
03_evaluate
ctx.finish()

데이터 저장/읽기 3계층

계층용도저장읽기
datastep 간 공유 대용량 데이터ctx.save_data(df, "X_train.parquet")ctx.read_data("X_train.parquet")
stepstep 간 경량 아티팩트 (모델, 인코더)ctx.save_step(model, "model.pkl")ctx.read_step("model.pkl")
output최종 산출물ctx.save_output(fig, "chart.png", folder="charts")—

실험 마무리 — ctx.finish()

마지막 step 끝에 반드시 호출합니다.

📋 복사해서 붙여넣기

ctx.finish(
    metrics={"auc": 0.912, "f1": 0.873},   # → output/metrics/metrics.json 자동 저장
    y_true=y_test,                           # → 표준 차트 자동 생성 (ROC, Confusion Matrix 등)
    y_pred=y_pred,
    y_prob=y_prob,
)
# ctx.finish() 자동 처리:
# ✅ output/reports/experiment_report.html 생성
# ✅ MLflow에 run 등록 (experiment_name: {project_nm}_{worker_id})
# ✅ S3에 runs/{run_id}/output/ 전체 업로드
ℹ️ ctx.finish()를 호출하지 않으면 실험이 S3와 MLflow에 기록되지 않습니다.

결과 확인

S3에서 확인

📋 복사해서 붙여넣기

# 내 실험 run 목록 확인
aws s3 ls s3://gs-cdp-mllab-dev/dev/ml_lab_titanic/hjsong/titanic_survival_lightgbm/runs/ \
    --profile gsr_cdp

# 특정 run 산출물 확인
aws s3 ls s3://gs-cdp-mllab-dev/dev/ml_lab_titanic/hjsong/titanic_survival_lightgbm/runs/{run_id}/output/ \
    --profile gsr_cdp --recursive

MLflow에서 확인

🌐 MLflow UI: https://dpa-mlflow.dp.gslook.com/

  • Experiment: {project_nm}_{worker_id} (예: ml_lab_titanic_hjsong)
  • Run name: {model_dir_name}-{test_dt}-{current_dt}

run_manifest.yaml에서 확인

# run_manifest.yaml 주요 항목
identity:
  env_nm: dev
  project_nm: ml_lab_titanic
  worker_id: hjsong
  experiment_topic: titanic_survival
  algorithm: lightgbm
metrics:
  auc: 0.912
  f1: 0.873
status: success

결과 확인 체크리스트

☐확인 항목
☐project.yaml에 내 worker_id가 workers_id 목록에 있는가?
☐디렉토리명이 experiment_topic + "_" + algorithm과 일치하는가?
☐model.yaml의 algorithm_params에 하이퍼파라미터를 넣었는가? (하드코딩 금지)
☐마지막 step에서 ctx.finish(metrics=...)를 호출했는가?
☐S3 버킷에 runs/{run_id}/ 폴더가 생성됐는가?
☐MLflow에서 내 run이 보이는가?
ℹ️ 세부 규칙은 CDP 규칙 가이드 (좌측 사이드바)를 참조하세요.