CDP 규칙 가이드

MLOps 규칙 가이드
전체 개요

gsr_ml_lab_cdp 프레임워크 사용자를 위한 핵심 원칙 5가지

CDP 핵심 원칙

gsr_ml_lab_cdp 프레임워크의 철학과 5가지 필수 규칙

프레임워크의 핵심 철학

"DS는 S3 경로와 MLflow run_id를 직접 다루지 않는다."

gsr_ml_lab_cdp는 실험 재현성과 팀 표준화를 위해 경로, 이름, 기록을 모두 프레임워크가 자동 관리합니다. DS는 YAML 3개를 작성하고, ctx API로 데이터를 저장/읽고, ctx.finish()로 실험을 마무리하면 됩니다.

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

원칙 1

YAML은 3개만, 추가 금지

파일	역할	작성 주체
`project/project.yaml`	팀 공통 설정 (bucket, mlflow url, 참여자)	팀 리드 or 프로젝트 초기
`project/{model_dir}/config/model.yaml`	실험 정의 (알고리즘, 하이퍼파라미터)	실험 DS
`project/{model_dir}/config/user.yaml`	실험 메모 (선택)	실험 DS

⚠️ yaml 파일 추가는 금지입니다. 3개 외에 새 yaml 파일을 만들면 프레임워크가 인식하지 못합니다.

원칙 2

workers_id는 반드시 사전 등록

# project/project.yaml
workers_id:
  - hjsong      # ← 목록에 없는 ID로 실행하면 ValueError
  - jylee
  - mskim

⚠️ 새 DS가 합류하면 반드시 workers_id에 먼저 추가한 후 실험을 실행하세요.

원칙 3

model_dir 이름 규칙을 지켜라

model_dir_name = experiment_topic + "_" + algorithm

올바른 예:  titanic_lightgbm/
            demand_forecast_xgboost/

틀린 예:    titanic-lgbm/          ← 구분자가 "_" 이어야 함
            my_experiment/          ← algorithm 이 없음

⚠️ model.yaml의 experiment_topic + "_" + algorithm과 디렉토리명이 불일치하면 ValueError 발생.

원칙 4

데이터는 ctx API로만 저장

데이터 종류	올바른 방법	금지
전처리 대용량 데이터	`ctx.save_data(df, "X_train.parquet")`	`pd.to_parquet("data/X_train.parquet")`
step 간 모델/메타	`ctx.save_step(model, "model.pkl")`	`pickle.dump(model, open("model.pkl","wb"))`
최종 산출물	`ctx.save_output(fig, "chart.png", folder="charts")`	`fig.savefig("output/chart.png")`

⚠️ ctx.output 경로 밖에 저장한 파일은 S3 sync 대상이 아닙니다. 실험 기록에서 누락됩니다.

원칙 5

하드코딩 대신 YAML에 필드 추가

# ❌ 하드코딩
THRESHOLD = 0.5
N_ESTIMATORS = 300

# ✅ model.yaml에 추가 후 ctx로 참조
threshold    = ctx.model['threshold']
n_estimators = ctx.model['algorithm']['params']['n_estimators']

자주 발생하는 에러와 원인

에러	원인	해결 방법
`ValueError: worker_id not in workers_id`	project.yaml에 내 ID 미등록	workers_id 목록에 추가
`ValueError: directory name mismatch`	디렉토리명과 experiment_topic_algorithm 불일치	디렉토리명 또는 yaml 수정
`ValueError: reserved key`	yaml에 예약어 사용	다른 키 이름 사용 (아래 목록 참조)
`ValueError: folder not allowed`	save_output에 허용되지 않은 folder	model/charts/metrics/reports 중 하나 사용
`ConflictError`	step 간 동일 파일명	파일명 고유하게 수정
`TokenRetrievalError`	AWS SSO 토큰 만료	`! aws sso login --profile gsr_cdp` 재실행

예약어 목록 (yaml 키로 사용 금지)

run_id          test_dt         current_dt      dry_run
stage           run_name        run_name_base   project_root
model_dir_name  runs_root       run_dir         input_dir
output_dir      artifacts_dir   logger
mlflow_experiment_name          commit_hash     commit_msg
branch_name     config_hashes   duration_seconds keep_local_runs

가이드 목차

파일	내용
이 파일	전체 원칙 요약
YAML 설정 규칙	YAML 3개 파일 작성법 상세
데이터 저장 계층	ctx API 3-tier 저장 규칙
네이밍 규칙	네이밍 & S3/MLflow 경로 규칙
개발환경 설정	AWS SSO, Bitbucket 환경 설정

MLOps 규칙 가이드전체 개요