docs

docs/3-2.lightgbm.md

@@ -0,0 +1,41 @@
+# LightGBM 기반 난이도 상수 예측 모델
+
+이 문서는 프로젝트의 또 다른 학습 엔진인 LightGBM 모델의 구조, 하이퍼파라미터 및 특징을 설명합니다.
+
+## 1. 모델 개요
+**LightGBM (Light Gradient Boosting Machine)**은 트리 기반 학습 알고리즘으로, XGBoost와 유사하지만 'Leaf-wise' 트리 성장 방식을 사용하여 더 빠르고 메모리 효율적인 학습이 가능합니다. 특히 대규모 데이터셋에서 높은 성능을 발휘하며, 본 프로젝트에서는 XGBoost와의 비교 및 앙상블 가능성을 열어두기 위해 도입되었습니다.
+
+## 2. 하이퍼파라미터 설정
+`train/train_lightgbm.py`에 정의된 주요 설정값은 다음과 같습니다. XGBoost보다 더 깊고 복잡한 트리를 형성하도록 설정되어 있습니다.
+
+| 파라미터 | 설정값 | 설명 |
+| :--- | :--- | :--- |
+| `learning_rate` | 0.02 | 학습률. XGBoost(0.05)보다 낮게 설정하여 더 정밀하게 수렴 |
+| `num_leaves` | 63 | 하나의 트리가 가질 수 있는 최대 잎(Leaf) 수. 복잡한 패턴 학습에 유리 |
+| `n_estimators` | 3000 | 결정 트리의 개수. 충분한 학습을 위해 크게 설정 |
+| `feature_fraction`| 0.9 | 각 트리 학습 시 사용할 피처 비율 (과적합 방지) |
+| `bagging_fraction`| 0.8 | 데이터 샘플링 비율 |
+| `bagging_freq` | 5 | 배깅 수행 빈도 |
+| `early_stopping` | 100 | 검증 오차가 개선되지 않을 경우 학습을 조기 종료하는 라운드 수 |
+
+## 3. LightGBM 모델의 특징
+
+### A. Leaf-wise 성장 방식
+- 대부분의 boosting 알고리즘이 Level-wise(수평 성장) 방식을 사용하는 것과 달리, LightGBM은 **Leaf-wise(수직 성장)** 방식을 사용합니다. 
+- 이 방식은 손실(Loss)을 가장 많이 줄일 수 있는 잎 노드를 계속 분할하므로, 동일한 분할 횟수에서 Level-wise보다 더 낮은 손실을 달성할 수 있습니다.
+
+### B. 실행 속도 및 효율성
+- XGBoost 대비 학습 속도가 매우 빠르며 메모리 사용량이 적습니다.
+- 많은 양의 데이터를 처리할 때 이점이 큽니다.
+
+## 4. 학습 및 검증 프로세스
+XGBoost와 동일한 파이프라인을 따르며, 결과물은 다음과 같이 구분되어 저장됩니다.
+
+- **모델 파일**: `model_lgbm.pkl`
+- **스케일러**: `scaler_lgbm.pkl`
+- **피처 목록**: `features_lgbm.txt`
+- **검증 결과**: `validate.json`, `validate.png`
+
+## 5. 모델 평가
+- LightGBM은 하이퍼파라미터 변화에 민감하므로 과적합(Overfitting) 여부를 `validate.png`를 통해 상시 모니터링해야 합니다.
+- 현재 설정은 높은 `n_estimators`와 낮은 `learning_rate`를 통해 아주 미세한 채보의 차이까지 학습하는 것을 목표로 하고 있습니다.

docs/4. train script.md

@@ -0,0 +1,67 @@
+# 4. 학습 스크립트 (Training Script) 가이드
+
+이 문서는 `train/` 폴더 내의 학습 스크립트(`train_xgboost.py`, `train_lightgbm.py`)의 구조와 실행 과정을 설명합니다.
+
+## 1. 실행 구조 및 파라미터
+
+학습 스크립트는 명령행 인자(CLI Arguments)를 통해 제어됩니다.
+
+### 실행 예시
+```bash
+python3 train/train_xgboost.py \
+  --workingDir ./output/xgboost \
+  --dataDir ./datas \
+  --trainSize 1000 \
+  --validSize 200
+```
+
+### 파라미터 상세
+- `--workingDir`: 학습 결과물(`model.pkl`, `validate.json` 등)이 저장될 경로입니다.
+- `--dataDir`: 정답 데이터(`measure.csv`)가 위치한 경로입니다.
+- `--trainSize`: 전체 데이터셋 중 학습에 사용할 샘플 수입니다.
+- `--validSize`: 학습에 참여하지 않고 모델 평가(검증)에만 사용할 샘플 수입니다.
+
+## 2. 데이터 처리 및 학습 파이프라인
+
+스크립트 내부의 `train_model` 함수는 다음 순서로 동작합니다.
+
+### A. 데이터 로드 및 매칭
+1. `workingDir`에서 `features.json`(전처리된 피처)을 읽어옵니다.
+2. `dataDir`에서 `measure.csv`(정답 난이도)를 읽어옵니다.
+3. `(songno, difficulty)`를 키로 사용하여 두 데이터를 매칭하고 하나의 데이터셋으로 결합합니다.
+
+### B. 데이터셋 분리 (Train/Valid Split)
+1. 결합된 데이터셋을 `RANDOM_STATE(42)`를 기반으로 무작위로 섞습니다(Shuffle).
+2. 앞에서부터 `TRAIN_SIZE` 만큼을 학습 데이터로, 그 뒤의 `VALID_SIZE` 만큼을 검증 데이터로 엄격히 분리하여 모델의 일반화 성능을 보장합니다.
+
+### C. 정규화 (Scaling)
+1. `StandardScaler`를 사용하여 피처의 평균을 0, 분산을 1로 조정합니다.
+2. `CONTINUE_TRAINING` 옵션이 켜져 있고 기존 `scaler.pkl`이 있다면 이를 로드하여 일관성을 유지합니다.
+
+### D. 모델 학습 및 지속 학습 (Warm Start)
+1. 모델 객체를 생성하거나, 기존 `model.pkl`이 있다면 이를 로드합니다.
+2. 기존 모델이 있는 경우 이전 학습 상태를 유지한 채 새로운 데이터로 가중치를 미세 조정(Fine-tuning)합니다.
+
+## 3. 검증 및 결과 시각화
+
+학습 완료 직후, 모델이 학습 중에 보지 못한 검증 데이터셋(`X_valid`)을 사용하여 성능을 평가합니다.
+
+1. **지표 계산**: MAE(Mean Absolute Error)와 오차 범위 ±0.1 이내의 정확도를 산출합니다.
+2. **validate.json 저장**: 검증된 각 곡의 실제값, 예측값, 오차를 에러 절댓값 내림차순으로 저장합니다.
+3. **validate.png 생성**: 에러의 분포를 한눈에 볼 수 있도록 산점도 그래프를 생성합니다. (X축: 에러 크기 순, Y축: 에러 절댓값)
+
+## 4. 주요 산출물 (Outputs)
+
+학습이 성공하면 `workingDir` 폴더에 다음 파일들이 생성/업데이트됩니다.
+
+| 파일명 | 내용 |
+| :--- | :--- |
+| `model.pkl` | 학습된 모델 바이너리 |
+| `scaler.pkl` | 피처 정규화를 위한 Scaler 객체 |
+| `features.txt` | 학습에 사용된 피처 이름 목록 및 순서 |
+| `validate.json` | 검증 데이터셋에 대한 상세 예측 결과 (JSON) |
+| `validate.png` | 검증 에러 분포 시각화 그래프 (PNG) |
+
+## 5. 주의사항
+- `features.json`이 먼저 생성되어 있어야 학습이 가능합니다 (`preprocess.ts` 선행 필요).
+- `TRAIN_SIZE + VALID_SIZE`가 전체 가용 데이터 수보다 크면 오류가 발생합니다.