CDP 규칙 가이드

네이밍 & 경로 규칙

model_dir, run_id, S3 트리, MLflow — 프레임워크가 자동 생성하는 이름의 규칙

네이밍 규칙

DS가 직접 정하는 이름과 프레임워크가 자동 생성하는 이름의 구분

이름	누가 정하는가	규칙
`model_dir_name`	DS (디렉토리 생성 + yaml 작성)	`experiment_topic + "_" + algorithm`
`run_id`	프레임워크 자동	`{YYYYMMDD}_{HHMMSS}_{6hex}`
`test_dt`	프레임워크 자동	`{YYYYMMDD}` (실험 실행일)
`experiment_name`	프레임워크 자동	`{project_nm}_{worker_id}`
`run_name`	프레임워크 자동	`{model_dir_name}-{test_dt}-{current_dt}`

ℹ️ DS가 직접 경로를 조립하거나 run_id를 생성할 필요가 없습니다.

model_dir_name 규칙

model_dir_name = f"{experiment_topic}_{algorithm}"

올바른 예시

model.yaml                          디렉토리명
─────────────────────────────────── ──────────────────────────────────────
experiment_topic: titanic_survival  titanic_survival_lightgbm/
algorithm: lightgbm

experiment_topic: demand_forecast   demand_forecast_xgboost/
algorithm: xgboost

experiment_topic: customer_churn    customer_churn_catboost/
algorithm: catboost

틀린 예시

❌ titanic-lightgbm/       ← 구분자가 "_" 이어야 함 (하이픈 X)
❌ my_titanic_exp/         ← algorithm 부분이 없음
❌ Titanic_LightGBM/       ← 대문자 사용 (소문자 권장)
❌ titanic_lightgbm_v2/    ← 버전을 이름에 넣지 않음 (run_id로 구분)

⚠️ model.yaml의 experiment_topic + "_" + algorithm과 디렉토리명이 불일치하면 ValueError: directory name mismatch가 발생합니다.

S3 경로 전체 구조

s3://{bucket}/{env_nm}/{project_nm}/{worker_id}/
    ├── config/
    │   └── mlflow_auth.json          ← 프레임워크 자동 생성
    └── {model_dir_name}/
        ├── data/{test_dt}/           ← ctx.save_data 저장 (Tier 1)
        │   ├── X_train.parquet
        │   └── y_train.parquet
        ├── steps/                    ← ctx.save_step 저장 (Tier 2)
        │   ├── 01_preprocess/latest/
        │   ├── 02_feature/latest/
        │   └── 03_train/latest/
        └── runs/{run_id}/            ← ctx.finish 최종 산출물 (Tier 3)
            ├── input/
            │   ├── project.yaml
            │   ├── model.yaml
            │   └── user.yaml         (존재할 때만)
            └── output/
                ├── run_manifest.yaml
                ├── run.log
                ├── executed_{step}.ipynb   ← papermill 결과
                ├── metrics/
                │   └── metrics.json
                ├── charts/
                ├── reports/
                │   └── experiment_report.html
                ├── model/
                │   └── model.pkl           ← save_step(model) 자동 복사
                └── steps/                  ← step 스냅샷

로컬 경로 구조

project/
└── {model_dir_name}/
    ├── config/
    │   ├── model.yaml
    │   └── user.yaml                (선택)
    ├── data/{test_dt}/              ← ctx.save_data 로컬 저장 (Tier 1)
    ├── steps/                       ← ctx.save_step 로컬 저장 (Tier 2)
    │   ├── 01_preprocess/
    │   ├── 02_feature/
    │   └── 03_train/
    └── runs/{run_id}/               ← ctx.finish 로컬 저장 (Tier 3)
        ├── input/
        └── output/

로컬 vs S3 경로 대응표

로컬 경로	S3 경로
`project/{model_dir}/data/{test_dt}/`	`s3://{bucket}/{env_nm}/{project_nm}/{worker_id}/{model_dir}/data/{test_dt}/`
`project/{model_dir}/steps/{step}/`	`s3://{bucket}/{project_nm}/{worker_id}/{model_dir}/steps/{step}/latest/`
`project/{model_dir}/runs/{run_id}/output/`	`s3://{bucket}/{env_nm}/{project_nm}/{worker_id}/{model_dir}/runs/{run_id}/output/`

ℹ️ steps/의 S3 경로는 {env_nm}이 없는 점에 주의하세요. 또한 latest/로 관리되므로 이전 run의 step 결과는 S3에서 덮어써집니다 (로컬에는 남음).

MLflow 네이밍 규칙

# 프레임워크가 자동으로 생성하는 MLflow 이름
experiment_name = f"{project_nm}_{worker_id}"
# 예: "ml_lab_test_hjsong"

run_name = f"{model_dir_name}-{test_dt}-{current_dt}"
# 예: "titanic_survival_lightgbm-20260526-20260526_143012"

⚠️ 직접 MLflow experiment나 run을 생성하지 마세요. ctx.finish()가 자동으로 처리합니다.

MLflow에서 내 실험을 찾는 방법:

experiment_name 필터: {project_nm}_{worker_id}로 검색
run_name 패턴: {model_dir_name}-{test_dt}...

경로 변수 정리

변수	출처	예시
`bucket`	`project.yaml → environments.{env_nm}.bucket`	`gs-cdp-mllab-dev`
`env_nm`	`model.yaml → env_nm`	`dev`
`project_nm`	`project.yaml → project_nm`	`ml_lab_test`
`worker_id`	`model.yaml → worker_id`	`hjsong`
`model_dir_name`	디렉토리명 (= experiment_topic + "_" + algorithm)	`titanic_survival_lightgbm`
`run_id`	프레임워크 자동 생성	`20260526_143012_a3f9bc`
`test_dt`	프레임워크 자동 생성 (실행일)	`20260526`
`step_name`	`setup_experiment(step=...)` 인자 또는 `STEP_NAME` env var	`01_preprocess`

실행 모드별 산출물 위치

모드	언제 사용	최종 산출물 위치
`(local, None)`	Jupyter 직접 실행, 개발·디버깅	로컬 `runs/{run_id}/output/` (S3 업로드 없음)
`(sm-job, step)`	SageMaker에서 step별 실행	S3 `steps/{step_name}/latest/` (run 산출물 없음)
`(sm-job, full)`	SageMaker에서 full 실행	S3 `runs/{run_id}/output/` (전체 산출물)

ℹ️ 개발 중에는 (local, None) 모드로 빠르게 반복하고, 최종 실험 기록은 (sm-job, full) 모드로 SageMaker에서 실행해 S3에 남기는 것을 권장합니다.

체크리스트

☐	확인 항목
☐	디렉토리명이 `experiment_topic + "_" + algorithm` 형식인가?
☐	model.yaml의 `experiment_topic`, `algorithm`과 디렉토리명이 일치하는가?
☐	`worker_id`가 `project.yaml`의 `workers_id` 목록에 있는가?
☐	S3 경로를 코드에서 직접 조립하고 있지 않은가?
☐	MLflow experiment/run을 직접 생성하고 있지 않은가?
☐	`model_dir_name`에 버전 suffix를 붙이고 있지 않은가? (버전은 run_id로 구분)