lightgbm

.gemini/pipeline-design.md

@@ -1,13 +1,35 @@
-# 파이프라인 실행 규칙
+# 파이프라인 실행 가이드
 
-모든 경로는 실행 시점에 인자로 지정하여 관리합니다.
+모든 실행은 프로젝트 루트 디렉토리에서 수행합니다.
 
-## 1. 학습 파이프라인 (`run_train.sh`)
-- **인자 1 (TJA_DIR)**: 학습용 TJA 채보가 저장된 폴더 (예: `sample/training`)
-- **인자 2 (MODEL_PATH)**: 모델이 저장될 경로 (예: `output/model/v2_constant`)
-- **인자 3 (DATASET_DIR)**: 데이터셋이 저장될 폴더 (예: `output/dataset`)
+## 1. 전처리 (Feature Extraction)
+TJA 파일들로부터 피처를 추출하여 `features.json`을 생성합니다.
+```bash
+bun run script/preprocess.ts --workingDir ./test --dataDir ./datas
+```
+- **--workingDir**: 결과물(`features.json`)이 저장될 폴더.
+- **--dataDir**: 원본 데이터(`tja/` 폴더)가 위치한 폴더.
 
-## 2. 예측 파이프라인 (`run_predict.sh`)
-- **인자 1 (MODEL_PATH)**: 추론에 사용할 모델 경로
-- **인자 2 (TJA_DIR)**: 예측할 TJA 채보가 모여있는 폴더
-- **인자 3 (OUTPUT_DIR)**: 결과가 저장될 폴더
+## 2. 모델 학습 (Training)
+추출된 피처와 상수 데이터를 사용하여 XGBoost 모델을 학습시킵니다.
+```bash
+python3 train/train_xgboost.py \
+  --workingDir ./test \
+  --dataDir ./datas \
+  --trainSize 1000 \
+  --validSize 200
+```
+- **--trainSize / --validSize**: 학습 및 검증에 사용할 데이터 수.
+
+## 3. 난이도 예측 (Inference)
+특정 곡 번호(`songno`)에 대한 난이도 상수를 예측합니다.
+```bash
+python3 predict/predict_xgboost.py --workingDir ./test --songno 1000
+```
+- **--songno**: 예측할 곡의 번호 (파일명 기준).
+
+## 주요 산출물 (in `workingDir`)
+- `features.json`: 추출된 피처 데이터셋.
+- `model.pkl`: 학습된 XGBoost 모델 파일.
+- `scaler.pkl`: 피처 정규화를 위한 Scaler 객체.
+- `features.txt`: 학습에 사용된 피처 이름 목록.